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

30 秒接入指南

产品定位

Cloud WAF 是一个企业级 Web 防护管理平台，提供域名接入、证书管理、WAF 规则、CC/ACL 防护、转发策略、统计大屏等一体化能力。系统由 Go 后端（Gin）+ Vue 3 前端 + Cobra CLI（zcloud）组成。

任何 Web 服务接入 Cloud WAF 后，可以通过 Web 控制台、CLI、或 REST API 三种方式管理；本指南面向开发者，演示如何在 30 秒内通过 CLI 完成第一次调用。

前置条件

• 已部署的 Cloud WAF 服务地址（如 https://waf.example.com）
• 一个具备访问权限的账号（用户名 + 密码）
• Linux / macOS 终端，已安装 curl 和 bash

三步走

第 1 步：下载并安装 CLI

方式 A — 一键脚本（推荐）：

curl -fsSL https://waf.example.com/api/cli/install.sh | sh

脚本会自动检测当前操作系统和架构（linux/amd64、linux/arm64、darwin/amd64、darwin/arm64），从 /api/cli/version 拉取最新二进制并安装到 /usr/local/bin/zcloud。

方式 B — 手动下载：

# 1) 查询最新版本和下载 URL
curl -s https://waf.example.com/api/cli/version

# 2) 下载二进制（替换为返回值里的 download_url）
curl -fsSL -o /tmp/zcloud "<download_url>"
chmod +x /tmp/zcloud
sudo mv /tmp/zcloud /usr/local/bin/zcloud

# 3) 验证安装
zcloud version

第 2 步：登录拿到会话

zcloud config set api_url https://waf.example.com
# 交互式登录：会依次提示输入 Username / Password（密码不回显）
zcloud auth login

成功后凭据会保存到本地 ~/.zcloud/credentials.toml，后续所有命令自动携带会话 token。

如使用自签证书，请改用 zcloud --insecure auth login 跳过 TLS 校验。

如需多套环境，使用 profile：

# profiles create 只接受位置参数 <name>，不支持任何 flag
zcloud config profiles create prod
zcloud --profile prod config set api_url https://prod.example.com
zcloud config profiles activate prod

第 3 步：运行第一个命令

# 列出当前账号管理的域名
zcloud guard domains list

# 查看自己身份和权限
zcloud auth info

# 看 CLI 完整命令树
zcloud --help

常见错误处理

输出格式切换

所有命令都支持 --format 切换输出：

zcloud guard domains list --format table   # 默认，人类友好
zcloud guard domains list --format json    # 机器可读
zcloud guard domains list --format yaml    # 配置友好

下一步

• CLI 完整命令清单 — 98 条命令全树
• API 文档 — REST 接口详解
• 认证说明 — Bearer 会话、API Key 与 401 重试机制
• 示例代码 — curl / Python / Go 三语示例
• 权限矩阵 — Resource × Action 全集

Cloud WAF · zcloud CLI · 文档版本与 API 同步发布