---
title: "讓 Claude Code 部署與排查 Zenavo 專案"
description: "為 Claude Code 串接 Zenavo MCP 與 Skills，按專案限定權限，在終端機裡一句話查看服務狀態、調閱報錯日誌、觸發部署或安全回滾。"
date: 2026-11-10
language: zh-TW
url: https://zenavo.app/zh-TW/blog/claude-code-deploy-debug
---

# 讓 Claude Code 部署與排查 Zenavo 專案

改完程式碼準備上線，或是線上服務突然啟動失敗時，你通常要在終端機和瀏覽器控制台之間來回切換：找專案、點部署、等建置、翻日誌。

把 Zenavo 的 MCP 與 Skills 接進 Claude Code 後，這些事可以直接在同一個終端機對話裡完成——例如直接對它說：「看看 `web` 服務最近一次部署為什麼失敗了，把報錯日誌找出來並給我修復建議。」

> 如果你只想在瀏覽器裡直接問 AI，不用在本機安裝任何工具，可以直接點控制台右側邊緣的 **[Zenavo Agent](https://docs.zenavo.app/zh-TW/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-TW/ai-agents)與 [Skills 頁面](https://zenavo.app/zh-TW/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-TW/operations/rollbacks)）。如果這次發布同時執行了不向後相容的資料庫遷移，先確認舊版程式碼能否在目前資料庫結構下正常運作。

## 6. 稽核日誌與收回權限

透過 MCP 執行的每一次部署、重新啟動、回滾與變數修改，都會記錄在控制台的[稽核日誌](https://docs.zenavo.app/zh-TW/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-TW/zenavo-agent) 內建在網頁控制台裡（Dev、Pro、Team 方案分別包含每月 30、100、300 點額度），打開服務頁面就能直接問原因、點確認卡片改設定，不需要本機環境。Claude Code + `zenavo-mcp` 則跑在你的本機終端機裡，適合一邊看線上報錯日誌、一邊直接改本機程式碼並推送重部署。如果你想在 Claude Code 裡自由切換 DeepSeek 等模型或統一管理團隊額度，還可以搭配在 Zenavo 上自架 [Magpie](https://zenavo.app/zh-TW/blog/self-host-magpie) 或 [New API](https://zenavo.app/zh-TW/blog/self-host-new-api) 閘道，並把同一個閘道串接給團隊共用的 [Open WebUI](https://zenavo.app/zh-TW/blog/self-host-open-webui) 或 [LobeHub](https://zenavo.app/zh-TW/blog/self-host-lobehub)。

先在一個測試專案上試試：執行 `zenavo-mcp login`，裝好 `zenavo@zenavo` 外掛，讓 Claude Code 幫你查一次日誌或發一次版。