> **本文档属于 Cloud WAF — 企业 Web 防护管理平台**
> CLI 工具：`zcloud` · 6 大模块：auth / config / sys / guard / analytics / tools
> 完整 API 索引：[/api/openapi.json](/api/openapi.json) · 文档地图：[/sitemap.xml](/sitemap.xml) · AI 速读：[/llms.txt](/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。

## 安装

参考 [快速开始](/docs/quickstart#第-1-步下载并安装-cli)，或：

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

## 通用 flags

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

| Flag | 类型 | 说明 |
|------|------|------|
| `--api-url` | string | 覆盖 api_url，单次调用使用临时地址 |
| `--insecure` | bool | 跳过 TLS 证书校验（自签场景） |
| `--profile` | string | 使用指定 profile（默认读 active 配置） |
| `--format` | enum | 输出格式 `table` / `json` / `yaml`（默认 table） |
| `--verbose` | bool | 打印请求详情，便于排障 |
| `--quiet` | bool | 静默模式：屏蔽成功提示与分页信息，不影响数据 stdout 与错误 stderr |
| `--yes` / `-y` | bool | 对所有交互确认自动回答 yes（等价于每个删除命令都加 `-f`） |
| `--help` / `-h` | bool | 输出当前命令的帮助 |

## 1. 认证命令（auth）

| 命令 | 说明 | 示例 |
|------|------|------|
| `zcloud auth login` | 交互式登录（提示输入用户名/密码，密码不回显），凭证写入 `~/.zcloud/credentials.toml` | `zcloud auth login` |
| `zcloud --api-url <URL> auth login` | 临时覆盖 API 地址后再登录 | `zcloud --api-url https://waf.example.com auth login` |
| `zcloud --insecure auth login` | 跳过 TLS 校验登录（仅自签证书内网测试） | `zcloud --insecure auth login` |
| `zcloud auth logout` | 注销当前会话，清除本地 token | `zcloud auth logout` |
| `zcloud auth info` | 查询当前账号信息和权限 | `zcloud auth info --format json` |
| `zcloud auth apikey create --name N [--scopes K1,K2] [--expires-days N]` | 签发新 API Key（明文仅返回一次，请立即保存） | `zcloud auth apikey create --name 生产对接 --expires-days 30` |
| `zcloud auth apikey list [--page N] [--size N]` | 查看自己/本 OEM 的 API Key 列表 | `zcloud auth apikey list --format json` |
| `zcloud auth apikey revoke <key-id> [-f]` | 吊销 API Key（幂等，软删保留审计） | `zcloud auth apikey revoke 8f21c0c5-... -f` |
| `zcloud auth apikey renew <key-id> --add-days N` | 续期 API Key 过期时间（--add-days 必填，1-365 天） | `zcloud auth apikey renew 8f21c0c5-... --add-days 90` |
| `zcloud auth apikey revoke-all [--user-id U] [--reason R] [-f]` | 一键吊销 user 名下全部 active API Key（应急止损；--user-id 仅平台级用户有效，留空=自己） | `zcloud auth apikey revoke-all -f --reason "凭据可能泄露"` |
| `zcloud auth apikey logs <key-id> [--event call\|manage] [--page N] [--size N\|--limit N]` | 查看指定 Key 的审计日志（默认 event=call，调用流水） | `zcloud auth apikey logs 8f21c0c5-... --limit 50` |
| `zcloud auth apikey stats <key-id> [--since 24h\|7d\|30m]` | 查看指定 Key 的聚合统计（成功率/错误分布/top endpoints/最近1h QPS） | `zcloud auth apikey stats 8f21c0c5-... --since 24h` |

绑定 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）

| 命令 | 说明 | 示例 |
|------|------|------|
| `zcloud config set <key> <value>` | 设置当前 profile 的配置项 | `zcloud config set api_url https://waf.example.com` |
| `zcloud config get <key>` | 读取当前 profile 的配置项 | `zcloud config get api_url` |
| `zcloud config list` | 列出当前 profile 的所有配置 | `zcloud config list` |
| `zcloud config profiles list` | 列出所有 profile | `zcloud config profiles list` |
| `zcloud config profiles create <name>` | 创建空 profile（无 flag；首个 profile 会自动激活） | `zcloud config profiles create prod` |
| `zcloud config profiles activate <name>` | 切换激活 profile | `zcloud config profiles activate prod` |
| `zcloud config profiles delete <name>` | 删除 profile | `zcloud config profiles delete dev` |

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

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

## 3. sys 模块（系统管理）

### 3.1 用户管理 sys users

| 命令 | 说明 | 示例 |
|------|------|------|
| `zcloud sys users list [--page N] [--size N] [--keyword K]` | 分页查询用户 | `zcloud sys users list --page 1 --size 20` |
| `zcloud sys users describe <uuid>` | 查看用户详情 | `zcloud sys users describe abc-123-...` |
| `zcloud sys users create --username U --password P [--nick-name N] [--email E] [--mobile M] [--comment C]` | 创建用户（`--username` 和 `--password` 必填；**没有 `--oem-id` / `--display-name` 之类的 flag**） | `zcloud sys users create --username u1 --password '***' --nick-name '运维 A'` |
| `zcloud sys users update <uuid> [--nick-name N] [--email E] [--mobile M] [--comment C]` | 编辑用户基础信息（按 flag 增量更新） | `zcloud sys users update abc-123 --nick-name '运维 A'` |
| `zcloud sys users delete <uuid> [-f]` | 删除用户（`-f` 跳过确认；亦可全局 `-y`） | `zcloud sys users delete abc-123 -f` |
| `zcloud sys users reset-password <uuid> --password NEW` | 重置密码（`--password` 必填） | `zcloud sys users reset-password abc-123 --password 'New***'` |
| `zcloud sys users lock <uuid> [--locked true\|false]` | 锁定/解锁账号（`--locked` 默认 true） | `zcloud sys users lock abc-123 --locked false` |
| `zcloud sys users assign-roles <uuid> --role-ids 1,2,3` | 分配角色（必填 `--role-ids`，逗号分隔） | `zcloud sys users assign-roles abc-123 --role-ids 5,6` |

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

| 命令 | 说明 | 示例 |
|---|---|---|
| `zcloud sys wx-zombies cleanup [--service-ids ID1,ID2] [--max-pages N]` | dry-run 扫描本地仍绑定、但不在微信公众号关注者列表中的 openid | `zcloud sys wx-zombies cleanup --max-pages 50` |
| `zcloud sys wx-zombies cleanup --apply [--max-pages N]` | 执行清理：清空 `users.wx_union_id/wx_nick_name`、对应 `alert_receivers.weixin` 和 `weixin_userinfo` | `zcloud sys wx-zombies cleanup --apply --max-pages 50` |

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

### 3.2 角色管理 sys roles

| 命令 | 说明 | 示例 |
|------|------|------|
| `zcloud sys roles list [--page N] [--size N] [--keyword K]` | 列出角色 | `zcloud sys roles list` |
| `zcloud sys roles create --name N [--level L] [--comment C]` | 创建角色（`--level` 默认 1） | `zcloud sys roles create --name 运维员 --level 10` |
| `zcloud sys roles update <id> [--name N] [--level L] [--comment C]` | 修改角色（按 flag 增量更新） | `zcloud sys roles update 5 --name 高级运维员` |
| `zcloud sys roles delete <id> [-f]` | 删除角色（`-f` 跳过确认；亦可全局 `-y`） | `zcloud sys roles delete 5 -f` |
| `zcloud sys roles get-permissions <id>` | 查询角色已有权限 | `zcloud sys roles get-permissions 5` |
| `zcloud sys roles set-permissions <id> --permissions K1,K2,K3` | 覆盖式设置权限（必填） | `zcloud sys roles set-permissions 5 --permissions guard.domain.list,guard.domain.view` |

### 3.3 OEM 管理 sys oems

| 命令 | 说明 | 示例 |
|------|------|------|
| `zcloud sys oems list [--page N] [--size N] [--keyword K]` | 列出 OEM | `zcloud sys oems list` |
| `zcloud sys oems describe <uuid>` | OEM 详情 | `zcloud sys oems describe oem-abc` |
| `zcloud sys oems create --name N --hostname H [--tag T] [--comment C]` | 创建 OEM | `zcloud sys oems create --name 客户A --hostname a.example.com` |
| `zcloud sys oems update <uuid> [--name N] [--hostname H] [--tag T] [--comment C]` | 修改 OEM（按 flag 增量更新） | `zcloud sys oems update oem-abc --name '新名'` |
| `zcloud sys oems delete <uuid> [-f]` | 删除 OEM | `zcloud sys oems delete oem-abc -f` |
| `zcloud sys oems get-setting <uuid> <key>` | 查 OEM 单项配置 | `zcloud sys oems get-setting oem-abc theme` |
| `zcloud sys oems set-setting <uuid> <key> <value>` | 写 OEM 单项配置 | `zcloud sys oems set-setting oem-abc theme dark` |

### 3.4 会话管理 sys sessions

| 命令 | 说明 | 示例 |
|------|------|------|
| `zcloud sys sessions list [--page N] [--size N] [--keyword K]` | 列出在线会话 | `zcloud sys sessions list` |
| `zcloud sys sessions kill <session-id> [-f]` | 强制下线会话 | `zcloud sys sessions kill sess-xxx -f` |

### 3.5 审计日志 sys audit-logs

| 命令 | 说明 | 示例 |
|------|------|------|
| `zcloud sys audit-logs list [--page N] [--size N] [--keyword K]` | 操作审计日志 | `zcloud sys audit-logs list --page 1 --size 50` |
| `zcloud sys audit-logs login-records list [--page N] [--size N] [--keyword K]` | 登录历史 | `zcloud sys audit-logs login-records list` |
| `zcloud sys audit-logs permissions` | 权限树（含 i18n 名） | `zcloud sys audit-logs permissions --format json` |

## 4. guard 模块（Web 防护）

### 4.1 域名 guard domains

| 命令 | 说明 | 示例 |
|------|------|------|
| `zcloud guard domains list [--page N] [--size N] [--keyword K]` | 列出域名 | `zcloud guard domains list` |
| `zcloud guard domains describe <domain-id>` | 域名详情 | `zcloud guard domains describe 12` |
| `zcloud guard domains create --domain D [--asset-name A] [--policy-id P]` | 创建域名（域名为必填） | `zcloud guard domains create --domain api.example.com --asset-name 主站 --policy-id 1` |
| `zcloud guard domains update <domain-id> [--asset-name A] [--policy-id P]` | 修改域名（按 flag 增量更新；至少一项） | `zcloud guard domains update 12 --policy-id 2` |
| `zcloud guard domains delete <domain-id> [-f]` | 删除域名 | `zcloud guard domains delete 12 -f` |
| `zcloud guard domains get-settings <domain-id>` | 读域名详细配置 | `zcloud guard domains get-settings 12` |
| `zcloud guard domains set-settings <domain-id> --key K --value V` | 写域名单项配置（KV 模式，**不是 JSON 文件**） | `zcloud guard domains set-settings 12 --key cc_protect --value enable` |

### 4.2 证书 guard certs

| 命令 | 说明 | 示例 |
|------|------|------|
| `zcloud guard certs list [--page N] [--size N] [--keyword K]` | 列出证书 | `zcloud guard certs list` |
| `zcloud guard certs describe <cert-id>` | 证书详情 | `zcloud guard certs describe 3` |
| `zcloud guard certs upload --name N --cert F --key F [--sign-cert F] [--sign-key F]` | 上传证书（PEM；可选签名证书 / 国密双证） | `zcloud guard certs upload --name star --cert ./fullchain.pem --key ./private.key` |
| `zcloud guard certs update <cert-id> [--name N] [--cert F] [--key F] [--sign-cert F] [--sign-key F]` | 替换证书（按 flag 增量更新） | `zcloud guard certs update 3 --cert ./new.pem --key ./new.key` |
| `zcloud guard certs delete <cert-id> [-f]` | 删除证书 | `zcloud guard certs delete 3 -f` |
| `zcloud guard certs bind <cert-id> --domain-id D` | 证书绑定到域名（必填 `--domain-id`） | `zcloud guard certs bind 3 --domain-id 12` |
| `zcloud guard certs unbind <cert-id> --domain-id D` | 证书解绑域名（必填 `--domain-id`） | `zcloud guard certs unbind 3 --domain-id 12` |

### 4.3 策略 guard policies

| 命令 | 说明 | 示例 |
|------|------|------|
| `zcloud guard policies list [--page N] [--size N] [--keyword K]` | 列出策略 | `zcloud guard policies list` |
| `zcloud guard policies describe <policy-id>` | 策略详情 | `zcloud guard policies describe 8` |
| `zcloud guard policies create --name N [--comment C]` | 创建策略 | `zcloud guard policies create --name p1` |
| `zcloud guard policies update <policy-id> [--name N] [--comment C]` | 修改策略 | `zcloud guard policies update 8 --name p1-v2` |
| `zcloud guard policies delete <policy-id> [-f]` | 删除策略 | `zcloud guard policies delete 8 -f` |

### 4.4 黑白名单 guard bwlist

| 命令 | 说明 | 示例 |
|------|------|------|
| `zcloud guard bwlist sets list [--page N] [--size N] [--keyword K]` | 列出名单集合 | `zcloud guard bwlist sets list` |
| `zcloud guard bwlist sets create --name N --type black\|white [--policy-id P] [--describe D]` | 创建名单集合（`--name` 和 `--type` 必填） | `zcloud guard bwlist sets create --name block-cn --type black` |
| `zcloud guard bwlist sets update <set-id> [--name N] [--status enable\|disable] [--describe D]` | 修改名单集合 | `zcloud guard bwlist sets update 5 --name allow-asia` |
| `zcloud guard bwlist sets delete <set-id> [-f]` | 删除名单集合 | `zcloud guard bwlist sets delete 5 -f` |
| `zcloud guard bwlist ips list <set-id> [--page N] [--size N]` | 列出集合下的 IP | `zcloud guard bwlist ips list 5` |
| `zcloud guard bwlist ips add <set-id> --ip IP` | 加入单个 IP（必填 `--ip`） | `zcloud guard bwlist ips add 5 --ip 1.2.3.4` |
| `zcloud guard bwlist ips batch-add <set-id> --ips IP1,IP2,...` | 批量加 IP（逗号分隔字符串，**不接受 `--file`**） | `zcloud guard bwlist ips batch-add 5 --ips 1.2.3.4,5.6.7.8` |
| `zcloud guard bwlist ips delete <ip-id> [-f]` | 删除单个 IP | `zcloud guard bwlist ips delete 1234 -f` |
| `zcloud guard bwlist ips batch-delete <set-id> --ip-ids ID1,ID2,...` | 批量删 IP（逗号分隔的 IP 条目 ID，限定集合内） | `zcloud guard bwlist ips batch-delete 5 --ip-ids 100,101,102 -f` |

### 4.5 WAF 规则 guard waf

| 命令 | 说明 | 示例 |
|------|------|------|
| `zcloud guard waf rules list [--page N] [--size N] [--policy-id P]` | 列出规则组 | `zcloud guard waf rules list` |
| `zcloud guard waf rules create --name N --policy-id P [--describe D] [--scope S] [--action 1\|2\|3] [--status 1\|2] [--waf-type N]` | 创建规则组（`--name` 和 `--policy-id` 必填；动作 1=block / 2=log / 3=captcha） | `zcloud guard waf rules create --name sqli-1 --policy-id 8 --action 1` |
| `zcloud guard waf rules update <rule-id> [--name N] [--describe D] [--scope S] [--action N] [--status N] [--waf-type N]` | 修改规则组 | `zcloud guard waf rules update 7 --name sqli-1-v2` |
| `zcloud guard waf rules delete <rule-id> [-f]` | 删除规则组 | `zcloud guard waf rules delete 7 -f` |
| `zcloud guard waf rules set-status <rule-id> --status enable\|disable` | 启停规则组（**字符串枚举，非布尔**） | `zcloud guard waf rules set-status 7 --status enable` |

### 4.6 转发 guard forwards

| 命令 | 说明 | 示例 |
|------|------|------|
| `zcloud guard forwards list [--page N] [--size N] [--domain-id D] [--keyword K]` | 列出转发 | `zcloud guard forwards list --domain-id 12` |
| `zcloud guard forwards create --domain-id D --port P [--schema 3\|4] [--domain D] [--describe D]` | 新增转发（`--domain-id` 和 `--port` 必填；`--schema` 3=TCP 4=UDP） | `zcloud guard forwards create --domain-id 12 --port 8443 --schema 3` |
| `zcloud guard forwards update <forward-id> [--port P] [--schema N] [--status 1\|2] [--describe D]` | 修改转发（`--status` 1=禁用 2=启用） | `zcloud guard forwards update 4 --status 2` |
| `zcloud guard forwards delete <forward-id> [-f]` | 删除转发 | `zcloud guard forwards delete 4 -f` |

### 4.7 调度管理 guard schedules

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

| 命令 | 说明 | 示例 |
|------|------|------|
| `zcloud guard schedules domains [--page N] [--size N] [--keyword K] [--user-id U] [--mode 0\|1\|2] [--status S]` | DNS 调度域名列表（`--mode` 0=全部 1=源站 2=节点） | `zcloud guard schedules domains --keyword example.com` |
| `zcloud guard schedules switch-mode <domain-id> --target-mode src\|node [--comment C]` | 切换源站/节点（必填 `--target-mode`） | `zcloud guard schedules switch-mode d_8a3b1c --target-mode node` |
| `zcloud guard schedules init <domain-id> [--comment C]` | 初始化解析（按当前配置重建记录并提交同步事务） | `zcloud guard schedules init d_8a3b1c` |
| `zcloud guard schedules reset <domain-id> [--comment C]` | 重置该域名所有解析（switch_state 归位、status 回滚） | `zcloud guard schedules reset d_8a3b1c` |
| `zcloud guard schedules records <domain-id> [--group-type 1\|2] [--status 1\|2] [--page N] [--size N]` | 列出域名解析记录（直查 zdns_db，只读） | `zcloud guard schedules records d_8a3b1c --status 2` |
| `zcloud guard schedules batch-status --record-ids id1,id2 --status enable\|disable [--comment C]` | 批量启停 DNS 解析记录（`--record-ids` 与 `--status` 均必填） | `zcloud guard schedules batch-status --record-ids r1,r2 --status disable` |
| `zcloud guard schedules affairs [--page N] [--size N] [--user-id U] [--status S] [--ctime-from MS] [--ctime-to MS] [--domain-id D]` | 事务记录列表（`--status` 取 `AffairsStatus_Start\|AffairsStatus_Succeed\|AffairsStatus_Faild`） | `zcloud guard schedules affairs --domain-id d_8a3b1c` |
| `zcloud guard schedules affair <affair-id>` | 事务记录详情（含完整 message HTML 与 json_content） | `zcloud guard schedules affair 1715600000_aB3xY9LmNq` |

### 4.8 下发 guard applies

| 命令 | 说明 | 示例 |
|------|------|------|
| `zcloud guard applies list [--page N] [--size N] [--domain-id D] [--status S]` | 列出下发任务（`--status` 取 `pending\|success\|failed\|running\|quit`） | `zcloud guard applies list --status running` |
| `zcloud guard applies describe <apply-id>` | 任务概要 | `zcloud guard applies describe 100` |
| `zcloud guard applies create --domain-id D` | 触发下发（`--domain-id` 必填） | `zcloud guard applies create --domain-id 12` |
| `zcloud guard applies detail <apply-id>` | 任务详情（含子任务） | `zcloud guard applies detail 100` |
| `zcloud guard applies retry <apply-id> [--node-ids id1,id2]` | 失败重试（`--node-ids` 指定子节点；为空则重试所有失败节点） | `zcloud guard applies retry 100` |
| `zcloud guard applies quit <apply-id> [-f]` | 终止任务 | `zcloud guard applies quit 100 -f` |

## 5. analytics 模块（统计大屏）

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

| Flag | 类型 | 说明 |
|------|------|------|
| `--window` | string | 时间窗口，如 `last_1h` / `last_24h` / `last_7d`（取值由后端定义） |
| `--stime` / `--etime` | int64 | 起止时间（Unix 毫秒，用于自定义窗口） |
| `--site-id` / `--domain-id` | string | 按站点/域名过滤 |
| `--compare` | bool | 启用环比 |
| `--top` | int | TopN 限制（1-100） |
| `--order` | string | 排序方式（`asc` / `desc`，具体含义视图表定义） |
| `--page` / `--size` | int | 列表分页（仅日志/记录类图表）|
| `--charts` | string | 当 chart-key 省略时，按逗号列表批量拉取（fallback batch） |

各页面 chart-key 清单：

| 页面 | chart-key |
|------|-----------|
| `overview` | `kpi`, `bandwidth`, `request-attack`, `event-type`, `waf-type`, `geo`, `top-domains`, `recent-events` |
| `access` | `request-hm`, `flow-hm`, `cache-hm`, `bandwidth`, `status`, `flow-duration`, `isp`, `top-ip`, `top-url`, `geo` |
| `protect` | `overview`, `waf/statistics`, `waf/types`, `waf/top-ip`, `waf/geo`, `cc/statistics`, `cc/top-ip`, `cc/geo`, `cc/top-url`, `ddos/statistics`, `ddos/types`, `ddos/top-ip` |
| `ai` | `attack-trend`, `top-ip`, `top-url`, `detection`, `test-results`, `logs` |
| `bot` | `statistics`, `advance-warn`, `browser`, `operating`, `geo`, `top-agent`, `top-ip`, `scatter`, `sessions` |
| `alert` | `total`, `hm`, `types`, `domains`, `list` |

| 命令 | 说明 | 示例 |
|------|------|------|
| `zcloud analytics overview [chart-key] [flags]` | 总览页（不传 chart-key 时整页 batch） | `zcloud analytics overview kpi --window last_24h --format json` |
| `zcloud analytics access [chart-key] [flags]` | 访问统计 | `zcloud analytics access top-url --window last_7d --format json` |
| `zcloud analytics protect [chart-key] [flags]` | 防护统计 | `zcloud analytics protect waf/statistics --format json` |
| `zcloud analytics ai [chart-key] [flags]` | AI 识别统计 | `zcloud analytics ai logs --page 1 --format json` |
| `zcloud analytics bot [chart-key] [flags]` | 主动防护（Bot） | `zcloud analytics bot statistics --format json` |
| `zcloud analytics alert [chart-key] [flags]` | 告警统计 | `zcloud analytics alert list --page 1 --size 20 --format json` |
| `zcloud analytics glossary` | 字段术语表 | `zcloud analytics glossary --format json` |
| `zcloud analytics batch --page P --charts C [...]` | 跨页通用 batch（`--page` 与 `--charts` 必填） | `zcloud analytics batch --page overview --charts kpi,bandwidth --format json` |
| `zcloud analytics overview export --charts C [--type csv\|json] [...]` | 导出 overview 报表（**仅 overview 子页支持 export**） | `zcloud analytics overview export --type csv --charts kpi,bandwidth > overview.csv` |
| `zcloud analytics alert ack <alert-id>` | 确认告警 | `zcloud analytics alert ack a-20260422-0001` |
| `zcloud analytics bot session <session-id>` | Bot 会话详情（仅接受 `--window` / `--stime` / `--etime`） | `zcloud analytics bot session s-abc123 --format json` |

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

| 命令 | 说明 | 示例 |
|------|------|------|
| `zcloud analytics health [chart-key] [flags]` | Phase 3 业务健康（status-breakdown / slow-uri / availability 等 7 chart-key） | `zcloud analytics health summary --window last_24h --format json` |
| `zcloud analytics ops [chart-key] [flags]` | Phase 5 平台运维（traffic-users / error-domains / nodes 等 8 chart-key，**仅平台运维/超管可见**） | `zcloud analytics ops traffic-users --top 20 --format json` |
| `zcloud analytics closure [chart-key] [flags]` | Phase 6 处置闭环（summary / alerts / risks / trend 4 chart-key） | `zcloud analytics closure summary --format json` |
| `zcloud analytics cache [chart-key] [flags]` | Phase 6 缓存收益（summary / trend / top-uri / content-types） | `zcloud analytics cache summary --window last_7d --format json` |
| `zcloud analytics logs list [flags]` | Phase 1 原始日志列表（uuid/session/ip/uri/status/z_final_* 12 字段筛选） | `zcloud analytics logs list --window last_24h --status 403 --format json` |
| `zcloud analytics logs detail <uuid>` | Phase 1 单条日志详情 | `zcloud analytics logs detail req-abc123 --format json` |
| `zcloud analytics logs export --format csv [--fields ...] [flags]` | Phase 1 原始日志导出（size ≤ 10000，超出走异步任务） | `zcloud analytics logs export --format csv --fields ctime,uuid,host,uri,status > logs.csv` |
| `zcloud analytics closure {alerts\|risks} confirm --ids ID1,ID2,...` | Phase 6 批量确认告警/风险（代理 `/api/alert/records/confirm` 与 `/api/chart/risk/events/:event_id/confirm`） | `zcloud analytics closure alerts confirm --ids a1,a2,a3` |
| `zcloud analytics reports templates` | Phase 4 列出报表模板 | `zcloud analytics reports templates --format json` |
| `zcloud analytics reports list` | Phase 4 报表历史列表 | `zcloud analytics reports list --format json` |
| `zcloud analytics reports describe <id>` | Phase 4 报表详情 | `zcloud analytics reports describe r-001 --format json` |
| `zcloud analytics reports generate --template T --window W [...]` | Phase 4 触发生成（同步阈值 ≤ 100k 行；超出走异步） | `zcloud analytics reports generate --template protection-value --window last_30d` |
| `zcloud analytics reports download <id> [--output file]` | Phase 4 下载报表产物（pdf/csv/json/html） | `zcloud analytics reports download r-001 --output report.pdf` |

**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 使用）。

| 命令 | 说明 | 所需权限 |
|------|------|---------|
| `zcloud plan list [--prod-type N] [--keyword KW] [--page N] [--page-size N]` | 分页查询套餐目录；可按产品类型（1=WAF/2=Monitor/3=GFIP）和名称关键词过滤 | `plan.plan.list` |
| `zcloud plan describe <plan_id>` | 查看套餐详情（含 content 配额 JSON） | `plan.plan.view` |

**示例**

```bash
# 列出 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

| 命令 | 说明 | 示例 |
|------|------|------|
| `zcloud update` | 自更新（查询 `/api/cli/version` 后下载新版本） | `zcloud update` |
| `zcloud completion <bash\|zsh\|fish>` | 生成 shell 补全脚本 | `zcloud completion zsh > ~/.zsh/_zcloud` |
| `zcloud version` | 显示当前 CLI 版本 | `zcloud version` |

后端发布相关 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 节点安装 / 升级](/docs/api#8-节点安装--升级node-install)。

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

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

```bash
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>'
```

脚本参数 / 环境变量：

| 参数 | 环境变量 | 默认 | 说明 |
|------|---------|------|------|
| `--token <token>` | `SETUP_TOKEN` | 必填 | 一次性安装 token（`nit_` 前缀），仅展示一次 |
| `--server <url>` | `SERVER_ADDR` | 必填 | cloud 对外地址，须匹配配置的 public base URL |
| `--install-dir <dir>` | `INSTALL_DIR` | `/opt/skynet-node` | 安装目录 |

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

### 8.2 管理操作（curl / API）

| 操作 | 方法 + 路径 | 所需权限（`node.node.*`） |
|------|------------|--------------------------|
| 注册安装包 + 预检 | `POST /api/node/install/artifacts` | `artifact` |
| 查询安装包 | `GET /api/node/install/artifacts` | `artifact` |
| 生成安装命令 | `POST /api/node/install/commands` | `install` |
| 生成升级命令 | `POST /api/node/install/upgrades` | `upgrade` |
| 查询任务列表 / 详情 | `GET /api/node/install/jobs[/:id]` | `job` |
| 撤销 token | `POST /api/node/install/tokens/:id/revoke` | `revoke` |

要点：`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 文档](/docs/api) — 命令对应的 REST 接口
- [认证说明](/docs/auth) — profile / 401 重试机制
- [权限矩阵](/docs/permissions) — 命令所需权限 key

---

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