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

```bash
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 — 手动下载：**

```bash
# 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 步：登录拿到会话

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

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

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

如需多套环境，使用 profile：

```bash
# 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 步：运行第一个命令

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

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

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

## 常见错误处理

| 现象 | 原因 | 处理 |
|------|------|------|
| `401 Unauthorized` | 会话过期 | 重新执行 `zcloud auth login` |
| `403 Forbidden` | 当前账号无该资源权限 | 联系管理员授予对应权限 key |
| `connection refused` | api_url 错误或服务不可达 | 检查 `zcloud config get api_url` |
| `x509: certificate signed by unknown authority` | 自签证书 | 加 `--insecure` 标志或导入 CA |

## 输出格式切换

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

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

## 下一步

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

---

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