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

API 文档

商业级 REST API 文档 · 57 个 endpoint · 80+ 图表数据接口（chart-key）· 双通道鉴权
适用对象：客户对接工程师、SRE、SaaS 集成商、AI agent
阅读顺序：先看 §0 总体约定 → §1 鉴权 → 再按业务模块跳转

目录

必读

• §0 总体约定 — 协议 / 信封 / HTTP 状态码 / 分页 / 三类读者画像
• §1 鉴权（先读） — Bearer Session + API Key 双通道 / scopes 收窄

公开接口（无需鉴权）

• §2 CLI 发布 — version · install.sh · download · checksums
• §3 用户认证 — login · logout

业务接口（双通道鉴权）

• §4 系统管理
  • 4.1 用户管理 — /api/sys/users
  • 4.2 API Key 管理 — /api/sys/apikeys
  • 4.3 权限树 — /api/sys/permissions/tree
  • 4.4 操作审计 — /api/sys/audit-logs、/api/sys/login-records
• §5 Guard 资源管理
  • 5.1 域名 — /api/guard/domains
  • 5.2 证书 — /api/guard/certs
  • 5.3 策略 — /api/guard/policies
  • 5.4 CC 规则 — /api/guard/policies/{id}/cc/rules
  • 5.5 ACL 规则 — /api/guard/policies/{id}/acl/rules
  • 5.6 黑白名单 — /api/guard/bwlist
  • 5.7 IP 转发 — /api/guard/forwards
  • 5.8 调度管理 — /api/guard/schedules
  • 5.9 WAF 规则 — /api/guard/waf/rules

套餐目录

• §7 套餐目录（Plan） — 只读对外：list · describe；admin 操作不在此范围

节点运维

• §8 节点安装 / 升级（Node Install） — artifacts · commands · upgrades · jobs · tokens + 安装机侧 script/package/env/report

Analytics 统计分析（92 chart-key · 单一形状契约）

• §6.0 本章统一调用约定 — 5 字段契约 / render_hint 8 词白名单
• §6.1 术语表 · §6.2 跨页 Batch · §6.3 单图 GET 调用入口
• §6.4 总览页面 Overview · 8 chart-key
• §6.5 访问分析页面 Access · 25 已支持 chart-key
• §6.6 防护分析页面 Protect · 19 已支持 chart-key（WAF / CC / DDoS）
• §6.7 AI 识别页面 · 6 chart-key
• §6.8 主动防护 / Bot 页面 · 12 chart-key
• §6.9 告警统计页面 Alert · 5 chart-key
• §6.10 业务健康 Health · 7 chart-key
• §6.11 平台运维 Ops · 8 chart-key
• §6.12 处置闭环 Closure · 4 chart-key
• §6.13 缓存收益 Cache · 4 chart-key
• §6.14 访问日志 Logs — 非 chart endpoint
• §6.15 报表中心 Reports — 非 chart endpoint
• §6.16 CLI 对应关系 — 30 cobra 命令映射

参考

• §A 通用查询参数 — window / stime / etime / site_id / domain_id / target_user_id / compare / top / order
• §B 可视化建议总表 — B.1 render_hint 速查 · B.2 数据形态速查
• §C 相关文档

完整 OpenAPI: /api/openapi.json · AI 速读: /llms.txt · 错误码: /docs/errors · CLI: /docs/cli · 权限: /docs/permissions

§0 总体约定

红网云后端基于 Gin 实现的 RESTful 服务。

0.1 基础协议

0.2 统一响应信封

任何 JSON 响应都遵循下面三段结构：

{
  "code": 0,
  "message": "ok",
  "data": { /* 业务载荷，类型依接口而定 */ }
}

特例：导出文件下载接口（POST /api/analytics/overview/export、GET /api/analytics/reports/:id/download、POST /api/analytics/logs/export）直接返回二进制流或 CSV/JSON 原文，不包裹信封。

0.3 HTTP 状态码

0.4 列表接口分页约定

所有列表接口统一使用 page + size（不是 page_size）：

响应：

{
  "code": 0,
  "data": {
    "list": [ /* ... */ ],
    "total": 42,
    "page": 1,
    "size": 20
  }
}

0.5 跨模块设计标记（D*）

文档中少量 D* 标记来自跨模块设计决策，用于提醒对接方不要使用不存在或语义错误的字段：

0.6 三类读者的阅读路径

§1 鉴权（先读）

红网云当前支持两条认证通道，同一请求只能选其中一种：

公开接口（无需鉴权）只有 4 个：

• GET /api/cli/version
• GET /api/cli/install.sh
• GET /api/cli/download/{filename}
• GET /api/cli/checksums.txt
• POST /api/auth/login

其它所有接口都必须携带上述任一认证头。下面各接口示例默认使用 Bearer；如改用 API Key，只需把请求头替换为 Authorization: ApiKey zck_<prefix>.<secret>，并确保该 Key 的 scopes 覆盖接口所需权限。

1.1 API Key 权限规则

effective_perms = user.RBAC ∩ key.scope

API Key 的权限不会超过签发用户当前的 RBAC；scope 只能收窄，不能放大。中间件认证通过后会注入与会话通道一致的 user_id / role_id 上下文，下游 RBAC/OEM 隔离保持一致。

安全约束：

• 明文 API Key 仅在签发响应里出现一次，落库零明文（key_hash 是 bcrypt 摘要）
• 用户被锁定或删除后，其名下 API Key 自动失效
• scopes 非空时，请求权限必须精确命中其中之一；为空表示完整继承当前 RBAC
• 跨 OEM 越权由中间件拦截：api_keys.oem_id 与请求 hostname 不一致时直接 403
• 可选 IP 白名单 allowed_ip_cidrs：非空时只放行命中 CIDR 的请求

API Key 管理接口的完整说明见 §4.2。

§2 CLI 发布（公开接口）

供 zcloud CLI 自更新与一键安装使用，无需鉴权。

GET /api/cli/version — 查询 CLI 最新版本

用途：客户端启动时自检版本；安装脚本 /api/cli/install.sh 内部依赖此接口决定下载哪个二进制。

鉴权：无（公开）

输入参数：无

输出字段：

可视化建议：纯文本展示（版本徽章），不适合图表。前端可用作"系统设置 - CLI 版本"页面的 KPI 数字卡。

示例响应：

{
  "code": 0,
  "message": "ok",
  "data": {
    "version": "v0.1.0-31",
    "binaries": [
      { "os": "linux",  "arch": "amd64", "download_url": "/api/cli/download/linux-amd64" },
      { "os": "linux",  "arch": "arm64", "download_url": "/api/cli/download/linux-arm64" },
      { "os": "darwin", "arch": "amd64", "download_url": "/api/cli/download/darwin-amd64" },
      { "os": "darwin", "arch": "arm64", "download_url": "/api/cli/download/darwin-arm64" }
    ]
  }
}

GET /api/cli/install.sh — 一键安装脚本

用途：在 Linux/macOS 上一行命令完成 CLI 安装。返回 text/x-shellscript，可直接 curl ... | sh。

鉴权：无（公开）

输入参数：无

输出字段：纯 shell 脚本文本，不走 JSON 信封。

可视化建议：不适合图表，作为代码片段展示。

示例：

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

GET /api/cli/download/{filename} — 下载指定二进制

用途：拉取特定平台的 zcloud 二进制（已签名）。filename 取自 /api/cli/version 返回的 download_url 的最后一段，如 linux-amd64。

鉴权：无（公开）

输入参数：

输出字段：二进制流（application/octet-stream）。

可视化建议：不适合图表。

GET /api/cli/checksums.txt — 二进制校验和

用途：配合 /api/cli/download/* 做 SHA256 完整性校验，安装脚本会先 fetch 这个文件再下载二进制。

鉴权：无（公开）

输入参数：无

输出字段：纯文本 text/plain，每行一个 <sha256> <filename>。

可视化建议：不适合图表。

§3 用户认证

POST /api/auth/login — 登录

用途：用用户名 + 密码换取一个会话 token。Web 控制台、CLI 交互式登录、移动端均走此接口。

鉴权：无（公开）

输入参数（请求体）：

输出字段：

可视化建议：登录响应不直接做图，但 need_change_password=true 时前端应跳转改密页。

示例请求：

curl -X POST https://waf.example.com/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"'$(echo -n 'your_password' | base64)'"}'

示例响应：

{
  "code": 0,
  "message": "ok",
  "data": {
    "token": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "u-admin",
    "user_name": "admin",
    "nick_name": "系统管理员",
    "need_change_password": false
  }
}

常见误用：

• 直接传明文密码 → 后端 base64 decode 失败，统一返回"用户名或密码错误"，无法定位真实原因
• token 在多端复用 → 注销时可能影响其它端，建议每端独立登录

POST /api/auth/logout — 注销

用途：主动失效当前 Bearer token；再次请求该 token 返回 401。

鉴权：Bearer <token>（API Key 通道无 logout 概念，吊销走 DELETE /api/sys/api-keys/:id）

输入参数：无

输出字段：data 为 null。

可视化建议：不适合图表。

示例请求：

curl -X POST https://waf.example.com/api/auth/logout \
  -H "Authorization: Bearer $TOKEN"

§4 系统管理

4.1 用户管理

适用场景：在"系统设置 - 用户管理"页面增删改查用户。所有用户接口都受 OEM 隔离，跨 OEM 操作会返回 403。

GET /api/sys/users — 用户列表（分页）

用途：在"用户管理"页面渲染用户表格，支持关键字模糊搜索 + 分页。

鉴权：sys.user.list

输入参数：

输出字段（data.list[]）：

可视化建议：表格展示。locked 列建议用徽章（绿/红）；roles 用 chip 标签。

示例请求：

curl -H "Authorization: Bearer $TOKEN" \
  "https://waf.example.com/api/sys/users?page=1&size=20&keyword=admin"

示例响应：

{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [
      {
        "user_id": "u-001",
        "user_name": "admin",
        "nick_name": "系统管理员",
        "email": "admin@example.com",
        "mobile": "",
        "locked": 0,
        "role_ids": [1],
        "roles": [{ "role_id": 1, "name": "超级管理员", "level": 1 }],
        "ctime": 1714521600000
      }
    ],
    "total": 42,
    "page": 1,
    "size": 20
  }
}

常见误用：

• 把 role_ids 当成单值字段 → 用户可有多角色，必须按数组处理
• 用 level 做权限阈值判断 → level 是展示字段（业务层级），权限阈值用 role_id（参见 pitfall_role_level_vs_role_id）

POST /api/sys/users — 创建用户

用途：在"用户管理"页面提交"新建用户"表单。

鉴权：sys.user.create

输入参数（请求体）：

输出字段：返回新建用户对象，结构同列表项。

可视化建议：不适合图表，是一次性写操作；前端应在成功后刷新用户列表。

示例请求：

curl -X POST https://waf.example.com/api/sys/users \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"user_name":"u1","password":"InitPassw0rd!","nick_name":"运维 A","email":"u1@example.com"}'

DELETE /api/sys/users/{id} — 删除用户

用途：用户管理页面"删除"按钮的后端接口。删除会级联清理会话、API Key、角色绑定。

鉴权：sys.user.delete

输入参数：

输出字段：data 为 null。

可视化建议：不适合图表。

PUT /api/sys/users/{id}/password — 重置密码

用途：管理员替用户重置密码。被重置用户下次登录后强制改密码。

鉴权：sys.user.resetpwd

输入参数：

输出字段：data 为 null。

可视化建议：不适合图表。

示例请求：

curl -X PUT https://waf.example.com/api/sys/users/u-001/password \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"password":"NewPassw0rd!"}'

常见误用：

• 期望前端做 base64 编码 → 此接口直接传明文，与登录接口不同（登录接口 base64 是历史兼容）

4.2 API Key 管理

适用场景：在"系统设置 - API Key"页面发放/回收脚本调用凭证。配合 /api/sys/api-keys/:id/logs|stats|audit-actions 做调用审计。

POST /api/sys/api-keys — 签发新 API Key

用途：为脚本/CI/第三方系统签发一条机器调用凭证。明文 api_key 字段仅此一次返回，前端必须立即让用户复制保存。

鉴权：sys.apikey.create

输入参数（请求体）：

输出字段：

错误码：

• 1052 scope 超出用户 RBAC 边界
• 1054 expires_in_days > 365
• 1055 name 缺失

可视化建议：签发响应是一次性写操作，建议前端用模态框 + 一次性复制按钮 + 遮码展示明文（参考行业惯例 GitHub/Stripe）。

示例请求：

curl -X POST https://waf.example.com/api/sys/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"生产对接","scopes":["guard.domain.list"],"expires_in_days":90}'

示例响应：

{
  "code": 0,
  "data": {
    "key_id": "8f21c0c5-55ae-4cbd-a60a-8e64a6e2b1d0",
    "name": "生产对接",
    "api_key": "zck_abc12345.A1b2C3d4E5f6G7h8I9j0K1L2M3n4O5p6Q7r8S9t0",
    "prefix": "zck_abc12345",
    "last4": "5t0",
    "expires_at": 1732982400000
  }
}

常见误用：

• 把 api_key 字段存数据库 → 应只存 key_id + prefix，明文交给业务方一次性
• scopes 列空数组以为是无权限 → 空数组实际代表完整继承当前 RBAC，要明确收窄就传具体权限 key

GET /api/sys/api-keys — 查询 API Key 列表

用途：在 API Key 管理页面展示当前用户/OEM 内的 Key 清单与状态。

鉴权：sys.apikey.list

输入参数：

输出字段（data.list[]）：

可见范围：

• 普通用户（role_id ≥ 10）：只看自己签发的
• 平台级用户（role_id < 10：超管/运维/审计员）：看本 OEM 全部

可视化建议：表格展示。status 用徽章（绿=active/灰=revoked），expires_at 即将到期（< 7d）建议高亮。配合 /stats 接口可做柱状图"调用量 TOP 5 Key"。

示例请求：

curl -H "Authorization: Bearer $TOKEN" \
  "https://waf.example.com/api/sys/api-keys?page=1&size=20"

DELETE /api/sys/api-keys/{id} — 吊销 API Key

用途：软吊销（status → revoked），保留审计痕迹。中间件认证时 status != active 直接拒绝。

鉴权：sys.apikey.delete

输入参数：

输出字段：data 为 null。

幂等性：重复吊销返回 200，前端反复操作不报错。

可操作范围：

• 普通用户：只能吊销自己签发的
• 平台级用户：可吊销本 OEM 内任意 key（管理止损用）

错误码：1051 API Key 不存在或不在可见范围。

可视化建议：不适合图表；前端"吊销"按钮触发，建议加二次确认对话框。

示例请求（用 API Key 调用）：

curl -X DELETE https://waf.example.com/api/sys/api-keys/8f21c0c5-55ae-4cbd-a60a-8e64a6e2b1d0 \
  -H "Authorization: ApiKey zck_abc12345.A1b2C3d4..."

GET /api/sys/api-keys/{id}/logs — 查询某 Key 的调用流水（E12）

用途：审计某条 API Key 的调用历史。返回该 Key 在审计表 api_key_audit_logs 中的事件列表。

鉴权：sys.apikey.logs

输入参数：

输出字段（每条记录）：

可视化建议：

• 推荐图表：表格 + 时序折线图（按 ctime 聚合调用次数）
• 派生指标：成功率柱状图（按 status_code 拆分 2xx/4xx/5xx）

可见范围：

• 普通用户：仅可查询自己签发的 Key
• 平台级用户：可查询本 OEM 内任意 Key（超管全库）

错误码：1051 API Key 不存在或不在可见范围。

GET /api/sys/api-keys/{id}/stats — 查询某 Key 的聚合统计

用途：在 API Key 详情页展示该 Key 的调用聚合 KPI（总次数、成功率、QPS、TOP 接口）。仅基于 event_type=call 的记录。

鉴权：sys.apikey.stats

输入参数：

输出字段：

可视化建议：

• 推荐图表：KPI 数字卡（4 个：total_calls / 成功率 / QPS / 错误数）+ 横向 bar 图（top_endpoints）
• 派生指标：饼图（success / client_err / server_err 三段占比）

错误码：400 since 解析失败；1051 API Key 不存在或不在可见范围。

示例请求：

curl -H "Authorization: Bearer $TOKEN" \
  "https://waf.example.com/api/sys/api-keys/8f21c0c5-55ae-4cbd-a60a-8e64a6e2b1d0/stats?since=24h"

GET /api/sys/api-keys/audit-actions — 查询管理操作流水（E13）

用途：跨 Key 的审计视图，返回 API Key 管理动作（创建 / 吊销 / 续期 / 批量吊销）的流水。

鉴权：sys.apikey.audit

输入参数：page / size，标准分页。

输出字段：与 GET /api/sys/api-keys/{id}/logs 相同；event_type 全部为 manage。

可见范围：

• 普通用户：只看自己作为操作人的记录（user_id = currentUserID）
• 平台级用户：本 OEM 全部（超管全库）

可视化建议：

• 推荐图表：表格（按 ctime 倒序）
• 派生指标：按 action 聚合的柱状图（create / revoke / renew / revoke-all 计数）

4.3 权限树

GET /api/sys/permissions/tree — 权限树

用途：返回当前 OEM 下的完整权限树（含模块/资源/动作三层 + i18n 名）。前端"角色权限"页用此渲染勾选树；签发 API Key 选 scope 时也用同一颗树。

鉴权：登录态（无具体权限要求）

输入参数：可附加 Accept-Language: en-US 切换权限名语言。

输出字段（节选，data[]）：

可视化建议：

• 推荐图表：三层树（n-tree / el-tree），module → resource → action
• 复用场景：API Key scope 选择器、角色权限分配勾选器

示例响应（节选）：

{
  "code": 0,
  "data": [
    {
      "module": "guard",
      "resources": [
        {
          "prefix": "guard.domain",
          "name": "域名",
          "actions": [
            { "key": "list",   "name": "列表",   "full_key": "guard.domain.list" },
            { "key": "view",   "name": "查看",   "full_key": "guard.domain.view" },
            { "key": "create", "name": "创建",   "full_key": "guard.domain.create" }
          ]
        }
      ]
    }
  ]
}

4.4 操作审计 /api/sys/audit-logs · /api/sys/login-records

前端「日志中心 › 操作审计」一页两个 Tab：操作日志与登录日志。两者共用 sys.audit.view 权限。

数据可见范围（重要）：在 repo 的 SQL 层收敛，按 role_id 分三档（handler 的 scopeOemID / scopeUserID）：

没有任何入参可以指定被查用户；keyword 虽能 LIKE 到 user_id / user_name，但与 scope 条件是 AND 关系，无法越权。

GET /api/sys/audit-logs — 操作日志

用途：控制台写操作的审计流水 —— 谁改了什么、改前改后、成功失败、是否代客操作。

鉴权：sys.audit.view

输入参数：

输出字段（节选，data.list[]，完整字段见 OpenAPI 的 AuditLog）：

标签真值表：写路由必须登记在 internal/middleware/audit_spec.go 的 productionAuditSpecs 里才有人话标签；纯查询型 POST 登记在 productionReadOnlyAuditPosts 里不记账。两张清单都没有的写路由会落库成 action=unregistered.business_operation + message=未登记业务操作，由 audit_spec_coverage_test.go 守着不再新增。

GET /api/sys/login-records — 登录日志

用途：登录 / 代登录流水 —— 谁何时从哪个 IP、用哪种方式登录，成功还是失败。

鉴权：sys.audit.view

输入参数：

输出字段（节选，data.list[]，完整字段见 OpenAPI 的 LoginRecord）：

§5 Guard 资源管理

📦 Guard 资源管理 · 30 个 endpoint · 用于配置防护对象（域名/证书/策略/CC&ACL 规则/名单/转发/调度/WAF 规则），是 WAF 防护能力的"配置面"
完整 schema 见 /api/openapi.json，本节给出对接最关键的字段名、枚举与典型踩坑点。

5.1 域名 /api/guard/domains

域名是 Guard 的核心资源——所有防护策略、证书绑定、统计聚合都以 domain_id 为锚点。

GET /api/guard/domains — 域名列表

用途：在"防护管理 - 域名"页面渲染域名表格，按审核状态筛选 + 关键字搜索。

鉴权：guard.domain.list

输入参数：

输出字段（data.list[] 即 DomainVO）：

可视化建议：

• 推荐图表：表格（主图）+ 顶部 KPI 卡片（总数 / 已通过 / 待审核）+ switches 用 chip 方阵渲染开关状态
• 派生指标：饼图（audit_status 4 状态占比）

示例请求：

curl -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  "https://waf.example.com/api/guard/domains?page=1&size=20&audit_status=4"

示例响应：

{
  "code": 0,
  "data": {
    "list": [
      {
        "domain_id": "d_8a3b1c",
        "domain": "api.example.com",
        "asset_name": "线上 API 网关",
        "user_id": "u_abc",
        "policy_id": "p_default",
        "cname": "api.example.com.cname.zcloud.io",
        "auto_cert": false,
        "mode": 1,
        "audit_status": 4,
        "switches": { "waf": 1, "cc": 1, "acl": 1, "bot": 0, "cache": 1 },
        "ctime": 1714521600000,
        "utime": 1714608000000
      }
    ],
    "total": 8,
    "page": 1,
    "size": 20
  }
}

常见误用：

• 用 page_size 分页 → 实际是 size，传 page_size 会被忽略
• 期望返回 protection_enabled / current_cert_id / origin_addr → 这些字段不存在；保护开关在 switches map 里，证书绑定走 /api/guard/certs/:id/domains 反查

POST /api/guard/domains — 创建域名

用途：在"添加域名"表单提交后调用，创建一条新的防护域名。

鉴权：guard.domain.create

输入参数（请求体 DomainCreateReq）：

policy_id 为什么必填：域名的 WAF、CC、访问控制、黑白名单、BOT 规则全部挂在策略上。不绑策略的域名会被正常代理，但一条防护规则都不生效 —— 接入了却不设防。

同地址同端口同协议的 src_sites 会被静默去重，不报错。

证书两条路都行：建域名时传 cert_id（域名 + 源站 + 绑证书在一个事务内完成，任一步失败整体回滚），或建完再调 POST /api/guard/certs/:id/bind。

输出字段：返回 DomainVO（结构同列表项），含分配的 domain_id 和 cname。

可视化建议：不适合图表。建议创建成功后立即跳转域名详情页或刷新列表。

GET /api/guard/domains/{id} — 域名详情

用途：进入域名详情页时拉单条详情。

鉴权：guard.domain.view

输入参数：path id = domain_id。

输出字段：DomainVO，与列表项完全一致。

可视化建议：表单展示。switches 渲染为开关组；audit_status 用徽章。

PUT /api/guard/domains/{id} — 更新域名

用途：编辑域名的资产名、策略绑定、自动证书等可变字段。

鉴权：guard.domain.edit

输入参数（请求体 DomainUpdateReq）：

输出字段：返回更新后的 DomainVO。

可视化建议：不适合图表。

DELETE /api/guard/domains/{id} — 删除域名

用途：从防护列表中移除域名。删除会级联清理 settings、证书绑定、统计快照。

鉴权：guard.domain.delete

输入参数：path id = domain_id。

输出字段：data 为 null。

可视化建议：不适合图表。建议删除前二次确认，提示"会清理统计与绑定"。

GET /api/guard/domains/{id}/settings — 域名设置查询

用途：在域名详情页"高级设置"标签下展示当前生效的 settings（保护模块开关、缓存策略、CC 限速等）。

鉴权：guard.domain.view

输入参数：path id = domain_id。

输出字段：

可视化建议：表单展示，每个 key 一行配置卡片。

GET /api/guard/domains/{id}/src-check-peers — 同源站探测对端查询（只读）

用途：探测在节点侧按源站 IP 跑，而不是按域名跑。同一用户名下多个域名回源到同一 IP 时，节点只跑一份探测，且取其中最小的监测频率 —— 于是会出现"界面写 60 秒、实际按 10 秒探测"而用户无从得知。本接口把共用源站且已开启探测的对端配置回显出来，解释实际生效值为何与本域名设置不同。

鉴权：guard.domain.settings（读的就是同一批域名设置，不另立权限点）

输入参数：path id = domain_id。

输出字段：

对端探测对象字段：detection_time_intervals（秒，已按对端取最小值）、action（4=只告警 5=切换流量并告警）、ports、fail_check_type、serial_failure_count、failure_ratio_windos、failure_ratio（0-100 整数百分比）。

语义要点：纯只读，不写任何库，也不改本域名的存量值 —— 存 60 就还是 60，只是实际跑 10。范围限定在同一用户名下（与 zmod where user_id = (...) 同口径），别人的域名共用同一 IP 不会出现在这里。

可视化建议：在源站探测配置区顶部以弱底提示条呈现，不用警示色（它不是错误，只是"你的设置可能不是实际生效值"）。

PUT /api/guard/domains/{id}/settings — 域名设置更新

用途：修改域名的 settings map。

鉴权：guard.domain.edit

输入参数（请求体 DomainSettingsUpdateReq）：

输出字段：data 为 null，调用方应紧接调用 GET 拉新值。

可视化建议：不适合图表。

常见误用：

• 把顶层布尔字段当 settings 传 → settings value 是 stringified JSON，不是 bool
• 自创不存在的 key → 后端按白名单校验，未知 key 返回 400

PUT /api/guard/domains/{id}/origins/{service_id}/status — 启停对外服务或源站

鉴权：guard.domain.origin_status

输入参数：path id（域名 ID）、service_id（源站配置里 src_configs[].service_id）。

源站配置有两级状态：对外服务（监听端口+协议）和组内单台源站，两级彼此独立——
「服务开着、组内某台单独关掉」是现网真实存在的状态。源站按 ip+port（+可选 line）定位，
不用下标：下标依赖调用方与存量顺序严格一致，中间增删过源站就会关错机器。

与 PUT /api/guard/domains/{id}/settings 的区别：那条收整包 JSON 字符串，由调用方读出-改-写回。
源站配置存在共库 guard_domain_settings.service_config_setting，老平台也在读写同一份，整包重建漏掉任何一个键都会写坏它。
本接口只声明「改哪一条的状态」，JSON 修改在服务端做，其余键（含本平台不认识的）原样保留。写入的是字符串枚举
CFGOPTION_2_ENABLE / CFGOPTION_1_DISABLE。

仍然生效：租户隔离、域名必须保留至少一个已启用的普通 HTTP/HTTPS 源站。状态变更触发配置下发。

输出字段：无。

GET /api/guard/domains/{id}/dns/advance/config — 解析高级配置查询

用途：查询解析调度的高级配置：自动回源、节点解析最少开启数、IPv6 检查。字段对齐 zmod「解析高级配置」对话框与 gen-server DnsAdvanceConfig。

鉴权：guard.domain.settings（disp_config_setting 本就在通用 settings 接口白名单里，同一份数据换个入口，不另立权限点）。

输入参数：path id = domain_id。

输出字段（data 即 DnsAdvanceConfigVO）：

语义要点：src_ipv6_check / default_ipv6_check 任一开启时，「初始化解析」才会为支持 IPv6 的节点/源站生成 AAAA 记录（IPv4/IPv6 双栈接入的开关就在这里）。

示例请求：

curl -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/dns/advance/config"

PUT /api/guard/domains/{id}/dns/advance/config — 解析高级配置更新

用途：修改解析高级配置。与 zmod 界面同构：只写下表四个字段，disp_config_setting 存量里其余 key（total_count/ava_ratio/max_count/auto_switch/cname 等）服务端原样保留。

鉴权：guard.domain.settings

输入参数（请求体 DnsAdvanceConfigUpdateReq，四字段均必填）：

输出字段：data 为 null。

语义要点：保存不会立刻改动现有解析记录；IPv6 开关在下一次「初始化解析」（POST /api/guard/schedules/domains/{id}/init）时生效（含 AAAA 记录的增删）。枚举必须传字符串名——数字形态会被 gen-server 侧 types.CFGOPTION 拒绝。

示例请求：

curl -X PUT -H "Authorization: ApiKey $ZCLOUD_API_KEY" -H "Content-Type: application/json" \
  -d '{"auto_switch_case":1,"auto_return_source":"CFGOPTION_1_DISABLE","src_ipv6_check":"CFGOPTION_2_ENABLE","default_ipv6_check":"CFGOPTION_2_ENABLE"}' \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/dns/advance/config"

域名接入 UX 改造 · 后端接口盘点（2026-06-26）

前端正在把域名管理页升级为「列表行内跳转 → 域名工作台 → 接入向导」三段式 UX。盘点结论：大部分是前端编排现有接口；域名工作台（Phase 2）落地后实测发现 2 处需后端补充（见表后「实测后端补充」）。对应关系：

已补充 ①（工作台详情字段）

GET /api/guard/domains/{id} 在现有 DomainVO 上已追加 cert_id + nodes + shadow_cache_addr。其中 settings、parsing_state 仍按既有设计走独立端点（GET /domains/{id}/settings、GET /schedules/domains）。

目标响应形状（在现有 DomainVO 上加 2 字段，对齐前端 DomainDetailVO）：

{
  "domain_id": "...", "domain": "...", "cname": "...", "switches": {},
  "cert_id": 12,
  "shadow_cache_addr": "192.168.14.103",
  "nodes": [
    { "id": 1, "ip_addr": "1.2.3.4", "node_id": "n-001", "enabled": 1, "line": 0 }
  ]
}

前端可直接读 detail.cert_id（再 GET /certs/{id} 取 common_name/到期/cert_type）和 detail.nodes（节点表）。

接入向导用法（①.5）：POST /domains 现已直接消费 src_sites + cert_id，域名、源站配置、证书绑定在一个事务内完成，任一步失败整体回滚。向导即按此一次建好，不再走「建域 → 逐源站 POST /forwards → POST /certs/{id}/bind/{domainId}」的多请求变通。旧的分步接口仍然可用，用于给已存在的域名追加源站或换绑证书。

POST /api/guard/domains/{id}/verify — 域名接入主动探测

用途：向导「接入验证」步骤主动检查源站可达性与公网 DNS 是否已指向分配的 CNAME。

鉴权：guard.domain.verify

输入参数：path id = domain_id。

输出字段：

回源分组 /api/guard/domains/{id}/origin-groups

回源分组：一个分组 = 一批防护节点绑定其回源的源站子集，让"哪台防护节点回哪些源站"可控（如电信节点回电信源站）。每个域名恰好有 1 个默认回源组（承载全部源站、禁删、未分组节点的兜底）；节点在域名内唯一归组；组内源站含 IPv6 时必须至少含一个支持 IPv6 的节点。3 个接口鉴权均为 guard.domain.origin_group。

GET /api/guard/domains/{id}/origin-groups — 回源分组列表

用途：查询该域名回源分组列表（默认组+自定义组，默认组排最前）。

鉴权：guard.domain.origin_group

输入参数：path id = domain_id。

输出字段（data.list[] 即 OriginGroupVO）：

示例请求：

curl -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/origin-groups"

POST /api/guard/domains/{id}/origin-groups — 新建回源分组

用途：归组操作——所选节点从原组拉入新组，被拉空的自定义组自动删除并回归默认组。节点/源站元数据由服务端回填，客户端只传标识。

鉴权：guard.domain.origin_group

输入参数（path id = domain_id；请求体 OriginGroupCreateReq）：

输出字段：data 为新建分组的 OriginGroupVO（字段同列表项）。

错误（400）：分组名冲突/保留、默认组不存在、节点不在域名绑定列表、源站不在源站配置、组内源站含 IPv6 但无支持 IPv6 的节点。

示例请求：

curl -X POST -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"电信组","node_ids":["n-a","n-b"],"src_ips":["10.0.0.1","10.0.0.2"]}' \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/origin-groups"

DELETE /api/guard/domains/{id}/origin-groups/{group_id} — 删除自定义分组

用途：删除自定义回源分组，组内节点/源站并回默认组；默认回源组禁删。

鉴权：guard.domain.origin_group

输入参数：path id = domain_id，path group_id = 分组 ID（int64）。

输出字段：

错误：404 分组不存在；400 默认回源组禁删。

示例请求：

curl -X DELETE -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/origin-groups/5301"

PUT /api/guard/domains/{id}/audit — 域名审核

用途：审核域名。新建域名默认 audit_status=1（未审核），未过审的域名不会下发到防护节点；置为 4（通过）后自动触发配置下发。

鉴权：仅平台级角色（role_id < 10）且持有 guard.domain.audit；业务角色即使被误授该权限也返回 403。

输入参数（path id = domain_id；请求体）：

输出字段：

错误：400 audit_status 参数非法；403 非平台角色或权限不足；404 域名不存在或无权访问。

示例请求：

curl -X PUT -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audit_status":4}' \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/audit"

域名节点分配 /api/guard/domains/{id}/nodes

节点分配：域名绑定哪些防护节点，决定其流量由哪些节点承载与清洗。5 个按域名接口鉴权均为 guard.domain.node；分配/移除成功都会触发配置重新下发，锁定只改状态不下发。另有运维对账入口 POST /api/guard/domains/nodes/sync（guard.domain.edit，前端不暴露、仅 CLI），见本节末尾。

GET /api/guard/domains/{id}/nodes — 已分配节点列表

用途：查询域名已分配的防护节点（含锁定状态与节点元数据）。

鉴权：guard.domain.node

输入参数：path id = domain_id。

输出字段（data.list[] 即 DomainAssignedNodeVO）：

错误：404 域名不存在或无权访问。

示例请求：

curl -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/nodes"

GET /api/guard/domains/{id}/nodes/available — 可分配节点列表

用途：查询该域名还可分配的节点（账号节点池 − 已分配）。

鉴权：guard.domain.node

输入参数：path id = domain_id。

输出字段（data.list[] 即 AssignableNodeVO）：node_id / name / machine_room / ip_addr / line / ipv6（含义同上表，无 lock_status）。

错误：404 域名不存在或无权访问。

示例请求：

curl -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/nodes/available"

PUT /api/guard/domains/{id}/nodes — 分配节点

用途：分配节点到域名（增量追加，重复分配的节点自动跳过）。节点同时同步进 CNAME 解析记录：enable_parse=true 时同时开启解析记录（节点调度模式下生效；回源模式只同步 last_status，下次加速自动开启）；不勾选时记录会创建但不开启。成功后触发配置重新下发。

鉴权：guard.domain.node

输入参数（path id = domain_id；请求体 DomainNodeAssignReq）：

输出字段（data 即 DomainNodeAssignResultVO）：

错误：400 所选节点不可分配（不在账号节点池内或已分配给该域名）；404 域名不存在或无权访问。

示例请求：

curl -X PUT -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"node_ids":["n-a","n-b"],"enable_parse":false}' \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/nodes"

DELETE /api/guard/domains/{id}/nodes/{node_id} — 移除节点

用途：从域名移除节点。成功后触发配置重新下发。

鉴权：guard.domain.node

输入参数：path id = domain_id，path node_id = 节点 ID。

保护性拒绝（400）：

• 该节点的解析记录仍在启用中（请先停用解析）；
• 解析停用不足 30 分钟（防 DNS 缓存导致流量黑洞）；
• 节点 IP 正被端口转发规则引用（请先调整端口转发配置）；
• 节点调度模式下移除会删空默认线路（请先为其他节点配置默认线路）。

输出字段：

错误：400 见上方保护性拒绝；404 域名不存在或该节点未分配给此域名。

示例请求：

curl -X DELETE -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/nodes/n-a"

PATCH /api/guard/domains/{id}/nodes/{node_id}/lock — 锁定/解锁节点

用途：锁定/解锁域名节点。锁定（2）后配置渲染与下发跳过该节点，绑定关系保留；解锁（1）恢复。只改状态，不触发重新下发。

鉴权：guard.domain.node

输入参数（path id = domain_id，path node_id = 节点 ID；请求体 DomainNodeLockReq）：

输出字段：

错误：400 锁定状态无效（仅允许 1/2）；404 域名不存在或该节点未分配给此域名。

示例请求：

curl -X PATCH -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lock_status":2}' \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/nodes/n-a/lock"

POST /api/guard/domains/nodes/sync — 节点分配运维对账

用途：运维对账工具——把所有域名的节点绑定与上层（aeg）的用户节点分配全量对齐（多退少补），节点被收回后跑一次可批量清理幽灵绑定。会覆盖按域名的手动精细分配，日常增量分配请用 PUT /api/guard/domains/{id}/nodes。前端已不再暴露此入口（仅 CLI zcloud guard domains nodes sync）。发生变更的域名触发配置重新下发。

鉴权：guard.domain.edit。平台级用户可用 ?user_id= 定向对账某个客户，业务级用户只对账自己的域名。

输入参数：query user_id（可选）= 只对账指定用户的域名。

输出字段（data 即 DomainNodeSyncVO）：

示例请求：

curl -X POST -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  "https://waf.example.com/api/guard/domains/nodes/sync"

域名防暴力破解规则 /api/guard/domains/{id}/brute-force/rules

防暴力破解：域名级请求频率规则——同一源 IP / Bot 会话在统计时长内对指定 URI 的请求次数超过阈值后执行处置动作（封禁/跳转/验证码等）。规则存共享表并联动下发；4 个接口鉴权均为 guard.domain.bruteforce；新增/更新/删除成功都会触发配置重新下发。弱密码拦截配置不在本组接口，走已有域名设置接口的 guard_weak_password_setting 项（GET/PUT /api/guard/domains/{id}/settings）。

GET /api/guard/domains/{id}/brute-force/rules — 规则列表

用途：查询域名的防暴力破解规则（按规则 ID 降序）。

鉴权：guard.domain.bruteforce

输入参数：path id = domain_id。

输出字段（data.list[] 即 BruteForceRuleVO）：

action 对象字段：

错误：404 域名不存在或无权访问。

示例请求：

curl -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/brute-force/rules"

POST /api/guard/domains/{id}/brute-force/rules — 新增规则

用途：新增防暴力破解规则。规则 ID 服务端生成；status 服务端强制 true（新增即启用）。成功后触发配置重新下发。

鉴权：guard.domain.bruteforce

输入参数（path id = domain_id；请求体 BruteForceRuleCreateReq，字段同上方 BruteForceRuleVO，无 id）。注意：

• 单位字段（req_time_unit / action.block_time_unit / action.window_unit）只接受枚举名字符串 ReqUnit_1_PSec / ReqUnit_2_PMin（传数字会解析失败）；level 只接受 ip / bot_session。传其他值返回 400。
• action.action_type 服务端不强校验、原样存储（对齐老平台），合法值以上表为准。
• status 传入值被忽略，创建后恒为 true。

输出字段（data 即创建后的 BruteForceRuleVO，含服务端生成的 id）。

错误：400 请求体/枚举值非法；404 域名不存在或无权访问。

示例请求：

curl -X POST -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"login-guard","describe":"登录接口限速","uri":"/login","rate":10,"rate_time":60,"req_time_unit":"ReqUnit_1_PSec","level":"ip","action":{"action_type":"block","block_time":10,"block_time_unit":"ReqUnit_2_PMin"}}' \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/brute-force/rules"

PUT /api/guard/domains/{id}/brute-force/rules/{rule_id} — 更新规则

用途：更新防暴力破解规则——白名单字段（name/describe/uri/rate/rate_time/req_time_unit/status/level/action）整行覆盖，未提供的字段按零值写入；rule_id 必须属于该域名（防跨域名改共享表）。status 按请求值落库（可用于停用规则）。成功后触发配置重新下发。

鉴权：guard.domain.bruteforce

输入参数：path id = domain_id，path rule_id = 规则 ID；请求体 BruteForceRuleUpdateReq（字段与新增一致，枚举约束同上）。

输出字段（data 即更新后的 BruteForceRuleVO）。

错误：400 请求体/枚举值非法或 rule_id 非数字；404 域名不存在、规则不存在或不属于该域名。

示例请求：

curl -X PUT -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"login-guard","describe":"登录接口限速","uri":"/login","rate":20,"rate_time":1,"req_time_unit":"ReqUnit_2_PMin","status":true,"level":"bot_session","action":{"action_type":"captcha"}}' \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/brute-force/rules/20220414"

DELETE /api/guard/domains/{id}/brute-force/rules/{rule_id} — 删除规则

用途：删除防暴力破解规则（域名关联摘除 + 物理删行）；rule_id 必须属于该域名。成功后触发配置重新下发。

鉴权：guard.domain.bruteforce

输入参数：path id = domain_id，path rule_id = 规则 ID。

输出字段：

错误：400 rule_id 非数字；404 域名不存在、规则不存在或不属于该域名。

示例请求：

curl -X DELETE -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/brute-force/rules/20220414"

域名缓存动作 /api/guard/domains/{id}/cache

缓存动作：对域名的 CDN 缓存做预热/清理。两个接口均为异步语义：服务端按域名节点关系与对外服务配置构造 CDN 缓存指令，经老平台 gen-service（zRPC cmd=554 → MQ）下发节点执行，发送即返回——不落库、无执行结果查询接口，返回成功仅代表指令已提交下发通道。两个接口鉴权均为 guard.domain.cache。缓存规则/高级配置/预热资源列表不在本组接口，走已有域名设置接口的 cache_config_v2_setting 项（GET/PUT /api/guard/domains/{id}/settings）。

POST /api/guard/domains/{id}/cache/warm — 预热缓存资源

用途：预热指定资源到节点缓存（对齐老平台"缓存预热"，缓存指令 cmd_type=2）。异步：发送即返回。

鉴权：guard.domain.cache

输入参数（path id = domain_id；请求体）：

输出字段：

错误：400 请求体非法、域名未分配节点、对外服务配置（service_config_setting）缺失或非法；404 域名不存在或无权访问；500 下发通道不可用。

示例请求：

curl -X POST -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cache_res":"/index.html,/static/app.js"}' \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/cache/warm"

POST /api/guard/domains/{id}/cache/purge — 清理缓存资源

用途：清理节点上指定资源的缓存（对齐老平台"缓存清理"，缓存指令 cmd_type=1）。异步：发送即返回。

鉴权：guard.domain.cache

输入参数（path id = domain_id；请求体）：

输出字段：

错误：400 请求体非法、域名未分配节点、对外服务配置（service_config_setting）缺失或非法；404 域名不存在或无权访问；500 下发通道不可用。

示例请求：

curl -X POST -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cache_res":"/index.html,/static/app.js"}' \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/cache/purge"

5.2 证书 /api/guard/certs

证书管理走"上传 PEM 文本 → 绑定域名"两步流程；Content-Type 是 application/json，不是 multipart/form-data。

三种证书类型（certificate_type，与老平台共库同值）：

ssl_password_file（加密证书凭证/私钥口令）对类型 1、2 可选，类型 3 无本地私钥因而忽略。

GET /api/guard/certs — 证书列表

用途："防护管理 - 证书"页面表格。

鉴权：guard.cert.list

输入参数：page / size / keyword（搜索 name/common_name）。

输出字段（data.list[] = CertVO）：

不存在 bound_domains 字段；要查证书绑定哪些域名，调 GET /api/guard/certs/{id}/domains。

可视化建议：

• 推荐图表：表格 + 即将到期高亮（expired_at - now < 30d 染色）
• 派生指标：KPI 卡（总数 / 30d 内到期数 / 已过期数）；饼图（auto_cert true/false 占比）

POST /api/guard/certs — 上传证书

用途：上传一条 PEM 证书。客户对接最容易踩的坑就是误用 multipart/form-data，请务必用 JSON。

鉴权：guard.cert.create

安全提示：直接集成本接口时，cert / key 仍按 JSON PEM 文本传入；但不要把私钥写入 AI 对话、工单、日志或可观测埋点。若通过 Aegeon Cloud 对话助手操作证书，优先使用其"安全证书附件"上传入口：浏览器将证书/私钥上传到 Aegeon 后只在对话中保留附件引用，私钥不会进入 AI 消息内容。

输入参数（请求体 CertUploadReq，application/json）：

输出字段：返回新建 CertVO。

可视化建议：不适合图表。前端上传组件应支持"粘贴 PEM 文本"和"读取本地文件"两种方式。

示例请求：

curl -X POST https://waf.example.com/api/guard/certs \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"prod-2026","cert":"-----BEGIN CERTIFICATE-----\nMII...\n-----END CERTIFICATE-----","key":"-----BEGIN PRIVATE KEY-----\nMII...\n-----END PRIVATE KEY-----"}'

国密 / 无私钥示例：

# 国密 NTLS：签名对 + 加密对四份材料缺一不可
curl -X POST https://waf.example.com/api/guard/certs \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"gm-2026","certificate_type":2,"sign_cert":"-----BEGIN CERTIFICATE-----\n...","sign_key":"-----BEGIN PRIVATE KEY-----\n...","cert":"-----BEGIN CERTIFICATE-----\n...","key":"-----BEGIN PRIVATE KEY-----\n..."}'

# 无私钥：只传证书 + keyless 服务器地址
curl -X POST https://waf.example.com/api/guard/certs \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"keyless-2026","certificate_type":3,"cert":"-----BEGIN CERTIFICATE-----\n...","no_key_tls_addr":"10.0.0.9:8443"}'

常见误用：

• 用 multipart/form-data 上传文件 → 后端不支持，返回 400
• 类型 2 只传 sign_cert/sign_key 不传加密对 → 400，国密四份材料缺一不可
• 类型 3 漏传 no_key_tls_addr → 400，节点靠它连 keyless 服务器
• 国密材料不是 SM2（塞了 RSA/ECDSA PEM）→ 400。老平台此处会丢弃解析错误照样入库，cloud 有意收紧，把问题挡在下发之前
• cert / key 字段传文件路径 → 必须是 PEM 文本字符串本身
• 将私钥原文放进 AI 对话或日志 → 应使用安全附件/密钥托管路径，仅在服务端短暂解密后调用本接口

GET /api/guard/certs/{id} — 证书详情

用途：详情页展示，含完整 PEM 文本。

鉴权：guard.cert.view

输入参数：path id。

输出字段：CertDetailVO = CertVO + cert + sign_cert（PEM 文本，方便下载）+ no_key_tls_addr + has_ssl_password。

私钥材料（key / sign_key）一律不回显。no_key_tls_addr 不是密钥，随详情返回供编辑回填。
口令（ssl_password_file）也不回显原文，只返回布尔 has_ssl_password —— 它是解私钥的凭证，回显等于让任何有 guard.cert.view 的只读账号取走。老平台同样只进不出。
因此前端编辑时「口令留空」只能表示保持原口令；要清空必须显式提交空串。

可视化建议：表单展示。可加"下载证书"按钮（前端拼 PEM 触发下载）。

Keyless 安装包接口

下载权限为 guard.cert.download；接口只返回公开发布包的元数据或安装包，
不接收、拼接或记录业务私钥。首次部署不需要先创建 certificate_type=3
证书：必须先安装 Keyless，才能获得后续表单需要填写的 HOST:8443。

GET /api/guard/keyless/package 返回版本、支持的 Linux 架构、ZIP 验证包及其
内含 tar.gz 的 SHA-256、完整性校验状态和使用说明。每个
发行版本在受控 CI 中由仓库内固化、仅含源码的 KeyServer 快照交叉编译
amd64/arm64，随后连同 SHA-256 校验文件写入不可变 Cloud 后端镜像；
后端再次核对完整性后才显示下载入口。发布目录默认是 /app/releases/keyless。

POST /api/guard/keyless/package/download

请求体：

{"arch":"amd64"}

响应是 ZIP 验证包，并带 X-Artifact-SHA256。ZIP 内有 tar.gz、其 SHA-256、
VERIFY.txt；先按 VERIFY.txt 在解压 tar.gz 前验证，再执行安装。下载动作写入
操作审计。校验和、包结构任一项
不通过时不会提供下载。安装包内提供 verify-package.sh、install.sh、
provision.sh、restart.sh、status.sh 和 verify-transport.sh，完整使用方法见
安装包内 docs/QUICKSTART.md；首次安装可执行：

sudo ./scripts/install.sh --copy-private-key-file /absolute/path/to/business.key --enable

推荐的一键安装方式只在目标 Linux 主机读取并校验源私钥，再复制到
/etc/keyless/keys/business.key（keyless:keyless、0600）；源文件不修改、
不上传平台。保留原始路径的高级方式仍可使用 --private-key-file 或手工编辑
user.yml，但必须自行保证 keyless 用户可读取该文件并可进入所有父目录。

服务启动并确认可达 HOST:8443 后，再在平台新建无私钥证书、粘贴匹配的
公开 fullchain 并填写该地址。KeyServer 只读取目标 Linux 主机上的未加密
RSA PEM/DER 私钥，不读取平台证书链。TLS 连通检查不等于远程签名已验证。

已有无私钥证书的集成可继续使用兼容接口
/api/guard/certs/{id}/keyless/package 和
/api/guard/certs/{id}/keyless/package/download；新界面和首次部署应使用
不依赖证书记录的全局接口。

PUT /api/guard/certs/{id} — 更新证书

用途：直接替换 PEM 文本（无需先删后建）。

鉴权：guard.cert.edit

输入参数（请求体 CertUpdateReq，字段同 Upload 但全部可选）：name / certificate_type / cert / key / sign_cert / sign_key / no_key_tls_addr / ssl_password_file。

• 各字段以空串表示"本次不改"；ssl_password_file 例外——它用 JSON null/缺省表示不改，空串表示清空口令。
• 未提交的材料沿用库里已有的（例如无私钥证书只改 no_key_tls_addr 时，证书自动沿用，不必重贴 PEM）—— 但仅限 certificate_type 未变时。
• 不传 certificate_type 表示保持原类型；切换类型时后端整包重建，会显式清零互斥字段（标准 → 无私钥清掉 key，国密 → 标准清掉 sign_cert/sign_key）。换类型时私钥、签名对、无私钥地址一律不沿用，必须重新提交（证书 cert 本身可沿用）。
• 换证书仍要覆盖已绑定域名：新材料的 CN/SAN 不覆盖某个已绑定域名时返回 400，需先解绑。

输出字段：返回更新后的 CertVO。

DELETE /api/guard/certs/{id} — 删除证书

鉴权：guard.cert.delete

输入参数：path id。

输出字段：data 为 null。

副作用：删除前会自动解绑该证书绑定的所有域名。

GET /api/guard/certs/{id}/domains — 查询证书已绑定的域名

用途：在证书详情页展示"该证书正在保护哪些域名"。

鉴权：guard.cert.view

输入参数：path id。

输出字段（data[] = CertDomainVO[]）：

可视化建议：表格展示。

POST /api/guard/certs/{id}/bind — 绑定证书到域名

用途：把指定证书绑到一个域名上。

鉴权：guard.cert.edit

输入参数（请求体 CertBindReq）：

输出字段：data 为 null。

可视化建议：不适合图表。

DELETE /api/guard/certs/{id}/bind/{domainId} — 解绑证书与域名

用途：解除证书与某个域名的绑定关系。

鉴权：guard.cert.edit

输入参数：path id = 证书 ID；path domainId = 域名 ID。

输出字段：data 为 null。

路径：是 DELETE /bind/{domainId}，不是 POST /unbind。

证书管理 UX 改造 · 后端补充盘点（2026-06-29）

前端正在重设计证书管理页(到期概要 + 绑定域名 + 国密上传)。盘点结论：核心能力后端已具备(列表 / 上传含国密 sign_cert·sign_key / 详情含 PEM / 绑定·解绑 / GET /certs/{id}/domains),重设计主要是前端补类型 + 接线。下列为建议后端补充 / 澄清项：

无需后端:SAN 列表 / 指纹 / 序列号 / 密钥长度等详情字段,前端可从 GET /certs/{id} 返回的 cert(PEM 全文)客户端解析,不必后端加字段。
前端待对齐(非后端项,备忘):前端 CertVO 类型为旧字段(cert_type/user_id),实际后端是 certificate_type/user_name;CertDetailVO.domains[] 后端不存在(绑定域名走 GET /certs/{id}/domains)。这些是前端要改的,不劳后端。

5.3 策略 /api/guard/policies

策略是规则的容器：CC / ACL / 黑白名单 都挂在策略下。一个域名绑一个策略。

GET /api/guard/policies — 策略列表

鉴权：guard.policy.list

输入参数：page / size / keyword。

输出字段（data.list[] = PolicyVO）：

switches 同时出现在创建 / 详情 / 列表响应里（三者共用同一 VO），域名接入向导据此展示所选策略当前开了哪些防护。新建策略的默认档：waf=GuardMode_3_Enable、cc / acl / ddos / anti_crawler / black_white_list / user_priority = CFGOPTION_2_ENABLE，其余为 CFGOPTION_1_DISABLE（geo / acl_rule 保持 CFGOPTION_0_UNKNOWN）。

可视化建议：表格 + 三个 chip（cc/bwl/acl 数量）。

POST /api/guard/policies — 创建策略

鉴权：guard.policy.create

输入参数（PolicyCreateReq）：name（必填）/ comment。

重名口径：按属主（user_id）判定，不是全局唯一——不同用户可以使用相同的策略名。同一属主下已存在同名策略时不报错，服务端自动追加 _01/_02… 序号后缀放行（与老平台 zmod CheckPolicyNameAlready 一致）；名称本身已带 _0N 后缀时先剥掉后缀再从 _01 起找空位。

输出字段：返回新建 PolicyVO。实际落库的名称以 data.name 为准，可能与请求里的 name 不同，请据此回显给用户。

GET /api/guard/policies/{id} — 策略详情

鉴权：guard.policy.view

输入参数：path id。

输出字段：PolicyVO。

PUT /api/guard/policies/{id} — 更新策略

鉴权：guard.policy.edit

输入参数（PolicyUpdateReq）：name / comment。

重名口径：改名时在该策略属主名下查重（排除自身），与老平台 zmod「修改防护策略」一致；撞名直接返回业务码 2004（err.guard.policy.name_exists），不会像创建那样自动加后缀。

输出字段：返回更新后的 PolicyVO。

DELETE /api/guard/policies/{id} — 删除策略

鉴权：guard.policy.delete

输入参数：path id。

输出字段：data 为 null。删除前需保证该策略未被任何域名引用。

POST /api/guard/policies/{id}/copy — 复制策略

鉴权：guard.policy.copy

输入参数：path id（源策略）。请求体全部可选：

深拷贝源策略的全部配置 blob（界面没有的字段原样保留）与三张 live 规则子表（WAF 精准规则组+条目、CC 规则、访问控制规则），子表换新 ID、blob 内的 ID 数组同步重写。源策略不受影响。输出字段：data 为新策略 VO。

GET /api/guard/policies/{id}/geo-config — 查询区域封禁配置

鉴权:guard.policy.view

返回 guard_policies.geo_config 的友好视图:mode(black=黑名单/white=白名单)、oversea(拒绝国外访问)、world_list/prov_list/city_list(国家/省份/城市)、custom_list(例外 IP 名单组)、stime/etime(生效整点,0-0=全天)、enabled(switches.geo 开关,只读)。

PUT /api/guard/policies/{id}/geo-config — 更新区域封禁配置

鉴权:guard.policy.edit

输入:mode(必填 black|white)/ oversea / world_list / prov_list / city_list / custom_list / stime / etime(0-23)。

custom_list(例外 IP 名单组)省略即保留服务端原值,显式传数组才写入(传 [] = 清空)。Cloud 访问控制界面不提供该项,zcloud guard policies geo-config update 也不下发它,以免覆盖已有的名单组绑定。

只落库不下发:变更计入待下发,统一走 POST /policies/{id}/publish。请求未包含的存量字段原样保留。

GET /api/guard/policies/{id}/sensitive-config — 查询敏感信息保护配置

鉴权:guard.policy.view

返回 guard_policies.sensitive_config 的透传视图:hide_sensitive(脱敏枚举位掩码 enum_sensitive + 枚举键数组 enum_sensitives + 自定义敏感信息 src_str)、info_leakage(信息泄漏防护)、hide_head(隐藏的服务信息头)、status_codes(异常状态码保护清单)、enabled(switches.sensitive_protection 开关,只读)。

PUT /api/guard/policies/{id}/sensitive-config — 更新敏感信息保护配置

鉴权:guard.policy.edit

输入:config(必填,整包 JSON:hide_sensitive / info_leakage / hide_head / status_codes)/ enabled(可选,同步 sensitive_protection 开关)。

config 整包透传:gen-server 拥有完整 schema,cloud 只落库并触发下发,请求未包含的存量字段原样保留。

GET /api/guard/policies/{id}/crawler-config — 查询网页防爬虫配置

鉴权:guard.policy.view

返回 guard_policies.crawler_config 的透传视图:search_engine/scanner/script_tool/other(四类识别拦截开关)、robots(自定义 robots.txt)、limit_often_err_req + limit_often_err_req_cfg(高频错误请求限制:default_code/custom_code/limit_rate/limit_rate_time(_unit)/deny_time(_unit))、enabled(switches.anti_crawler,只读)。

PUT /api/guard/policies/{id}/crawler-config — 更新网页防爬虫配置

鉴权:guard.policy.edit

输入:config(必填,整包 JSON)/ enabled(可选,同步 anti_crawler 开关)。整包透传,未包含的存量字段原样保留;落库并触发下发。

GET /api/guard/policies/{id}/global-blacklist-config — 查询全网协同防御配置

鉴权:guard.policy.view

返回 guard_policies.global_blacklist_config 的透传视图:block_time(恶意 IP 加入动态黑名单后的拦截时长,秒,候选 100/300/400/500/1000)、enabled(switches.global_blacklist,只读)。

PUT /api/guard/policies/{id}/global-blacklist-config — 更新全网协同防御配置

鉴权:guard.policy.edit

输入:config(必填,{block_time})/ enabled(可选,同步 global_blacklist 开关)。落库并触发下发。

GET /api/guard/policies/{id}/pending-changes — 待下发变更

鉴权:guard.policy.view

返回:dirty(策略修改时间晚于最近下发,从未下发视为 true)、last_modified_at、last_apply、changes[](最近下发之后 cloud 侧的操作明细:action/resource_label/detail 字段级 diff/oper_name/ctime)。老平台界面同期修改只反映在 dirty,不出现在 changes。

PUT /api/guard/policies/{id}/features/{featureKey} — 能力开关

鉴权:guard.policy.edit

输入:enabled(布尔);featureKey=waf 时可传 mode(disable=关闭/log=记录/block=拦截,填了 mode 则忽略 enabled)。

可用 featureKey:waf / cc / geo / global-blacklist / one-key-close / one-key-lock / tamper / sensitive / brute-force / crawler / web-lock。

5.4 CC 规则 /api/guard/policies/{id}/cc/rules

CC = HTTP 速率限制规则（Connection / Concurrency Control）。挂在策略下，按 policy_id 隔离。

GET /api/guard/policies/{id}/cc/rules — CC 规则列表

鉴权：guard.cc.list

输入参数：path id = policy_id；query page / size。

输出字段（data.list[] = CcRuleVO）：

可视化建议：表格 + status 徽章。matches 太复杂建议折叠为"详情"按钮弹出。

POST /api/guard/policies/{id}/cc/rules — 创建 CC 规则

鉴权：guard.cc.create

输入参数（CcRuleCreateReq）：

复杂结构建议先调 list 取一条样本作为模板。

输出字段：返回新建 CcRuleVO。

GET /api/guard/policies/{id}/cc/rules/{rid} — CC 规则详情

鉴权：guard.cc.view

输入参数：path id = policy_id，rid = rule_id。会校验 rule_id 是否归属当前 policy_id，跨策略读取返回 NotFound。

输出字段：CcRuleVO。

PUT /api/guard/policies/{id}/cc/rules/{rid} — 更新 CC 规则

鉴权：guard.cc.edit

输入参数：path id + rid，body 同 Create。

输出字段：返回更新后的 CcRuleVO。

DELETE /api/guard/policies/{id}/cc/rules/{rid} — 删除 CC 规则

鉴权：guard.cc.delete

输入参数：path id + rid。

输出字段：data 为 null。

PUT /api/guard/policies/{id}/cc/rules/{rid}/status — 切换 CC 规则状态

用途：在列表页用开关组件启用/禁用规则。

鉴权：guard.cc.edit

输入参数（CcRuleStatusReq）：

重要：status 是 int32 数字，不是 "enabled" / "disabled" 字符串。

输出字段：data 为 null。

示例请求：

curl -X PUT https://waf.example.com/api/guard/policies/p_default/cc/rules/12345/status \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"status":1}'

5.5 ACL 规则 /api/guard/policies/{id}/acl/rules

ACL = 访问控制列表（基于 IP / Header / URI 的放行/拦截）。结构与 CC 规则相似但没有 priority 字段。

GET /api/guard/policies/{id}/acl/rules — ACL 规则列表

鉴权：guard.acl.list

输入参数：path id，query page / size。

输出字段（data.list[] = AclRuleVO）：

可视化建议：表格 + status 徽章 + action.type chip 染色（block 红 / pass 绿 / page 蓝）。

POST /api/guard/policies/{id}/acl/rules — 创建 ACL 规则

鉴权：guard.acl.create

输入参数（AclRuleCreateReq）：name / describe / matches[]（≥1）/ action / stime / etime。

action.type 为 block / page 时 content 字段服务端会 base64 编码存储；调用方传明文。

输出字段：返回新建 AclRuleVO。

GET /api/guard/policies/{id}/acl/rules/{rid} — ACL 规则详情

鉴权：guard.acl.view

输入参数：path id + rid。

输出字段：AclRuleVO。

PUT /api/guard/policies/{id}/acl/rules/{rid} — 更新 ACL 规则

鉴权：guard.acl.edit

输入参数：path id + rid，body 同 Create。

输出字段：返回更新后的 AclRuleVO。

DELETE /api/guard/policies/{id}/acl/rules/{rid} — 删除 ACL 规则

鉴权：guard.acl.delete

输入参数：path id + rid。

输出字段：data 为 null。

PUT /api/guard/policies/{id}/acl/rules/{rid}/status — 切换 ACL 规则状态

鉴权：guard.acl.edit

输入参数（AclRuleStatusReq）：status int32（1=启用 2=禁用，数字）。

输出字段：data 为 null。

5.6 黑白名单 /api/guard/bwlist

黑白名单分两层：集合（set） 是逻辑容器（黑/白名单），IP 是集合内的具体条目。每个集合自带生效范围（scope）：all=对当前用户全部域名生效（含后续新增域名），selected=只对指定域名生效。集合与域名的绑定由后端自动写入域名配置并触发下发，无需再到域名或策略下单独开开关。

存量兼容：早期集合通过 policy_id 绑定策略生效（此时 scope_type 返回 policy），仍继续工作；编辑该集合并选择新生效范围后自动迁移并解绑 policy_id。灰黑（3）/灰白（4）名单已废弃，列表默认不返回（include_grey=true 可见），仅兼容存量数据。

GET /api/guard/bwlist/summary — 账号级名单组计数

用途：判定链路节点/类型段控的计数。与列表分开：这组数不随搜索关键词变化，前端只在进页面时取一次。

鉴权：guard.bwlist.list。输出：{black, white, cdn_white, total}。

路径不挂在 /sets 下（/sets/summary 会与 /sets/{id} 的路由参数冲突）。

GET /api/guard/bwlist/sets — 名单集合列表

鉴权：guard.bwlist.list

输入参数：page / size / keyword / ip_set_type（1=黑名单 2=白名单）/ policy_id / include_grey（默认 false，只返回黑/白名单）。

输出字段（data.list[] = IPSetVO）：

可视化建议：

• 推荐图表：表格（主图）+ KPI 卡（黑名单总数 / 白名单总数 / 启用率）
• 派生指标：饼图（ip_set_type 1/2 占比）

搜索：keyword 一框多用 —— 组名 LIKE ∪ 描述 LIKE ∪ 组内 IP 文本 LIKE ∪ 组内网段包含该 IP（搜 1.2.3.4 可命中装着 1.2.3.0/24 的组，对齐 zmod FindIPInIPSet）。网段包含仅在 keyword 是合法 IP 时触发。

GET /api/guard/bwlist/sets/{id} — 查询单个名单集合

鉴权：guard.bwlist.list（与列表同权限）

输入参数：path id。

输出字段：单个 IPSetVO（字段同上表，含 scope_type / domain_ids / domain_names）。

供控制台名单详情页深链/刷新时按 ID 加载。业务级用户只能读取归属自己的集合，读取他人集合返回 404——不区分「不存在」与「无权」，避免用 ID 探测他人数据；平台级用户不受此限。

POST /api/guard/bwlist/sets — 创建名单集合

鉴权：guard.bwlist.create

输入参数（BWListSetCreateReq）：

输出字段：返回新建 IPSetVO。

指定 scope_type 时，后端把集合写入范围内每个域名的黑白名单配置（域名侧开关自动打开）并触发下发；scope_type=all 的集合对后续新增域名也自动生效。scope_type 与 policy_id 同时传返回 400。

PUT /api/guard/bwlist/sets/{id} — 更新名单集合

鉴权：guard.bwlist.edit

输入参数（BWListSetUpdateReq）：name / status / describe / scope_type / domain_ids（全部可选）。

输出字段：返回更新后的 IPSetVO。

修改 status 会同步域名配置并触发下发：启用集合进入黑/白名单，禁用集合进入禁用列表（dis_list）。传 scope_type 会重算生效范围：缩小范围时自动从移出的域名撤下配置；对存量策略绑定集合传 scope_type 会解绑 policy_id 并迁移到新范围模型。

status 不建议使用：集合级启停是本平台的扩展，旧平台没有这个概念（其名单组界面只有 名单信息/描述/IP/创建时间/操作），实际数据里也从未被使用。控制台与 zcloud CLI 均不提供该能力 —— 集合被禁用后控制台不会显示原因、也没有恢复入口。启停请用 IP 级的 PUT /api/guard/bwlist/ips/{id}/status。
本接口仍接受 status 只为不破坏既有对接方；不传 = 不改动库中原值，故从旧平台导入的 status 会原样保留并按其语义下发。

DELETE /api/guard/bwlist/sets/{id} — 删除名单集合

鉴权：guard.bwlist.delete

输入参数：path id。

输出字段：data 为 null。会级联删除集合内所有 IP 条目。

删除集合会同时从所有生效域名（及存量策略）的黑白名单配置中解绑，并触发相关域名重新下发。

GET /api/guard/bwlist/sets/{id}/ips — 集合内 IP 列表

鉴权：guard.bwlist.ip_list

输入参数：path id = 集合 ID；query page / size / keyword（按 IP/CIDR 模糊搜索）。

输出字段（data.list[] = IPVO）：

不存在有效期字段。名单条目没有到期概念（与 zmod 的 IPV2 模型一致）：expired_at / expire_at / left_time / timeout / ttl 一律不接受也不返回，传了会被忽略。临时封禁请自行删除条目。

可视化建议：表格。

POST /api/guard/bwlist/sets/{id}/ips — 单条添加 IP

鉴权：guard.bwlist.ip_add

输入参数（BWListIPAddReq）：

输出字段：返回新建 IPVO。

POST /api/guard/bwlist/sets/{id}/ips/batch — 批量添加 IP

用途：一次导入数百条 IP（如威胁情报源），减少多次往返开销。重复 IP 自动跳过（幂等）。

鉴权：guard.bwlist.ip_add

输入参数（BWListIPBatchAddReq）：

输出字段：data 为 null 或返回新增 ID 列表（按实现）。

POST /api/guard/bwlist/sets/{id}/ips/batch/delete — 批量删除 IP

用途：一次删除集合下多条 IP（如清理过期封禁），一个事务原子完成，避免逐条删除的部分失败与审计刷屏。

鉴权：guard.bwlist.ip_delete

输入参数（BWListIPBatchDeleteReq）：

输出字段：data.deleted 为实际删除条数。集合内无任一匹配返回 404。

PUT /api/guard/bwlist/ips/{id}/status — 启停单条 IP

鉴权：guard.bwlist.ip_add（复用写权限）

输入参数：path id = IP 条目 ID；body（BWListIPStatusReq）：

输出字段：返回更新后的 IPVO。

DELETE /api/guard/bwlist/ips/{id} — 删除单条 IP

重要：删除路径是顶级路径 DELETE /api/guard/bwlist/ips/{id}，不是嵌套在 sets 下的 DELETE /sets/{sid}/ips/{id}。

鉴权：guard.bwlist.ip_delete

输入参数：path id = IP 条目 ID。

输出字段：data 为 null。

5.7 IP 转发 /api/guard/forwards

这是 TCP/UDP 端口转发（4 层），不是路径转发 / 反向代理（7 层）。

GET /api/guard/forwards — IP 转发列表

鉴权：guard.forward.list

输入参数：

输出字段（data.list[] = ForwardVO）：

可视化建议：

• 推荐图表：表格 + status / schema 双 chip
• 派生指标：饼图（TCP/UDP 占比）

POST /api/guard/forwards — 创建 IP 转发

鉴权：guard.forward.create

输入参数（ForwardCreateReq）：

不存在 source_path / target 字段。

输出字段：返回新建 ForwardVO。

GET /api/guard/forwards/{id} — IP 转发详情

鉴权：guard.forward.view

输入参数：path id。

输出字段：ForwardVO。

PUT /api/guard/forwards/{id} — 更新 IP 转发

鉴权：guard.forward.edit

输入参数：path id，body 同 Create（字段全部可选）。

输出字段：返回更新后的 ForwardVO。

PUT /api/guard/forwards/{id}/status — 启停 IP 转发

鉴权：guard.forward.status

输入参数：path id，body 只有一个字段。

与 PUT /api/guard/forwards/{id} 的区别：本接口只改状态一列，跳过节点归属与源站的全量校验。
防护节点被回收、下线或从未迁入 cloud 节点库的历史规则（zmod 导入数据常见），走全量更新会被
「选择了未分配或不可用的防护节点」拒绝，导致规则连停都停不掉——而停用恰是此时最需要的操作。
老平台 zmod 的对应接口（PATCH /api/guard/forward/ipfromward/ipfromwards/{id}/status）同样不做这层校验。

仍然保留：租户隔离、域名绑定的历史规则不可在此单独启停（需先转为独立转发）、启用时检查同节点同协议端口占用。
状态实际发生变化时触发配置下发；状态未变则幂等返回、不下发。

输出字段：更新后的 ForwardVO（含 apply_triggered / apply_message）。

DELETE /api/guard/forwards/{id} — 删除 IP 转发

鉴权：guard.forward.delete

输入参数：path id。

输出字段：data 为 null。

源站转发 UX 改造 · 后端补充盘点（2026-06-30）

前端正在重设计源站转发页(对标友商「非网站 / 端口转发」:阿里云 DDoS 高防端口接入、腾讯云 BGP 高防非网站防护)。友商一条 L4 转发规则可配:转发协议(TCP/UDP)、转发端口、源站端口(与转发端口分离)、源站 IP/域名(阿里 ≤20 个逗号分隔自动负载均衡、腾讯 ≤20 个/规则)、权重 + 负载均衡算法、会话保持(开关 + 超时)、健康检查(TCP/UDP 探测:间隔 / 响应超时 / 健康 + 不健康阈值 / 端口,自动剔除异常源站)、新建连接 + 读写超时、连接 / 新建速率限速;列表展示每源站健康态 + 实时连接数 / 带宽。盘点我们现状如下:

结论:① ② 前端自查即可修(后端已支持);③ 是关键阻塞 —— 后端给出 raw JSON schema 前,「高级配置」(源站端口 / 会话保持 / 健康检查 / 权重)无法做成结构化表单,前端先做 协议 + 转发端口 + 源站 IP + 描述 + 启用 的核心闭环,高级项待后端 schema。④ ⑤ 是展示增强,可选。

5.8 调度管理 /api/guard/schedules

本模块只做 DNS 解析调度（域名解析模式切换 / 批量启停记录）。 旧版 cron 定时任务接口已下架。

⚠️ 异步生效约定：本组接口先落库兼容表 guard_db.dns_records + guard_db.dns_affairs，随后由 cloud DNS worker 调用 DNS provider API 异步生效。前端 / 调用方必须轮询 affairs 接口获取最终状态（初始 AffairsStatus_Start → AffairsStatus_Succeed / AffairsStatus_Faild）。

⚠️ 数据真值源：dns_records.group_type 是模式真相源，guard_configs.parsing_state 异步同步，均来自老平台 guard_db；存在最长 30s 不一致窗口。VO 同时返回两者，前端在不一致时显示"同步中" badge。

5.8.1 域名调度

GET /api/guard/schedules/domains — 域名列表

鉴权：guard.schedule.list

输入参数：

输出字段（data = ScheduleDomainListResp）：

POST /api/guard/schedules/domains/{id}/switch-mode — 切换源站/节点

鉴权：guard.schedule.switch

输入参数：

实现要点：guard_db 单库事务内 SELECT FOR UPDATE 锁住该域名全部 dns_records → 更新 group_type 与 switch_state=2（切换中）→ INSERT dns_affairs（status=AffairsStatus_Start）→ 提交后 NSQ Cmd=0 通知。

输出字段：返回新建 ScheduleAffairVO，前端应将 affairs_id 写入轮询轮换。

POST /api/guard/schedules/domains/switch-mode — 批量切换源站/节点

鉴权：guard.schedule.switch（与单域名切换同一权限，不新增 perm key）

输入参数：

实现要点：与老平台 PATCH /api/guard/schedule/domain/dns/switch 的 id_list 语义对齐 ——
整批一个事务，任一域名校验失败则全部回滚（老平台原话「放弃执行」），不做部分成功。
事务内逐个域名执行与单切完全相同的校验（FOR UPDATE 锁记录、无进行中事务、目标模式有可生效记录、
无已启用的锁定记录），随后只 INSERT 一条 dns_affairs，其 content 为逗号分隔的 domain_id 列表
（老平台同款格式，cloud 的 LatestByDomainIDs 本就按逗号切分读取，两平台可互读）。
提交后 cloud DNS worker 逐个更新 guard_configs.parsing_state 并调用 DNS provider。

输出字段：返回新建 ScheduleAffairVO（一条，对应整批）。

POST /api/guard/schedules/domains/{id}/init — 初始化解析

鉴权：guard.schedule.init

输入参数：path id（domain_id）；body 可选 comment。

实现要点：读取 guard_domain_settings 的源站/调度配置与 domain_node_ships 节点绑定，锁住该域名旧 dns_records 后删除并重建源站/节点记录；随后 INSERT dns_affairs，以 NSQ Cmd=0 通知 zdns 同步一次。

输出字段：返回新建 ScheduleAffairVO。

POST /api/guard/schedules/domains/{id}/reset — 重置解析

鉴权：guard.schedule.reset

输入参数：path id（domain_id）；body 可选 comment。

实现要点：所有 dns_records.switch_state 归位为 1，status 回滚到 last_status；落事务后 NSQ Cmd=0 通知。

输出字段：返回新建 ScheduleAffairVO。

GET /api/guard/schedules/domains/{id}/records — 域名解析记录

鉴权：guard.schedule.records

输入参数：

输出字段（data = ScheduleRecordsResp）：

直查 zdns_db.dns_records，只读，不落事务。

5.8.2 解析调度

POST /api/guard/schedules/domains/{id}/records — 新建解析记录

鉴权：guard.schedule.batch

输入参数（ScheduleRecordCreateReq）：

语义要点：目标分组与当前解析模式一致时记录立即启用，否则建为禁用态；相同分组+类型+线路+值查重；默认线路守卫——分组内存在启用 A 记录时必须保留至少一条默认线路（Line 1），否则未匹配任何运营商线路的访客将解析落空（对齐 zmod NoIPv4DefaultLine）。

输出字段：data 为调度事务 ScheduleAffairVO。

PUT /api/guard/schedules/records/{id} — 编辑解析记录

鉴权：guard.schedule.batch

输入参数（ScheduleRecordUpdateReq，三字段均必填）：

语义要点：类型与分组不可改（改型走删除重建）；锁定记录（mark=2）拒绝编辑；改动后过默认线路守卫。

输出字段：data 为调度事务 ScheduleAffairVO。

DELETE /api/guard/schedules/records/{id} — 删除解析记录

鉴权：guard.schedule.batch

语义要点：锁定记录、当前模式最后一条生效记录、以及删除后打破默认线路守卫的操作均被拒绝。

输出字段：data 为调度事务 ScheduleAffairVO。

POST /api/guard/schedules/records/batch-status — 批量启停记录

鉴权：guard.schedule.batch

输入参数（ScheduleBatchStatusReq）：

实现要点：UPDATE dns_records SET last_status=status, status=? WHERE record_id IN (?)；落事务后 NSQ Cmd=0 通知。

输出字段：返回新建 ScheduleAffairVO。

5.8.3 事务记录

GET /api/guard/schedules/affairs — 事务列表

鉴权：guard.schedule.affairs

输入参数：

输出字段（data = ScheduleAffairListResp）：见下方 ScheduleAffairVO。

GET /api/guard/schedules/affairs/{id} — 事务详情

鉴权：guard.schedule.affairs

输入参数：path id（affairs_id）。

输出字段（data = ScheduleAffairVO）：

轮询建议：前端发起写操作后，每 2~5s 轮询一次本接口，直到 status 切换为 Succeed 或 Faild；若长时间停在 Start，说明 cloud DNS worker 仍在执行或重试，可在 UI 显示"同步中"。

解析调度 UX 改造 · 后端补充盘点（2026-07-01）

前端将重设计解析调度页。对标友商：阿里云云解析「智能解析 / GTM 全局流量管理」、腾讯 DNSPod、Cloudflare Load Balancing，以及各家 WAF 的 CNAME 接入 + 灾备切换。我们的模型 = 按域名在 源站(SRC=1) ↔ 防护节点(NODE=2) 间切换 DNS 解析（cloud 写兼容表并由 cloud DNS worker 调用 DNS provider API，每次写产生一条 affair 事务并由 worker 回写终态）。友商比我们多的能力：健康检查 + 自动 failover（节点挂→自动切源站）、权重负载均衡、智能线路（电信/联通/移动/geo）、单条记录 CRUD、TTL 编辑。据此盘点后端补充：

前端自查项（非后端）：DnsRecordVO.mark / .protect_status 前端类型声明了但后端 DTO 不返回 → 前端清掉；parsing_state 不在域名 Detail（专走 /schedules/domains）是有意拆分，不改。

结论：① ② 是重设计前应先定的（同步状态字段 + 孤儿接口去留），成本小。③④⑤⑥ 属于"要不要把解析调度从『手动源站/节点切换』升级成『带健康/权重/线路/CRUD 的智能解析』"的产品决策，依赖最终 mock 定的范围，先请后端评估 zdns_db + NSQ 侧可行性。核心闭环（手动 SRC/NODE 切换 + 记录批量启停 + init/reset + affair 轮询）后端已完整支持，重设计可先做纯 UX（域名中心化流程 + 更清晰的当前模式/同步状态 + 事务切换历史）。

5.8bis 运维：配置快照 + 源站级状态位 · 后端补充盘点（2026-07-01）

来源：域名中心化整体联动 review + 用户两个运维场景（几十个域名各关一个特定源站 / 操作前存快照、事后一键恢复）。前端已先行落地「配置快照 UI」（源站转发页，localStorage 暂存 + 用现有 PUT /forwards/:id 逐条回放），待以下接口就绪后切换为服务端实现。

优先级建议：② 源站软关闭是地基，成本相对小、直接解掉「关了怎么恢复」；① 服务端快照其次；③ 看产品。②③ 依赖是否把 L4 转发从「整规则开关」升级为「源站粒度」，属产品决策，先请后端评估可行性。

④ 接入闭环 · 验证接入（对标大厂）：接入向导完成页已加「验证接入」按钮，前端 interim 用 GET /guard/domains/:id 的 proxy_switch && !stoping 判是否生效（被动、依赖后端异步检测）。建议后端加主动探测 POST /guard/domains/:id/verify-access：实时查 ① DNS 是否已 CNAME 指向我方 ② 回源是否可达，返回 { dns_ok, origin_ok, resolved_cname, message }，让「验证接入」即点即得（对标阿里/腾讯/华为的接入检测）。

5.8ter 配置下发记录（Apply）· 后端补充盘点（2026-07-02）

前端把「配置下发记录」重设计成下发任务监控看板（列表进度条 + 详情节点按集群折叠 + 失败聚类 + 重试/取消 + 下发中实时轮询）。现有模型（ApplyVO 状态/成功失败数、ApplyNodeStat 按 node_group_name 分集群、ApplyDetailItemVO.apply_err 每节点错误、retryApplyApi(node_ids)/quitApplyApi）已足够支撑核心。以下是加固项（架构评审提出的边界）：

⚠️ 架构现实（核对后端代码后必读，决定各项落点）：cloud 是薄前台——apply + apply_detail 单库 ACID 写入 cloud_guard，经 outbox → zRPC cmd=550 → gen-service（老配置生成平台）；真正下发到节点、并回写 apply_status（PENDING1→RUNNING4→SUCCESS2/FAILED3）/effect_status/apply_err 的是 gen-service（cloud 不主动写这些）；outbox 已有 30s 未回写就重投。因此下面各项落点不同：②severity 是 cloud 侧就能做（触发时 cloud 知道改的是啥，打标即可，最低成本、优先）；①generation/回滚、③规范化错误码、④生效语义 多在 gen-service 侧（要老平台配合，非 cloud Go 改改）；⑤超时/重投 cloud outbox 已部分覆盖（节点级最终一致仍在 gen-service）；⑥ affair 走 zdns/NSQ、apply 走 gen-service/outbox，是两套后端，合并成本高。

优先级：①（版本+回滚，防乱序 + 与快照一条线）和 ②（安全等级告警）最高；③④⑤ 是健壮性；⑥ 是长期架构。

5.8quater 防护节点与回源（租户视角）· 待后端接口（2026-07-02）

背景：cloud 定位为租户产品（用户从上层控制台跳转进入），「集群节点」管理（平台运维/节点列表/分组/ACL/分配/部署升级）已从 cloud 前端整体移除（归上层控制台）；后端 /api/node 全部保留（agent 自注册、domain_node_ships 是调度/下发地基，上层平台直接调用）。租户侧需 2 个租户视角新接口（对标阿里/腾讯 WAF 的回源 IP 段公示 + 高防 IP 线路视图；前端已按此契约实现，接口未就绪时显示提示、不显示假数据）。
前端消费位置（2026-07-02 验收后调整,不做独立页）：origin-ip-ranges → 接入向导完成步「源站放行回源 IP 段」块 + 域名工作台接入区「回源放行清单」弹窗（共享组件 OriginIpRanges.vue）；my-nodes → 解析调度详情流量走向图「防护节点」上的健康徽标 + 线路名。

要点：① 权限挂租户已有的 guard.domain.list 即可（只读观测）；② status 的健康判定是解析调度页「节点健康」占位的正式数据源（自动 failover 前置）；③ 回源出口 IP 若与节点管理 IP 不同（NAT/独立出口），以实际回源出口为准，别把管理 IP 泄给租户。

5.9 WAF 规则 /api/guard/waf/rules

WAF 规则组挂在策略（policy_id）下，一个规则组含若干子规则（rules[]），由网关侧匹配 zone / pattern 决定命中后 action（拦截 / 记录 / 验证码）。

⚠️ 状态约定：本组接口的 status 字段统一约定 1=禁用 2=启用（S-6 修复后已与 forwards / bwlist / schedules 对齐）。POST /status 接口的 oneof 校验也是 1|2。

⚠️ 路径 ID 取 tag：PUT/DELETE /api/guard/waf/rules/{id} 中 {id} 是规则组的 tag（uint64 主键），不是 rule_id（业务编号）。前端从列表的 tag 字段取值。

GET /api/guard/waf/rules — WAF 规则组列表

鉴权：guard.waf.list

输入参数：

输出字段（data.list[] = WafGroupVO）：

WafRuleVO（子规则）字段：

可视化建议：

• 推荐图表：表格 + action / status 双 chip + rules.length 数字徽章
• 派生指标：按 action 聚合的饼图（block / log / captcha 占比）

POST /api/guard/waf/rules — 创建 WAF 规则组

鉴权：guard.waf.create

输入参数（WafGroupCreateReq）：

WafRuleReq（子规则请求体）：

示例：

curl -X POST https://waf.example.com/api/guard/waf/rules \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SQL 注入防护",
    "policy_id": "1",
    "describe": "OWASP Top 10 SQLi 黑名单",
    "action": 1,
    "status": 2,
    "rules": [
      { "zone": "ARGS", "pattern_type": 2, "pattern": "union\\s+select", "describe": "SQLi: union select" }
    ]
  }'

输出字段：返回新建 WafGroupVO（含 tag、rules[] 已落库的子规则）。

不存在字段：enabled 布尔（用 status 整数）/ description（用 describe）/ domains[]（作用域用 scope 字符串）。

PUT /api/guard/waf/rules/{id} — 更新 WAF 规则组

鉴权：guard.waf.edit

输入参数（path id = 规则组 tag；body WafGroupUpdateReq，字段全部可选，按 flag 增量更新；rules[] 全量替换）：

本接口不更新 status——启停切换走独立的 PUT /api/guard/waf/rules/{id}/status。

输出字段：返回更新后的 WafGroupVO。

DELETE /api/guard/waf/rules/{id} — 删除 WAF 规则组

鉴权：guard.waf.delete

输入参数：path id（规则组 tag）。

实现要点：级联删除子规则（waf_rules.group_id = tag）。

输出字段：data 为 null。

PUT /api/guard/waf/rules/{id}/status — 切换 WAF 规则组启停

鉴权：guard.waf.status

输入参数（path id = 规则组 tag；body WafStatusReq）：

示例：

curl -X PUT https://waf.example.com/api/guard/waf/rules/42/status \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": 1 }'

输出字段：data 为 null。

GET /api/guard/waf/rules/export — 导出精准防护规则为 JSON 文件

鉴权：guard.waf.export

输入参数（query）：

输出：直接返回 JSON 文件流（Content-Disposition: attachment; filename="waf-precision-rules.json"，非 {code,data} 信封）。文件结构：

{
  "version": 1,
  "kind": "waf-precision-rules",
  "rules": [
    {
      "name": "拦截可疑注入", "describe": "", "waf_type": 8, "sub_rule_condition": 1,
      "scope": "/api/", "action": 1, "status": 2,
      "rules": [ { "zone": "URL", "sub_field": "", "pattern_type": 1, "pattern": "select", "describe": "", "is_not": false } ]
    }
  ]
}

rules[] 中每组不含 id/tag/policy_id/时间戳，便于跨策略导入。

POST /api/guard/waf/rules/import — 从 JSON 批量导入精准防护规则

鉴权：guard.waf.import

输入参数（body WafRuleImportReq）：

行为：各组独立校验/创建（追加，单组失败不阻断其余），成功后即时下发一次。

示例：

curl -X POST https://waf.example.com/api/guard/waf/rules/import \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "policy_id": "P123", "rules": [ { "name": "block-x", "waf_type": 8, "action": 1, "sub_rule_condition": 1, "rules": [ { "zone": "URL", "pattern_type": 1, "pattern": "select" } ] } ] }'

输出字段：data = { imported, failed, errors[] }（成功数 / 失败数 / 每条失败原因）。

5.9 WEB 基础防护 /api/guard/policies/{id}/waf/*

从 zmod 移植的 WEB 基础防护，四块配置：基础防护（自定义拦截页/引擎/XML/Body 大小/内置策略）、高频攻击惩罚、精准白名单、BODY 检测白名单。精准防护规则本体仍走 §5.x 的 /api/guard/waf/rules。除高频惩罚存独立列 guard_policies.waf_rate_limit 外，其余内联 guard_policies.waf_config JSON。所有写接口即时下发（ApplyTagWaf）到策略关联域名。枚举字段用 zmod pb 枚举名字符串（如 WAFPageType_1_DEFAULT），前端只透传。权限：读 guard.waf.view/guard.waf.list，写 guard.waf.create/edit/delete。

精准白名单条目：{ id, name, describe, rule_id(逗号串), rule_name, op(str/regex), url, status(CFGOPTION_2_ENABLE/..), zones[{zone,sub_field}] }。「跳过哪些检测」由 rule_id（逗号分隔的过白内置规则编号）表达，白名单无 action/waf_type。

BODY 白名单条目：{ rule_id, op(prefix/suffix/regex/equal), data(匹配路径), describe, status(bool) }。注意 status 是 bool（与白名单的 CFGOPTION 串不同）。

基础防护体：{ waf_policy{name,policy_id,default_main_rule_version}, waf_custom_err_code{page_type,code,content,redirect_addr}, waf_xml{status,max_depth,...}, req_body_size, engine{version} }。

⚠️ 精准防护规则（/api/guard/waf/rules）的子规则 pattern/describe 在 user_rule_v3 以 base64 存储（与 zmod/gen-server 一致），本次移植已补齐编解码并兼容存量明文。

§6 Analytics 统计分析

📊 Analytics 统计分析 · 18 paths（含 80+ chart-key 单图接口）· 用于构建 WAF 监控大屏、运营报表、处置闭环
所有 /api/analytics/* 路径已对外，只能增加字段或新增接口，不能修改或删除已发布路径。
完整 chart-key → 数据形态映射见各小节"chart-key 索引表"，每行都明确推荐图表。

6.0 本章统一调用约定

Analytics 接口数量多但大多是同构的图表查询。本章用"统一约定 + 索引表 + 特殊接口展开"组织。

鉴权与权限

Header：Authorization: Bearer <token> 或 Authorization: ApiKey zck_...，可附加 Accept-Language: zh-CN / en-US。

权限分三类：

使用 API Key 时，Key 的 scopes 必须覆盖接口所需权限。例如调用 GET /api/analytics/access/status，Key 至少包含 analytics.access.view。

单图 GET 调用模板

curl -sS 'https://waf.example.com/api/analytics/access/status?window=last_24h&site_id=site-001' \
  -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  -H 'Accept-Language: zh-CN'

返回统一 JSON 信封，图表 data 固定使用 Chart 统一契约（docs/specs/chart-contract.md）。这是新系统对外唯一契约；老数据库表、聚合表和 ES 索引只作为内部数据源，不影响调用方入参或响应结构。

图表 data 固定 5 字段，禁止 series / totals / kpis / points / list 作为对外顶层字段：

window.granularity 不是入参：客户传 window=last_24h，后端按时间窗大小自动选择 5m/1h/1d 聚合表，并在响应里回填实际命中的 granularity。

Batch 调用模板

适用于 POST /api/analytics/batch 与 POST /api/analytics/<page>/batch。

curl -sS -X POST https://waf.example.com/api/analytics/overview/batch \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
        "time_window": "last_24h",
        "site_id": "",
        "domain_id": "",
        "compare": false,
        "charts": [
          { "key": "kpi" },
          { "key": "bandwidth" }
        ]
      }'

Batch 响应的 data.data 以 chart-key 为键；data.meta 给出整体耗时、缓存命中率、失败图表数和实际时间窗。单个 chart 失败时优先查看该 chart 节点里的 partial / error 字段。

6.1 术语表

GET /api/analytics/glossary — 统计术语表

用途：返回统计分析术语表，前端 tooltip 用此渲染"什么是 QPS / 拦截率"等说明。

鉴权：登录态

输入参数：无。

输出字段：

可视化建议：

• 推荐图表：不直接做图；前端图表组件挂上 tooltip 时按 chart-key 在 terms map 里查询解释

示例响应：

{
  "code": 0,
  "data": {
    "terms": {
      "qps": "每秒请求数",
      "block_rate": "拦截率"
    }
  }
}

6.2 跨页 Batch

POST /api/analytics/batch — 跨页通用批量查询

用途：在前端大屏页面初始化时一次性请求多个 chart-key，省去 N 次单图 GET 往返。后端并行执行各子查询并合并响应。

鉴权：按 page 字段映射到对应 analytics.<page>.view

输入参数（请求体）：

logs（Phase 1 访问日志）和 reports（Phase 4 报表中心）是独立 group，不走 batch 模式。

输出字段：

可视化建议：

• 推荐图表：本接口本身不直接做图，是数据装载层；前端拿到响应后按 chart-key 分发到各图表组件
• 派生指标：data.meta.cache_hit_ratio 可在 dev 环境做 KPI 数字卡监控大屏的缓存效率

示例请求/响应：

// 请求
{
  "page": "overview",
  "time_window": "last_24h",
  "compare": false,
  "charts": [
    { "key": "kpi" },
    { "key": "bandwidth" }
  ]
}

// 响应
{
  "code": 0,
  "data": {
    "data": {
      "kpi": {
        "chart_key": "overview/kpi",
        "render_hint": "kpi",
        "schema": {
          "dimensions": [],
          "measures": [
            { "name": "domain_count", "type": "integer", "unit": "" },
            { "name": "requests",     "type": "integer", "unit": "requests" },
            { "name": "blocked",      "type": "integer", "unit": "events" },
            { "name": "block_rate",   "type": "percent", "unit": "%" },
            { "name": "qps",          "type": "float",   "unit": "qps" },
            { "name": "ai_detect",    "type": "integer", "unit": "events" }
          ]
        },
        "rows": [
          { "domain_count": 8, "requests": 12345, "blocked": 678, "block_rate": 5.49, "qps": 0.143, "ai_detect": 0 }
        ],
        "meta": { "source": "postgres", "cache": "miss", "latency_ms": 10 }
      },
      "event-type": {
        "chart_key": "overview/event-type",
        "render_hint": "categorical_distribution",
        "schema": {
          "dimensions": [{ "name": "event_type", "type": "string" }],
          "measures": [{ "name": "count", "type": "integer", "unit": "events" }]
        },
        "rows": [
          { "event_type": "sql_injection", "count": 1234 },
          { "event_type": "xss", "count": 567 }
        ],
        "meta": { "source": "elasticsearch", "cache": "miss", "latency_ms": 15, "partial": false }
      }
    },
    "meta": {
      "elapsed_ms": 22,
      "cache_hit_ratio": 0,
      "total_charts": 2,
      "failed_charts": 0,
      "window": { "stime": 1746662400000, "etime": 1746748800000, "granularity": "1h" }
    }
  }
}

注意：上例中 kpi 的 measure 名 requests / blocked 是对外契约真值名（与 pkg/chart/contract 真值结构体对齐）。底层数据库字段名不对外暴露，前端严格按 schema.measures[].name 取值。

POST /api/analytics/{page}/batch — 页面级 Batch

用途：与 POST /api/analytics/batch 等价，但 page 由 URL 决定（前端固定页面调用更直观）。

鉴权：根据 {page} 映射到对应 analytics.<page>.view。

支持的 page 值：