权限

2.0.2 的管理端授权使用 canonical permission path + action code。canonical path 是稳定的授权资源标识符，不是 Admin UI 路由，也不是 HTTP 挂载路径。例如 /runtime/db-management 和 /auth/role 即使导航或 controller URL 调整，仍表示同一个授权身份。

相同的 canonical identifiers 支持两种互斥的管理端授权模式。使用内置身份系统时，HsSqlAgent 的 member / role 会解析 permission/action templates；使用 host authorization 时，HsSqlAgent 会通过 HsSqlAgentPermissionResource.Permissions 把请求的 canonical permission keys 交给宿主，由宿主映射到自己的 policy model。除非特别说明，下方角色与 template 章节描述的是 内置身份模式。

运行时示例

因此，仅完成身份验证并不足以执行这些操作；所需 path/action 组合还必须能通过成员角色解析出来。

Permission-action 模板是权威来源

Role API 提供 permission-action-templates 清单。每个模板包含：

• permission ID、名称和 path
• action ID、code 和名称

角色请求以 { PermissionId, ActionId } 组合提交选择。角色服务会去除重复项，并只保存模板清单中存在的组合。

角色是权限分配单位

成员被分配角色，角色持有 permission/action 选择。这样可以把用户生命周期与可复用访问策略分开：

Member
  └─ Role(s)
       └─ Permission path + Action

一个成员可以拥有多个角色。最终管理权限是这些已分配角色所覆盖权限面的并集。

授权变化会让旧状态失效

修改角色权限属于安全敏感操作。角色权限变化时，角色服务会找到受影响成员，递增其 security version，并通过 auth runtime-state cache barrier 执行变更。

目的是避免之前已登录的会话在角色定义变化后继续持有旧授权。

受保护的 SuperUser 角色

SuperUser 是 2.0.2 内置受保护角色，无法通过普通角色管理编辑或删除，避免 bootstrap/全权限角色被悄悄改造成另一套权限。

相关文档

• 成员与角色 — 成员生命周期和角色保护规则。
• 数据库管理 — 数据库与语义权限示例。
• MCP 密钥 — MCP 凭据与管理角色属于不同授权边界。
• 安全策略 — 使用独立管理权限维护的运行时 SQL、限流和并发策略。