2.2 角色管理
管理系统角色与组织自定义角色。访问控制按角色名称字符串匹配生效。
进入路径:左侧主导航 → 管理后台 → 权限管理。 路径:/admin/permissions权限:仅 super_admin
ℹ️ 权限点(Permission)系统已于 2026-05-22 下线。平台不再有独立的
Permission(权限点)对象,也没有"资源 × 操作 × 范围"三元组。访问控制改为按角色名称字符串匹配:admin/owner/super_admin/member(以及任意自定义角色名)。本页只剩"角色列表"一项功能。
2.2.1 页面结构
整页只有一个 角色列表(无 Tab、无权限点 CRUD、无权限分配双列、无统计卡片)。
2.2.2 角色列表
表格列
| 列 | 说明 |
|---|---|
| 名称 | 角色名称(代码形式,鉴权依据),如 admin / kb_curator |
| 显示名 | 中文名 |
| 类型 | 自定义 / 组织 / 系统 |
| 组织 | 角色所属组织(系统角色为空/全局) |
| 系统角色 | 是否内置系统角色(内置不可删) |
| 启用 | 启用 / 禁用 |
| 操作 | 编辑 / 删除(系统角色删除 disabled) |
系统内置角色
| 角色名 | 含义 |
|---|---|
super_admin | 超管,所有权限 |
owner | 组织拥有者,组织内所有权限 |
admin | 组织管理员,组织内管理权限 |
member | 普通成员,只能用资源、不能配资源 |
系统角色不可删除,但可以禁用。
创建/编辑角色对话框
| 字段 | 创建后可改 | 必填 | 说明 |
|---|---|---|---|
| 角色名称 | ❌ | ✓ | 代码形式,如 kb_curator。创建后不可修改,是鉴权依据 |
| 显示名 | ✓ | ✓ | 中文名 |
| 描述 | ✓ | ||
| 类型 | ❌ | ✓ | 自定义 / 组织 / 系统(仅创建时可选) |
⚠️ 标 ❌ 的字段创建后不可改。角色名称错了只能删除重建。
2.2.3 访问控制模型(关键)
平台访问控制按 角色名称 字符串匹配:
- 内置识别名:
admin/owner/super_admin/member(后端依赖如require_admin()直接对这些名字做字符串比对) - 自定义角色名:可自由创建,用于业务侧岗位区分(如
kb_curator) - 平台不再有独立的 Permission(权限点)对象,也没有"资源 × 操作 × 范围"三元组
💡 新建一个名叫
xxx_admin的角色不会被require_admin()等依赖识别成"管理员"——除非角色名恰好是admin/super_admin/owner/member之一。自定义角色名靠业务页面自行判定。
2.2.4 设计角色的最佳实践
💡 这一节是经验,非强制规范。
1. 优先用系统角色
系统角色覆盖了 80% 场景,先看是否能用 member 解决。
2. 自定义角色按"业务岗位"建,不按"功能模块"建
❌ 不好:agent_admin(智能体管理员)— 跨业务,容易冲突 ✅ 好:kb_curator(知识库策划)— 单一职责
3. 定期清理无引用的自定义角色
新业务上来时建了一堆 xxx_v2 角色,旧业务下线后忘了删。建议每季度复查一次孤儿角色。
2.2.5 角色与用户关系
用户 ──[加入组织]── 组织
│
└──[在该组织被授予]── 角色(命名字符串)一个用户在不同组织可以有不同角色。同一组织内一个用户可以有多个角色。
2.2.6 常见问题
Q1:为什么有些操作明明授了角色还是 403?
检查清单:
- 角色是不是被禁用了
- 用户在该组织有没有这个角色(注意是组织级,不是平台级)
- 角色名是否被后端识别(管理类操作要求
admin/super_admin/owner之一) - 后端是否需要重启 / 缓存刷新(部分场景角色缓存 60s)
Q2:批量给一组用户改角色?
当前 UI 不支持批量。需要在「用户管理 - 管理角色」对话框里一个个改,或用后端 CLI:
siracli role assign --role kb_curator --org acme --user-csv users.csvQ3:能"克隆"一个角色吗?
UI 没有克隆按钮。新建角色 → 填写名称即可(不再需要勾选权限点)。
Q4:角色改了之后用户多久生效?
- 用户 → 角色的关系:立即生效(下一次请求)
- 但前端已加载的页面可能仍显示旧菜单,刷新页面即可。
Q5:能审计"谁给谁授权"了吗?
可以。所有角色变更都会写到 行为审计,resource 类型为 role,可以过滤查看。