> **本文档属于 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)

---

# 权限矩阵

## 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 一次性绑定到角色：

```bash
# 给"运维员"角色授予域名 + 证书的所有读权限
# 注意：CLI flag 名为 --permissions（必填），不是 --keys
zcloud sys roles set-permissions 5 \
  --permissions guard.domain.list,guard.domain.view,guard.cert.list,guard.cert.view
```

通过 API：

```bash
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 的完整权限树

前端权限页用此接口渲染（含中英文显示名）：

```bash
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 账号管理员级权限；最小权限是减小爆炸半径的第一道闸门。

## 相关文档

- [认证说明](/docs/auth) — 角色与会话的关系
- [API 文档](/docs/api) — 接口对应的权限 key
- [CLI 工具](/docs/cli) — 等价的命令行操作

---

*Cloud WAF · 权限矩阵由服务端权限注册表生成*