---
title: "让 Claude Code 部署和排查 Zenavo 项目"
description: "为 Claude Code 接入 Zenavo MCP 和 Skills，按项目限定权限，在终端里一句话查看服务状态、拉取报错日志、触发部署或安全回滚。"
date: 2026-11-10
language: zh-CN
url: https://zenavo.app/zh-CN/blog/claude-code-deploy-debug
---

# 让 Claude Code 部署和排查 Zenavo 项目

改完代码准备上线，或者线上服务突然启动失败时，你通常要在终端和浏览器控制台之间来回切换：找项目、点部署、等构建、翻日志。

把 Zenavo 的 MCP 和 Skills 接进 Claude Code 后，这些事可以直接在同一个终端对话里完成——比如直接对它说：“看看 `web` 服务最近一次部署为什么失败了，把报错日志找出来并给我修复建议。”

> 如果你只想在浏览器里直接问 AI，不用在本地装任何工具，可以直接点控制台右侧边缘的 **[Zenavo Agent](https://docs.zenavo.app/zh-CN/zenavo-agent)**：它能自动识别你当前打开的页面、读取日志和部署记录，并通过页面上的确认卡片帮你部署、回滚、重启或设置环境变量。这篇文章讲的是把同样的能力接进你本地的 Claude Code。

## 1. 安装并登录 `zenavo-mcp`

从 [zenavo-mcp Releases](https://github.com/Zenavo-App/zenavo-mcp/releases) 下载对应系统的二进制文件，放进 `PATH` 后在终端运行：

```sh
zenavo-mcp login
```

浏览器会打开设备授权页面。核对终端显示的验证码后，选择你要授予的权限范围：

- **只读（Read-only）**：只能看项目、服务状态、部署记录、日志和环境变量名称（看不到变量明文），适合日常排查问题；
- **部署（Deploy）**：在只读基础上，允许触发部署、重启服务、回滚版本和修改环境变量。

同时在项目范围里选择 **仅限部分项目**，只勾选手头正在开发的项目。授权完成后，令牌保存在本机，不需要把任何 API Key 粘贴到聊天窗口里。

接着在 Claude Code 中安装 Zenavo 插件（内含 MCP 配置以及部署、排障、回滚、变量管理等 Skills）：

```sh
claude plugin marketplace add Zenavo-App/zenavo-skills
claude plugin install zenavo@zenavo
```

如果你只需要裸 MCP 连接，也可以直接运行 `claude mcp add zenavo -- zenavo-mcp`。其他客户端（Cursor、Windsurf 等）的接入方式见 [AI 智能体文档](https://docs.zenavo.app/zh-CN/ai-agents)和 [Skills 页面](https://zenavo.app/zh-CN/skills)。

## 2. 查看项目状态与部署记录

先发一条只读指令，确认它连上了你的项目：

```text
查看我在 Zenavo 上的项目，列出各个服务的运行状态和最近一次部署结果。
```

Claude Code 会调用 MCP 列出服务、当前状态（Running / Crashed 等）以及最近的构建和部署任务。

出于安全设计，**MCP 不会返回环境变量的明文值**（只返回变量名），也**不能直接读取数据库里的行或下载备份文件**。这样即使你在排障时把上下文发给模型，也不会泄露密钥和客户数据。

## 3. 用日志定位构建或启动失败

当某个服务部署失败或反复重启时，不用自己去一页页翻日志，直接让它按阶段排查：

```text
检查 web 服务最近一次失败的部署。
看日志判断是卡在依赖安装、代码构建、容器启动还是健康检查，贴出关键报错并给出修改建议。
```

拿到具体原因后，就能对症处理：

- **依赖或构建报错**：直接在本地让 Claude Code 改好代码、跑通构建，提交并推送到 GitHub；
- **缺少环境变量**：让它在确认后帮你补上变量并重启服务；
- **端口或健康检查不匹配**：核对代码实际监听的端口（需监听 `0.0.0.0`）是否与服务的 HTTP 端口一致。

## 4. 触发部署与验证

需要手动触发发布时，可以直接说：

```text
部署测试项目里的 web 服务，跟进到构建和滚动更新结束，然后检查启动日志有没有报错。
```

注意：**Zenavo 部署的是该服务绑定的远端 Git 分支或 Docker 镜像**。你本地改了但还没 `git push` 的代码，需要先推送到仓库，再让它触发部署。

凡是涉及修改的操作（部署、重启、改变量、回滚），Claude Code 都会先向你展示要执行的参数并请求确认。

## 5. 出问题时快速回滚

如果刚上线的新版本有问题，可以让它回退到上一个正常版本：

```text
查看 web 服务的部署历史，找到上一次成功的版本，帮我回滚过去并确认服务恢复正常。
```

回滚前留心一件事：**服务回滚只恢复当时的应用镜像和环境变量，不会回滚数据库结构或数据卷**（详见[回滚文档](https://docs.zenavo.app/zh-CN/operations/rollbacks)）。如果这次发布同时执行了不向后兼容的数据库迁移，先确认旧版代码能否在当前数据库结构下正常工作。

## 6. 审计日志与收回权限

通过 MCP 执行的每一次部署、重启、回滚和变量修改，都会记录在控制台的[审计日志](https://docs.zenavo.app/zh-CN/account/audit-log)里。

`zenavo-mcp login` 创建的授权密钥在控制台 **账户 → API 密钥** 中以 `MCP on <电脑名>` 命名，默认有效期 90 天。换电脑或不再需要时，随时可以在页面上删掉它，立即吊销访问权限。

## 常见问题

**它能帮我买服务器、删项目或看数据库里的表吗？**
不能。Zenavo MCP 故意不包含购买或销毁服务器、删除项目、改账单、进容器终端、读数据库内容和下载备份等高风险操作，这些操作只能在控制台由人完成。

**装好插件后提示看不到项目？**
先确认终端里跑过 `zenavo-mcp login`，并检查授权时勾选的项目列表是否包含当前项目。想新增授权项目时，重新运行一次 `zenavo-mcp login` 即可。

**只读模式和部署模式怎么选？**
建议生产环境日常用**只读**授权，让 Claude Code 帮你看日志、查状态、写修复代码；开发或测试项目再开启**部署**权限，让它一条龙完成“改代码 → 推送 → 部署 → 看日志验证”。

**控制台自带的 Zenavo Agent 和 Claude Code MCP 有什么区别？**
[Zenavo Agent](https://docs.zenavo.app/zh-CN/zenavo-agent) 内置在网页控制台里（Dev、Pro、Team 方案分别包含每月 30、100、300 积分），打开服务页面就能直接问原因、点确认卡片改配置，不需要本地环境。Claude Code + `zenavo-mcp` 则跑在你的本地终端里，适合一边看线上报错日志、一边直接改本地代码并推送重部署。如果你想在 Claude Code 里自由切换 DeepSeek 等模型或统一管理团队额度，还可以配合在 Zenavo 上自建 [Magpie](https://zenavo.app/zh-CN/blog/self-host-magpie) 或 [New API](https://zenavo.app/zh-CN/blog/self-host-new-api) 网关，并把同一个网关接给团队共用的 [Open WebUI](https://zenavo.app/zh-CN/blog/self-host-open-webui) 或 [LobeHub](https://zenavo.app/zh-CN/blog/self-host-lobehub)。

先在一个测试项目上试试：运行 `zenavo-mcp login`，装好 `zenavo@zenavo` 插件，让 Claude Code 帮你查一次日志或发一次版。