角色与权限

Clouisle 的授权由全局角色和团队门限两层叠加决定。前端按权限隐藏菜单与按钮，后端会重新校验——「看不到入口」不是安全边界，绕过界面直接请求同样会被拒绝。

权限目录与内置角色矩阵见权限与角色参考；本页讲怎么操作、谁有权限、失败时发生什么。

权限模型

两层授权

• 全局角色决定「能做什么」：能否进入管理台、能否创建 Agent、能否修改站点设置、能否导出审计日志。
• 团队门限决定「在哪个团队、以什么级别做」：团队角色只有所有者、管理员、成员、观察者四种，本身不授予任何权限。

两层是「与」的关系。例如，一个用户即使拥有创建 Agent 的全局权限，也必须先属于某个团队才能在该团队创建；团队所有者也不会因为角色自动获得管理台权限。

检查顺序

带团队的请求按以下顺序校验，任何一步失败都会拒绝：

1. 团队是否存在。
2. 是否超级管理员——是则直接放行，不查角色和团队成员关系。
3. 是否该团队成员。
4. 该动作是否属于团队管理动作——是则要求在该团队内是所有者或管理员。
5. 如果在该团队内是观察者，只允许只读和使用类动作。
6. 全局角色是否包含所需权限。

失败时页面提示无权限、需要团队管理员或不是团队成员，而不是返回空数据。

权限分类

管理台权限覆盖管理后台的各功能：用户、角色、权限、团队、模型、能力（工具与 Skill）、知识库、站点设置、集成、会话、记忆、通知与审计日志。要进入管理台，至少要拥有管理台访问权限；之后每个页面再按各自的查看或修改权限拦截。

资源权限覆盖团队内的 Agent、工作流、知识库、工具、Skill、会话与记忆。资源权限通过全局角色授予，再叠加团队门限；API Key 例外，它按个人归属。

内置角色

系统内置五个全局角色，不能改名、不能删除，权限集也不能修改。

Super Admin

持有全部权限。系统第一个注册用户会被自动提升为 Super Admin。超级管理员在团队接口中直接放行，但仍需要有团队成员记录才会出现在成员列表里。

Admin

可以管理全部团队与团队成员，但团队管理动作仍要求他在该团队内是所有者或管理员。Admin 是「日常运营」角色：能处理用户、团队、模型、能力、知识库、会话与审计，但不负责角色设计和站点级配置。

Team Admin

权限等于 Member 加上修改团队信息与成员管理。启动时系统会给所有团队内角色为所有者或管理员的用户补授该角色。因此把某人设为团队管理员前，他必须已经持有 Team Admin 角色，否则会因缺少团队管理权限被拒绝。

Member

在团队内创建、编辑和运行 Agent、工作流、知识库、工具与 Skill，可以管理自己的 API Key。注意：Member 即使拥有删除工具的权限项，实际删除仍要求团队管理员，操作会被拒绝。

Viewer

只读角色，也是新用户的默认全局角色。可以查看团队、与 Agent 对话、运行工作流、检索知识库、执行工具与 Skill，但不能创建或修改任何资源，也不能管理 API Key。

两个操作界面

团队与角色相关的界面有两个，要求不同：

普通成员与观察者看不到管理全部团队，他们的团队入口只有管理当前团队，且普通成员在该页只能查看。模型授权标签对团队管理员是只读的，文案明确「由系统管理员分配」。

集成与投递记录权限

集成相关界面按域授权，登录域与内置服务域互相独立：

• 全局 SSO 开关显示在安全页，但按登录域授权，不属于通用站点设置权限。
• 消息投递记录位于侧边栏 Monitoring 组，该组整体还要求管理台访问权限；只有投递记录查看权限而没有管理台权限的用户看不到入口，但直接访问页面地址仍会按该权限放行。
• 内置 Admin 角色能查看集成配置与投递记录，但不能修改——改配置需要 Super Admin 或带相应修改权限的自定义角色。

角色管理

管理台 Roles 页面列出全部角色。内置 Admin 角色只能查看角色，因此只有 Super Admin（或带角色管理权限的自定义角色）能创建、修改、删除自定义角色。

创建自定义角色

1. 以 Super Admin 登录，进入 Admin → Roles。
2. 点击 Create Role，填写名称（全局唯一）与描述。
3. 在权限列表中按分类勾选权限。
4. 保存。

自定义角色是全局角色，可以指派给任意用户，与团队归属无关。名称重复会提示角色已存在。

示例： 内容管理员——只需要团队查看、知识库管理与 Agent 对话权限，不进入管理台。

编辑角色

可以修改自定义角色的名称与描述，也可以整体替换权限集——保存时提交的是完整列表，不是增量。内置角色不允许改名、改描述或改权限。

删除角色

删除角色有两条硬性限制：

• 内置角色不能删除。
• 仍有用户持有该角色时不能删除，页面会提示还有多少用户在使用。

自定义权限

权限目录本身也可以在 Permissions 页面维护，需要权限查看权限；创建、修改、删除还分别需要对应权限。

系统内置权限不能修改或删除；自定义权限的标识重复时会提示已存在。

用户权限

查看用户权限

Admin → Users 打开用户列表。用户详情/编辑面板展示：

• 用户拥有的全局角色（多选）
• 团队归属与团队内角色（在团队页维护）
• 登录方式、账号状态与是否超级管理员

没有「有效权限聚合视图」：实际权限是全部全局角色的并集再叠加团队门限，需要人工对照权限与角色参考判断。

变更用户全局角色

1. Admin → Users，点击目标用户的 Edit。
2. 在 Role 区域勾选或取消角色（可多选）。
3. 保存。

保存时整体替换角色列表：未列出的角色会丢失；匹配不到的角色名被忽略。

角色变更立即对后续请求生效，已登录的会话不会被踢下线，但下一个受限操作就会被拒绝。

创建用户时不能指定角色：新用户没有任何全局角色，需要创建后单独指派。

团队权限

团队角色是门限，不是授权

团队角色只有四个固定值：所有者、管理员、成员、观察者。它不携带任何权限，只回答两个问题：这个人是不是这个团队的成员；他的级别够不够做管理动作。

团队管理动作（修改团队信息、成员管理、删除团队、删除工具）要求同时具备全局权限且在该团队内是所有者或管理员。

团队角色与典型组合

实际能力 = 全局角色权限 ∩ 团队门限。以下是最常见组合（假设成员已被授予对应全局角色）：

团队内观察者与全局 Viewer 角色是两件事：前者只是「在这个团队里级别最低」，不会自动获得全局 Viewer 权限；反之把全局 Viewer 加进团队时，建议同时设为观察者。

团队管理动作的完整约束见团队与成员。

资源可见性

除了两层门限，资源自身的可见性也会拦截：

Agent 与工作流的规则一致。其他团队即使知道资源地址，也无法查看或调用。

共享资源

跨团队共享覆盖工具与知识库：

• 自定义工具可以由所属团队的管理员共享给其他团队，接收团队在「共享给我」中查看，权限分为只读与可查看执行结果两档。
• 知识库可以由所属团队的管理员以只读方式共享给其他团队；接收团队可以查看和检索，不能修改。
• 私有资源不能共享，也不能共享给本团队；共享是单向的，由所属团队建立和撤销。
• Agent、工作流没有「按团队逐个授权」的共享层级：跨团队可见性由资源自身的可见性决定，其余情况默认团队隔离。

API Key 归属

API Key 按用户归属，可设置过期时间、绑定指定 Agent 与工作流，并在页面或个人设置中管理。界面上可以填写每分钟请求上限与作用域，但当前版本不会实际限流，也不会据此收窄权限——不要把它们当成生效的安全措施。Key 的访问仍受绑定对象与团队隔离约束，详见 API Key 参考。

权限审计

没有专门的权限变更审计视图，审计日志也没有「授权」或「撤销」动作类型。当前覆盖范围：

审计日志在 Audit Logs 页面按资源与操作筛选查看，需要审计日志查看权限。详见审计日志。

排查 403

权限被拒绝

症状： 功能不可用，页面提示无权限、需要团队管理员或不是团队成员。

按顺序排查：

1. 全局权限是否缺失？ 在 Admin → Users 编辑用户，看角色里有没有包含目标能力的角色（对照权限参考）。错误提示通常会指出缺少哪一项权限。
2. 团队门限是否不够？ 属于团队管理动作时，必须是团队所有者或管理员；团队观察者做写操作一定会被拒。
3. 是不是团队成员？ 「不是团队成员」表示该用户根本不在这个团队里。
4. 资源是否私有？ 私有资源对非创建者返回无权限，与角色权限无关。
5. 是不是别人的 API Key？ Key 只能由本人或超级管理员读写。

过度授权的用户

1. 在 Users 里查看目标用户的角色，对照权限参考逐条核对。
2. 在 Roles 里查看每个角色的权限集——内置 Admin 已覆盖全部团队资源，通常没必要再叠加宽权限的自定义角色。
3. 降级前先检查该用户是否仍是某些团队的所有者或管理员，否则角色保存会被保护规则拒绝。
4. 定期复核。角色变更不写审计日志，改角色时请自行留痕。

权限行为不一致

1. 确认检查层：团队内请求是「全局权限 + 团队门限」两层；只有管理台接口才看管理台权限。
2. 确认角色来源：用户可能有多个角色，权限取并集；也可能在启动时被补授 Team Admin。
3. 确认内置角色不能手改：内置角色的权限集每次启动都会恢复。

最佳实践

推荐：

• 用自定义角色承载岗位权限，不用「多给几个内置角色」凑能力。
• 团队管理员先授予 Team Admin 全局角色，再在团队内设为管理员（顺序反了会被拒绝）。
• 团队只读人员同时使用团队观察者和全局 Viewer。
• API Key 按集成单独创建、单独轮换，不要共用个人账号的 Key。
• 每季度复核角色成员与团队所有者/管理员名单。

避免：

• 直接把 Super Admin 当日常账号使用。
• 试图修改内置角色的权限。
• 依赖「前端看不到按钮」当作安全边界。
• 用一个共享账户跑多个集成。

保护规则

• 五个内置角色与内置权限不可删除、不可改名，权限集也不可修改。
• 删除自定义角色前必须先解除指派。
• 超级管理员账户不能删除，也不能停用。
• 默认团队不能删除；团队所有者不能离开或被移除，必须先行转让所有权。
• 权限变更对后续请求立即生效，已登录会话不缓存权限。

相关文档

• 权限与角色参考 — 权限目录、内置角色矩阵与菜单映射
• 团队与成员 — 成员增删改、离开、转让所有权
• 用户管理 — 用户创建、启用/停用、删除与角色指派
• 审计日志 — 角色与成员变更的审计覆盖范围