跳到內容
多雲網路

Debug API

擷取時間為 2026-07-28，來源為本部署環境的一個 CE。sitecli/capture-manifest.json 記錄了來源節點，而 scripts/capture-sitecli.sh --check 會針對線上 CE 重新驗證指令 介面。

vpm/debug API 會在已註冊的節點上執行 Site CLI 指令並回傳其輸出。以下所有內容都是 針對線上節點實測建立的；上游並未發布任何相關資料。

指令目錄具有自我描述能力

Section titled “指令目錄具有自我描述能力”

向 exec-user 發出 POST 請求並省略 command 鍵，即可詢問節點支援哪些指令：

Terminal window
curl -sS -X POST \
  -H "Authorization: APIToken $XCSH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"namespace":"system","site":"<site>","node":"<node>"}' \
  "$XCSH_API_URL/api/operate/namespaces/system/sites/<site>/vpm/debug/<node>/exec-user" \
  | jq -r .output | jq .

回應是一個以指令名稱為鍵的 JSON 物件：

{
  "crictl-inspect": ["System Troubleshooting", "ExecUser", " container-id"],
  "diagnosis":      ["System Troubleshooting", "ExecUser", "no argument needed", "GLOBAL"],
  "ip-link-set":    ["Network Troubleshooting", "Exec", " (<device>||<group>) (up||down)"]
}

每個項目的格式為 [category, tier, exampleArgument?, scope?]，而這些欄位並不只是 說明文件——它們決定了該指令必須以何種方式呼叫。

三種傳輸方式，由目錄項目決定

Section titled “三種傳輸方式，由目錄項目決定”
條件方法與路徑請求主體回傳
scope 為 GLOBALGET .../vpm/debug/global/<cmd>無JSON
tier 為 ExecUserPOST .../vpm/debug/<node>/exec-usercommand 陣列文字
tier 為 ExecPOST .../vpm/debug/<node>/execcommand 陣列文字

ExecUser — 唯讀層級 31 個指令

Section titled “ExecUser — 唯讀層級 ”

最常見的情況。將指令與其參數以陣列傳遞，指令名稱放在第一個：

Terminal window
curl -sS -X POST \
  -H "Authorization: APIToken $XCSH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"namespace":"system","site":"<site>","node":"<node>","command":["crictl-ps"]}' \
  "$XCSH_API_URL/api/operate/namespaces/system/sites/<site>/vpm/debug/<node>/exec-user"
{ "return_code": 0, "output": "CONTAINER    IMAGE    CREATED    STATE ..." }

參數必須是各自獨立的陣列元素，而非單一字串：

{ "command": ["journalctl", "-u", "vpm", "-n", "200"] }

GLOBAL — 全站範圍，且傳輸方式完全不同 2 個指令

Section titled “GLOBAL — 全站範圍，且傳輸方式完全不同 ”

health 與 diagnosis 是唯二的兩個指令。它們是對 global 路徑發出的 GET 請求， 不接受任何參數，並回傳結構化 JSON 而非終端機文字。

Terminal window
curl -sS -H "Authorization: APIToken $XCSH_API_TOKEN" \
  "$XCSH_API_URL/api/operate/namespaces/system/sites/<site>/vpm/debug/global/health" | jq .

Exec — 特權層級 此版本上有 1 個指令

Section titled “Exec — 特權層級 ”

這是一個獨立的端點，而且層級限制是強制執行而非建議性的：exec 會以相同的 command not supported 訊息拒絕 ExecUser 指令。此層級的每個成員都會變更節點狀態， 或讀取某個狀態標記。

在此租戶所執行的版本上，該層級僅包含 ip-link-set。較新的版本另外加入了 systemctl-restart-NetworkManager、systemctl-restart-crio、 systemctl-restart-kubelet、systemctl-start-crio-prune 以及三個 marker-exists-* 指令。

尋找站台與節點名稱

Section titled “尋找站台與節點名稱”

節點名稱就是 Azure VM 名稱，而 list-service 是一個成本低廉的方式，可以在確認節點名稱 的同時一併看到其上執行的服務：

Terminal window
curl -sS -H "Authorization: APIToken $XCSH_API_TOKEN" \
  "$XCSH_API_URL/api/operate/namespaces/system/sites/<site>/vpm/debug/global/list-service" \
  | jq -r '[.service[].node] | unique'
["", "f5-xc-ce-vm-01"]

有些服務回報的節點名稱是空的，因此該清單中的空字串是回應本身的產物，而不是第二個節點。 list-service 也不在那 34 個指令的目錄中：它是一個目錄未公告的 global 端點，這也是 為什麼它記錄在此處而非指令參考中。

重現本儲存庫的擷取結果

Section titled “重現本儲存庫的擷取結果”

每個指令頁面都嵌入了由 scripts/capture-sitecli.sh 擷取的輸出，該腳本實作了上述三項 規則。

  1. 將它指向某個租戶。它會讀取 XCSH_API_URL 與 XCSH_API_TOKEN，或退回使用目前 作用中的 xcsh 內容。

  2. 重新整理目錄，並確認節點沒有在文件底下發生變動：

    Terminal window
    bash scripts/capture-sitecli.sh --check

    這只會比較已提交的目錄與軟體版本。它會將版本變更與新增或移除的指令分開回報。

  3. 當你需要最新的證據時重新擷取：

    Terminal window
    bash scripts/capture-sitecli.sh