跳转到内容
多云网络

调试 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