本文档属于 Cloud WAF — 企业 Web 防护管理平台
CLI 工具：zcloud· 5 大模块：guard / sys / analytics / cli_release / auth
完整 API 索引：/api/openapi.json · 文档地图：/sitemap.xml · AI 速读：/llms.txt
权限矩阵
RBAC 模型
Cloud WAF 采用经典 Resource × Action × Role 三元 RBAC 模型：
- Resource（资源）：业务实体的逻辑分组，如
guard.domain（域名管理）、sys.user（用户管理），用Prefix唯一标识 - Action（动作）：在该资源上的操作，如
list（列表）、create（新建）、delete（删除）等 - 完整权限 Key：
<resource_prefix>.<action_key>，例如guard.domain.list，是给角色授权的最小单位 - Role（角色）：权限 key 的集合；用户绑定角色后获得对应权限
权限矩阵由服务端权限注册表统一维护，并通过 GET /api/sys/permissions/tree 对外提供带 i18n 名称的完整权限树。
完整资源 / 动作清单
下表按模块汇总所有可授权的 Resource × Action 组合，可直接用作 PUT /api/sys/roles/{id}/permissions 的 keys 参数（逗号分隔）。
sys 模块（系统管理）
| 模块 | 资源 (Resource Prefix) | 动作 (Action Key) | 完整权限 Key |
|---|---|---|---|
| sys | sys.user | list | sys.user.list |
| sys | sys.user | view | sys.user.view |
| sys | sys.user | create | sys.user.create |
| sys | sys.user | edit | sys.user.edit |
| sys | sys.user | delete | sys.user.delete |
| sys | sys.user | resetpwd | sys.user.resetpwd |
| sys | sys.user | lock | sys.user.lock |
| sys | sys.user | assign | sys.user.assign |
| sys | sys.role | list | sys.role.list |
| sys | sys.role | view | sys.role.view |
| sys | sys.role | create | sys.role.create |
| sys | sys.role | edit | sys.role.edit |
| sys | sys.role | delete | sys.role.delete |
| sys | sys.role | perm | sys.role.perm |
| sys | sys.oem | view | sys.oem.view |
| sys | sys.oem | create | sys.oem.create |
| sys | sys.oem | edit | sys.oem.edit |
| sys | sys.oem | delete | sys.oem.delete |
| sys | sys.security | view | sys.security.view |
| sys | sys.security | edit | sys.security.edit |
| sys | sys.session | view | sys.session.view |
| sys | sys.session | kick | sys.session.kick |
| sys | sys.audit | view | sys.audit.view |
guard 模块（Web 防护）
| 模块 | 资源 (Resource Prefix) | 动作 (Action Key) | 完整权限 Key |
|---|---|---|---|
| guard | guard.domain | list | guard.domain.list |
| guard | guard.domain | view | guard.domain.view |
| guard | guard.domain | create | guard.domain.create |
| guard | guard.domain | edit | guard.domain.edit |
| guard | guard.domain | delete | guard.domain.delete |
| guard | guard.domain | settings | guard.domain.settings |
| guard | guard.cert | list | guard.cert.list |
| guard | guard.cert | view | guard.cert.view |
| guard | guard.cert | upload | guard.cert.upload |
| guard | guard.cert | edit | guard.cert.edit |
| guard | guard.cert | delete | guard.cert.delete |
| guard | guard.cert | bind | guard.cert.bind |
| guard | guard.policy | list | guard.policy.list |
| guard | guard.policy | view | guard.policy.view |
| guard | guard.policy | create | guard.policy.create |
| guard | guard.policy | edit | guard.policy.edit |
| guard | guard.policy | delete | guard.policy.delete |
| guard | guard.bwlist | list | guard.bwlist.list |
| guard | guard.bwlist | create | guard.bwlist.create |
| guard | guard.bwlist | edit | guard.bwlist.edit |
| guard | guard.bwlist | delete | guard.bwlist.delete |
| guard | guard.bwlist | ip_list | guard.bwlist.ip_list |
| guard | guard.bwlist | ip_add | guard.bwlist.ip_add |
| guard | guard.bwlist | ip_delete | guard.bwlist.ip_delete |
| guard | guard.waf | list | guard.waf.list |
| guard | guard.waf | create | guard.waf.create |
| guard | guard.waf | edit | guard.waf.edit |
| guard | guard.waf | delete | guard.waf.delete |
| guard | guard.waf | status | guard.waf.status |
| guard | guard.cc | list | guard.cc.list |
| guard | guard.cc | create | guard.cc.create |
| guard | guard.cc | edit | guard.cc.edit |
| guard | guard.cc | delete | guard.cc.delete |
| guard | guard.cc | status | guard.cc.status |
| guard | guard.acl | list | guard.acl.list |
| guard | guard.acl | create | guard.acl.create |
| guard | guard.acl | edit | guard.acl.edit |
| guard | guard.acl | delete | guard.acl.delete |
| guard | guard.acl | status | guard.acl.status |
| guard | guard.forward | list | guard.forward.list |
| guard | guard.forward | create | guard.forward.create |
| guard | guard.forward | edit | guard.forward.edit |
| guard | guard.forward | delete | guard.forward.delete |
| guard | guard.schedule | list | guard.schedule.list |
| guard | guard.schedule | view | guard.schedule.view |
| guard | guard.schedule | switch | guard.schedule.switch |
| guard | guard.schedule | init | guard.schedule.init |
| guard | guard.schedule | reset | guard.schedule.reset |
| guard | guard.schedule | records | guard.schedule.records |
| guard | guard.schedule | batch | guard.schedule.batch |
| guard | guard.schedule | affairs | guard.schedule.affairs |
| guard | guard.apply | list | guard.apply.list |
| guard | guard.apply | view | guard.apply.view |
| guard | guard.apply | create | guard.apply.create |
| guard | guard.apply | retry | guard.apply.retry |
| guard | guard.apply | quit | guard.apply.quit |
analytics 模块（统计大屏）
| 模块 | 资源 (Resource Prefix) | 动作 (Action Key) | 完整权限 Key |
|---|---|---|---|
| analytics | analytics.overview | view | analytics.overview.view |
| analytics | analytics.overview | export | analytics.overview.export |
| analytics | analytics.access | view | analytics.access.view |
| analytics | analytics.protect | view | analytics.protect.view |
| analytics | analytics.ai | view | analytics.ai.view |
| analytics | analytics.ai | logs | analytics.ai.logs |
| analytics | analytics.bot | view | analytics.bot.view |
| analytics | analytics.bot | session | analytics.bot.session |
| analytics | analytics.alert | view | analytics.alert.view |
| analytics | analytics.alert | ack | analytics.alert.ack |
动作语义约定
为保持跨模块一致，动作命名遵循以下约定：
| Action Key | 语义 | 典型 HTTP 方法 |
|---|---|---|
list |
列表查询（含分页） | GET (collection) |
view |
详情查询 | GET (one) |
create |
新建 | POST |
edit |
编辑（修改既有资源） | PUT / PATCH |
delete |
删除 | DELETE |
resetpwd |
重置密码（sys.user 专属） | PUT |
lock |
锁定/解锁（sys.user 专属） | PUT |
assign |
分配角色（sys.user 专属） | PUT |
perm |
角色权限读写（sys.role 专属） | GET / PUT |
settings |
详细配置读写（guard.domain 专属） | GET / PUT |
upload |
上传（证书等） | POST |
bind |
绑定/解绑关系（证书↔域名） | POST / DELETE |
ip_list / ip_add / ip_delete |
bwlist 下 IP 子资源 | GET / POST / DELETE |
status |
启停（waf/cc/acl 规则） | PUT |
retry / quit |
任务重试/取消（guard.apply） | POST / PATCH |
export |
报表导出（analytics.overview） | POST |
logs |
明细日志（analytics.ai） | GET |
session |
会话详情（analytics.bot） | GET |
ack |
告警确认（analytics.alert） | PATCH |
使用示例：给角色授权
通过 CLI 把若干权限 key 一次性绑定到角色：
# 给"运维员"角色授予域名 + 证书的所有读权限
# 注意：CLI flag 名为 --permissions（必填），不是 --keys
zcloud sys roles set-permissions 5 \
--permissions guard.domain.list,guard.domain.view,guard.cert.list,guard.cert.view
通过 API：
curl -sS -X PUT https://waf.example.com/api/sys/roles/5/permissions \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"keys": ["guard.domain.list", "guard.domain.view"]}'
拿到带 i18n 的完整权限树
前端权限页用此接口渲染（含中英文显示名）：
curl -sS https://waf.example.com/api/sys/permissions/tree \
-H "Authorization: Bearer $TOKEN" \
-H "Accept-Language: zh-CN" \
| jq
返回结构含 module / resources[] / actions[]，每条带 key 和 i18n name。
给 CI 账号最小权限的实践
例 1：CI 只需要发证 → 授予
guard.cert.list, guard.cert.view, guard.cert.upload, guard.cert.delete, guard.cert.bind
例 2：CI 只读统计大屏 → 授予
analytics.overview.view, analytics.access.view, analytics.protect.view
切忌给 CI 账号管理员级权限；最小权限是减小爆炸半径的第一道闸门。
相关文档
Cloud WAF · 权限矩阵由服务端权限注册表生成