本文档属于 Cloud WAF — 企业 Web 防护管理平台
CLI 工具：zcloud · 6 大模块：auth / config / sys / guard / analytics / tools
完整 API 索引：/api/openapi.json · 文档地图：/sitemap.xml · AI 速读：/llms.txt

CLI 完整命令清单

zcloud 是什么

zcloud 是 Cloud WAF 平台官方 CLI，使用 Cobra 框架，覆盖管理控制台 100% 的核心运维操作，共 98 条命令分布在 6 大模块（auth / config / sys / guard / analytics / tools）。

二进制由后端 /api/cli/version 接口动态分发，支持 linux/darwin × amd64/arm64。

安装

参考 快速开始，或：

curl -fsSL <api_url>/api/cli/install.sh | sh
zcloud version

通用 flags

下列 flags 在所有命令上有效（继承自根命令）：

1. 认证命令（auth）

绑定 API：POST /api/auth/login / POST /api/auth/logout / GET /api/auth/userinfo / GET\|POST\|DELETE /api/sys/api-keys[/<id>] / PUT /api/sys/api-keys/<id>/renew / POST /api/sys/api-keys/revoke-all / GET /api/sys/api-keys/<id>/logs / GET /api/sys/api-keys/<id>/stats

API Key 调用约定：请求头使用 Authorization: ApiKey zck_<prefix>.<secret>（与 Bearer session 并行的双通道）。effective_perms = user.RBAC ∩ key.scope，scope 为空 = 完整继承 user 权限。

2. 配置命令（config）

创建 profile 后，请用 zcloud --profile <name> config set api_url <URL> 单独写入 api_url 等配置；
profiles create 命令本身只接收一个位置参数 <name>，不接受任何 flag。

config 命令均为 local 操作，不调用后端 API。

3. sys 模块（系统管理）

3.1 用户管理 sys users

3.1.1 僵尸微信绑定治理 sys wx-zombies

安全约束：默认使用微信 user/get 关注者列表做差集，不逐个调用 user/info；达到 --max-pages 会中止，避免误清理。若微信关注者列表为空但本地存在绑定，默认拒绝 --apply，除非显式加 --allow-empty-followers。

3.2 角色管理 sys roles

3.3 OEM 管理 sys oems

3.4 会话管理 sys sessions

3.5 审计日志 sys audit-logs

4. guard 模块（Web 防护）

4.1 域名 guard domains

4.2 证书 guard certs

4.3 策略 guard policies

4.4 黑白名单 guard bwlist

4.5 WAF 规则 guard waf

4.6 转发 guard forwards

4.7 调度管理 guard schedules

本组命令只做 DNS 解析调度（切换源站/节点、一键启停、批量启停记录）。不直接调用三方 DNS API，所有写操作通过 NSQ topic=dns 通知 zdns 服务异步生效。必须用 affairs 子命令轮询事务最终状态（AffairsStatus_Start → Succeed / Faild）。

4.8 下发 guard applies

5. analytics 模块（统计大屏）

通用 flags（适用于所有 analytics <page> 命令；不显式指定时不会进入 query string，由后端使用默认值）：

各页面 chart-key 清单：

5.1 2026-04-30 chart-rebuild 6 phase 扩展（4 page + 2 独立子命令组）

Phase 4 模板枚举（--template）：protection-value / asset-risk / attack-source / business-health / platform-summary（仅平台运维/超管） / raw-log-export。

真值字段约束（cross-cutting D3/D8/D10）：

• --z-final-action 取值仅 0=放行 / 1=拦截 / 2=验证码；--z-white 是独立 bool 字段（白名单命中），不参与 action 枚举。
• 缓存指标固定使用 total_cache_count / total_cache_bytes / total_cache_response_bytes 三字段（禁 cache_count / cache_bytes）。
• 处置字段固定使用 process_uid / process_time / status / level（禁 handle_user / handle_time / risk_score）。

占位兜底：部分 chart-key 当前服务端返回 {available: false, reason: "数据源待接入..."}；接口/CLI 契约稳定，业务 SQL/ES 真接入按 chart-key 滚动落地。

6. 套餐目录（plan）

对外范围说明：仅以下两个只读命令对外公开。套餐的创建/编辑/删除、为用户开通、订阅查询属平台控制台管理操作，直接操作在线计费数据，不在对外对接 API/CLI 范围（仅平台运维经控制台 + RBAC 使用）。

示例

# 列出 WAF 类型套餐
zcloud plan list --prod-type 1 --format json

# 搜索套餐名称含"基础版"的套餐
zcloud plan list --keyword 基础版

# 查看指定套餐详情
zcloud plan describe 550e8400-e29b-41d4-a716-446655440000

绑定 API：GET /api/plan/plans / GET /api/plan/plans/:id

7. cli_release / tools

后端发布相关 API：GET /api/cli/version（公开） / GET /api/cli/install.sh（公开）。

8. 节点安装 / 升级（命令行）

CLI 豁免说明（规则 5）：节点安装 / 升级没有 zcloud node ... 子命令，zcloud 当前仅有 auth / config / sys / guard / analytics / plan 六个命令组。节点链路的"命令行"是平台生成的一次性安装一行命令（在目标节点主机上以 root 执行）+ 管理面 HTTP 接口。完整接口语义见 API 文档 §8 节点安装 / 升级。

8.1 一键安装 / 升级命令（节点主机执行）

平台 POST /api/node/install/commands（升级用 /upgrades）返回的 command 形如：

curl -fsSL --connect-timeout 10 --max-time 60 \
  -H 'Authorization: Bearer nit_xxx' 'https://<cloud>/api/node/install/script' \
  | sudo bash -s -- --token 'nit_xxx' --server 'https://<cloud>'

脚本参数 / 环境变量：

脚本行为：校验依赖（curl/tar/gzip/sha256sum）→ 下载 package 并校验 X-Artifact-SHA256 → 拉取 env 覆盖包内 env.conf → 执行 install.sh → 经 /report 回报 running/success/failed。所有下载带 --retry，回报调用短超时。

8.2 管理操作（curl / API）

要点：max_uses 最低 5 / 默认 20 / 上限 100（保留重试余量）；ttl_seconds 默认 3600 / 上限 86400；明文 token 只展示一次、库中仅存 hash + prefix；安装机侧鉴权失败返回 401 + challenge；script 不消耗次数、package/env 消耗 use_count、report 用独立 report_count 且 success 才置 token used。详见 API §8。

完整命令树

zcloud
├── auth         (login / logout / info)
├── config       (set / get / list / profiles[list,create,activate,delete])
├── sys
│   ├── users    (list / describe / create / update / delete / reset-password / lock / assign-roles)
│   ├── roles    (list / create / update / delete / get-permissions / set-permissions)
│   ├── oems     (list / describe / create / update / delete / get-setting / set-setting)
│   ├── sessions (list / kill)
│   └── audit-logs (list / login-records list / permissions)
├── guard
│   ├── domains  (list / describe / create / update / delete / get-settings / set-settings)
│   ├── certs    (list / describe / upload / update / delete / bind / unbind)
│   ├── policies (list / describe / create / update / delete)
│   ├── bwlist   (sets[*] / ips[*])
│   ├── waf      (rules[*])
│   ├── forwards (list / create / update / delete)
│   ├── schedules(domains / switch-mode / init / reset / records / batch-status / open / close / affairs / affair)
│   └── applies  (list / describe / create / detail / retry / quit)
├── analytics    (overview / access / protect / ai / bot / alert / glossary / batch / export / ack / session)
├── plan         (list / describe)  [只读对外]
├── update
├── completion
└── version

相关文档

• API 文档 — 命令对应的 REST 接口
• 认证说明 — profile / 401 重试机制
• 权限矩阵 — 命令所需权限 key

Cloud WAF · zcloud CLI · 共 98 条命令，源数据来自 src/frontend/src/views/docs/cli-commands.ts