前言¶
在 DSH 裏做運維或巡檢時，Agent 往往需要讀主機狀態、拉日誌或在受控範圍內執行一次性命令。若監控面板與智能體環境彼此隔離，通常要單獨寫腳本、維護 API 憑據，再把能力手工掛到工具列表上。哪吒監控（Nezha Monitoring）V2 內置 MCP 服務，可通過 POST /mcp 暴露服務器清單、遠程執行與文件操作等工具；dsh-nezha 由維護者 kaecho 提供，負責把該端點接到 DeepSeek Harness，並在插件詳情頁用可視化表單管理地址與 PAT。下面按安裝、配置與工具命名說明用法。
插件定位¶
dsh-nezha（GitHub：kaecho/dsh-nezha）是 DSH 客戶端類插件：連接 Nezha Dashboard 的 MCP 端點，使用 Authorization: Bearer nzp_... 認證。當前版本爲 0.1.0，許可證 MIT。運行要求爲 DSH >=0.2.1-rc.2、Node.js >=22（開發與打包；DSH 運行時自帶 Node），以及已開啓 MCP 的 Nezha V2。
插件無運行時外部依賴，無需額外構建。保存配置後會自動執行 MCP initialize、notifications/initialized 和 tools/list，並將 Nezha 工具動態註冊到 DSH，統一命名爲 mcp__nezha__<tool>。
環境準備¶
在接入插件之前，需要同時滿足 DSH、Nezha 與網絡三側條件。
| 項目 | 要求 |
|---|---|
| DeepSeek Harness | >=0.2.1-rc.2 |
| Nezha | V2，且 enable_mcp: true |
| 認證 | Nezha API Token（PAT），以 nzp_ 開頭；不能使用瀏覽器登錄 JWT |
| 網絡 | DSH 所在主機能通過 HTTP(S) 訪問 Dashboard 的 /mcp |
| 反向代理 | 允許 POST /mcp，轉發 Authorization，請求體上限至少 8 MiB |
Nezha 的 MCP 默認關閉。在 Dashboard 配置中開啓後需重啓或重新加載，使 /mcp 生效：
enable_mcp: true
核心能力¶
- 連接與註冊：對接
POST /mcp；啓動或保存配置後拉取tools/list並註冊到 DSH。 - Web UI 設置：在插件詳情頁（
plugins.bundle.config）配置 Dashboard 地址、PAT、啓用/停用、超時；支持測試連接、保存、刷新工具、清除已保存令牌。 - 錯誤可讀化：連接失敗、認證失敗、權限不足、404、限流和超時會轉換爲可讀提示。
- 憑據分離：PAT 寫入 DSH 憑據記錄
dsh-nezha/token；普通設置文件僅含url、enabled、timeoutMs。 - 傳輸形態：兼容 JSON 與 SSE 形式的 MCP 響應；Nezha 當前爲 POST 請求/響應模式，不依賴長連接 SSE。
安裝與啓用¶
當前版本以 GitHub Release 的 .tgz 和本地目錄安裝爲主，尚未發佈到 npm。資料中未給出 dsh plugin add github:... 一類命令，應在 DSH Web UI 的 Plugins / 插件 頁面添加。
從本地目錄安裝（開發/自用推薦）¶
- 將本倉庫放到 DSH 所在主機，例如
/path/to/dsh-nezha。 - 在插件頁選擇添加插件，在「包名或地址」中填寫該目錄的絕對路徑。
- 安裝並保持啓用；若提示
restart-required，重啓 DSH 後再打開插件詳情頁。
從本地 .tgz 安裝¶
在倉庫根目錄執行：
npm pack
會生成 dsh-nezha-0.1.0.tgz。在 DSH 插件頁選擇從本地安裝，指向該文件即可；插件無外部依賴，安裝時不需要執行依賴構建腳本。
從 npm 安裝（發佈後）¶
發佈到 npm 後，可在「包名或地址」中填寫 dsh-nezha 按包名安裝。
安裝完成後，插件列表中應出現標題爲 Nezha MCP / 哪吒 MCP 的條目。
首次配置¶
- 打開 Plugins / 插件，進入
dsh-nezha詳情頁。 - 在配置區填寫：
| 字段 | 說明 |
|---|---|
| Dashboard 地址 | 可填 https://nezha.example.com 或含路徑/完整 /mcp 的 URL；插件會規範化爲 /mcp。勿帶用戶名、密碼、查詢參數或片段。 |
| API Token / PAT | 以 nzp_ 開頭；留空表示保留已保存令牌。 |
| 啓用 | 關閉則不連接、不註冊工具。 |
| 超時 | 單次 MCP 請求 5–300 秒，默認 60 秒；長耗時 server.exec 需調大並同步反向代理超時。 |
- 點擊 測試連接：對當前表單地址與 PAT（PAT 留空則用已保存值）執行
initialize與tools/list，不保存配置、不執行命令或文件操作。 - 點擊 保存並連接：寫入 profile 設置與憑據，自動重連並刷新工具。
- Nezha 側 PAT scope、白名單或版本變更後，使用 刷新工具 重新讀取
tools/list。 - 撤銷本地 PAT：勾選 清除已保存的 PAT（保存時生效） 後保存。
非機密配置落在當前 profile 目錄下 <profile>/dsh-nezha/settings.json（由環境變量 DSH_PROFILE_DIR 指向的 profile 目錄決定）。
Agent 側工具命名與權限¶
DSH 註冊名格式爲 mcp__nezha__<tool>。Nezha 原始名中的點號會替換爲下劃線，例如：
| Nezha 原始工具 | DSH 工具名 |
|---|---|
server.list |
mcp__nezha__server_list |
server.exec |
mcp__nezha__server_exec |
fs.read |
mcp__nezha__fs_read |
在 Nezha Dashboard 的 API / API Token（PAT） 頁面創建 Token，按需選擇 scope 與服務器 ID 白名單。Scope 與工具對應關係（節選）：
| Scope | 可用的工具 |
|---|---|
| 任意有效 PAT | meta.whoami |
nezha:inventory:read |
server.list |
nezha:server:read |
server.get、fs.list、fs.read、fs.download_url |
nezha:server:exec |
server.exec |
nezha:server:write |
fs.write、fs.upload_url |
nezha:server:delete |
fs.delete |
建議最小權限：僅巡檢用 nezha:inventory:read 與 nezha:server:read；需要遠程執行再開 nezha:server:exec；寫刪文件再開 write/delete，並對高風險 scope 限制服務器白名單與有效期。官方說明見 Nezha MCP 指南 與 API Token（PAT）。
典型用法思路¶
配置完成且狀態爲已連接後，Agent 即可調用 mcp__nezha__* 工具。具體參數以 Nezha 返回的 inputSchema 爲準。常見組合包括：
- 用
mcp__nezha__meta_whoami確認當前 Token 的 scope 與白名單。 - 用
mcp__nezha__server_list、mcp__nezha__server_get做資產與狀態快照。 - 用
mcp__nezha__fs_list、mcp__nezha__fs_read讀目錄與小段日誌。 - 在明確授權下使用
mcp__nezha__server_exec執行非交互式一次性命令（Nezha 側默認超時 30 秒，最大 300 秒）。 - 大文件可用
mcp__nezha__fs_download_url/mcp__nezha__fs_upload_url生成一次性 URL（默認有效期約 300 秒，單文件上限 100 MiB）；需正確配置 Nezha 的dashboard_host。
工具列表隨 Nezha 實例的 tools/list 變化，不同版本可能略有差異。
適用場景與注意¶
適合：已在用 Nezha V2 做監控，希望在 DSH Agent 中直接調用官方 MCP 能力、並希望通過 Web UI 管理端點與 PAT 的團隊。
安全與運行方式：
- 生產環境使用 HTTPS；
server.exec與fs.write/fs.delete等屬於高風險操作，應結合 DSH 工具權限與確認機制，並遵循最小 PAT scope。 - 插件在 DSH 進程權限下運行；安裝前應查看倉庫源碼與 MIT 許可證，並保護好 profile 目錄、備份與憑據存儲。
- 不再使用時在 Nezha 撤銷 PAT，並在插件設置頁清除已保存令牌。
常見故障（細節見倉庫 README）：401 多爲 PAT 無效或誤用 JWT；403 檢查 scope 與白名單後 刷新工具；404 檢查 enable_mcp、反向代理是否轉發 POST /mcp；超時需同時調整插件超時與反向代理讀超時；429 需注意 Nezha 對 Token 的限流（約每秒 10 次、每分鐘 120 次）。
結尾¶
dsh-nezha 把哪吒 V2 內置 MCP 接到 DSH，用可視化配置完成端點與 PAT 管理，並把 Nezha 工具以 mcp__nezha__* 形式暴露給 Agent。社區目錄頁：https://www.skillhub.cn/plugins/kaecho/dsh-nezha；源碼與完整故障排查：https://github.com/kaecho/dsh-nezha。
