讓 Claude Code 部署與排查 Zenavo 專案

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

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

如果你只想在瀏覽器裡直接問 AI，不用在本機安裝任何工具，可以直接點控制台右側邊緣的 Zenavo Agent：它能自動識別你目前開啟的頁面、讀取日誌與部署紀錄，並透過頁面上的確認卡片幫你部署、回滾、重新啟動或設定環境變數。本文介紹的是把同樣的能力接進你本機的 Claude Code。

1. 安裝並登入 zenavo-mcp

從 zenavo-mcp Releases 下載對應系統的執行檔，放進 PATH 後在終端機執行：

zenavo-mcp login

瀏覽器會開啟裝置授權頁面。核對終端機顯示的驗證碼後，選擇你要授予的權限範圍：

• 唯讀（Read-only）：只能看專案、服務狀態、部署紀錄、日誌與環境變數名稱（看不到變數明文），適合日常排查問題；
• 部署（Deploy）：在唯讀基礎上，允許觸發部署、重新啟動服務、回滾版本與修改環境變數。

同時在專案範圍裡選擇 僅限部分專案，只勾選手頭正在開發的專案。授權完成後，權杖會儲存在本機，不需要把任何 API Key 貼到聊天視窗裡。

接著在 Claude Code 中安裝 Zenavo 外掛（內含 MCP 設定以及部署、排障、回滾、變數管理等 Skills）：

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

如果你只需要單純的 MCP 連線，也可以直接執行 claude mcp add zenavo -- zenavo-mcp。其他用戶端（Cursor、Windsurf 等）的串接方式見 AI 智慧體文件與 Skills 頁面。

2. 查看專案狀態與部署紀錄

先發一條唯讀指令，確認它連上了你的專案：

查看我在 Zenavo 上的專案，列出各個服務的執行狀態和最近一次部署結果。

Claude Code 會呼叫 MCP 列出服務、目前狀態（Running / Crashed 等）以及最近的建置與部署任務。

出於安全設計，MCP 不會回傳環境變數的明文值（只回傳變數名稱），也不能直接讀取資料庫裡的資料列或下載備份檔。這樣即使你在排障時把上下文發給模型，也不會外洩密鑰與客戶資料。

3. 用日誌定位建置或啟動失敗

當某個服務部署失敗或反覆重啟時，不用自己去一頁頁翻日誌，直接讓它按階段排查：

檢查 web 服務最近一次失敗的部署。
看日誌判斷是卡在相依套件安裝、程式碼建置、容器啟動還是健康檢查，貼出關鍵報錯並給出修改建議。

拿到具體原因後，就能對症處理：

• 相依套件或建置報錯：直接在本機讓 Claude Code 改好程式碼、跑通建置，提交並推送到 GitHub；
• 缺少環境變數：讓它在你確認後幫你補上變數並重新啟動服務；
• 連接埠或健康檢查不符：核對程式碼實際監聽的連接埠（需監聽 0.0.0.0）是否與服務的 HTTP 連接埠一致。

4. 觸發部署與驗證

需要手動觸發發布時，可以直接說：

部署測試專案裡的 web 服務，跟進到建置和滾動更新結束，然後檢查啟動日誌有沒有報錯。

注意：Zenavo 部署的是該服務綁定的遠端 Git 分支或 Docker 映像檔。你本機改了但還沒 git push 的程式碼，需要先推送到儲存庫，再讓它觸發部署。

凡是涉及修改的操作（部署、重新啟動、改變數、回滾），Claude Code 都會先向你展示要執行的參數並請求確認。

5. 出問題時快速回滾

如果剛上線的新版本有問題，可以讓它回退到上一個正常版本：

查看 web 服務的部署歷史，找到上一次成功的版本，幫我回滾過去並確認服務恢復正常。

回滾前留心一件事：服務回滾只恢復當時的應用程式映像檔與環境變數，不會回滾資料庫結構或磁碟區（詳見回滾文件）。如果這次發布同時執行了不向後相容的資料庫遷移，先確認舊版程式碼能否在目前資料庫結構下正常運作。

6. 稽核日誌與收回權限

透過 MCP 執行的每一次部署、重新啟動、回滾與變數修改，都會記錄在控制台的稽核日誌裡。

zenavo-mcp login 建立的授權金鑰在控制台 帳戶 → API 金鑰 中以 MCP on <電腦名稱> 命名，預設效期 90 天。換電腦或不再需要時，隨時可以在頁面上刪掉它，立即撤銷存取權限。

常見問題

它能幫我買伺服器、刪專案或看資料庫裡的資料表嗎？ 不能。Zenavo MCP 刻意不包含購買或銷毀伺服器、刪除專案、改帳單、進入容器終端機、讀資料庫內容與下載備份等高風險操作，這些操作只能在控制台由人完成。

裝好外掛後提示看不到專案？ 先確認終端機裡執行過 zenavo-mcp login，並檢查授權時勾選的專案清單是否包含目前專案。想新增授權專案時，重新執行一次 zenavo-mcp login 即可。

唯讀模式與部署模式怎麼選？ 建議正式環境日常用唯讀授權，讓 Claude Code 幫你看日誌、查狀態、寫修復程式碼；開發或測試專案再開啟部署權限，讓它一條龍完成「改程式碼 → 推送 → 部署 → 看日誌驗證」。

控制台內建的 Zenavo Agent 與 Claude Code MCP 有什麼差別？ Zenavo Agent 內建在網頁控制台裡（Dev、Pro、Team 方案分別包含每月 30、100、300 點額度），打開服務頁面就能直接問原因、點確認卡片改設定，不需要本機環境。Claude Code + zenavo-mcp 則跑在你的本機終端機裡，適合一邊看線上報錯日誌、一邊直接改本機程式碼並推送重部署。如果你想在 Claude Code 裡自由切換 DeepSeek 等模型或統一管理團隊額度，還可以搭配在 Zenavo 上自架 Magpie 或 New API 閘道，並把同一個閘道串接給團隊共用的 Open WebUI 或 LobeHub。

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