skillhub/document/docs/02-administration/security/authorization.md

title	sidebar_position	description
权限管理	2	RBAC 权限系统配置

权限管理

SkillHub 采用基于角色的访问控制（RBAC）系统。

当前代码里实际存在两套并行角色体系：

• 平台角色：控制后台治理、用户管理、审计等平台级能力。
• 命名空间角色：控制某个团队空间内的成员、发布、审核、归档等操作。

二者会同时参与鉴权，但不是一套角色的上下级映射。

平台角色

代码里实际初始化的显式平台角色

数据库迁移只初始化了 4 个显式平台角色：

角色	代码	实际能力
超级管理员	SUPER_ADMIN	拥有全部权限；RbacService#getUserPermissions 会直接返回全部权限码；可访问所有 SUPER_ADMIN/SKILL_ADMIN/USER_ADMIN/AUDITOR 能访问的接口；可分配 SUPER_ADMIN；发布技能时可绕过命名空间成员校验并直接自动发布；但仍不能审批自己提交的 promotion，且普通审核单若是自己提交的，也只有 SUPER_ADMIN 能特判审批。
技能管理员	SKILL_ADMIN	可访问技能治理后台接口；可隐藏/取消隐藏技能、撤回版本（yank）、处理技能举报；可查看和处理全局空间审核、promotion 审核、治理工作台收件箱中的 review/promotion/report；不能分配平台角色、不能看审计日志、不能管理用户。
用户管理员	USER_ADMIN	可访问用户管理接口；可列表用户、审批用户、启用/禁用用户、修改平台角色；不能分配 SUPER_ADMIN；不能处理技能治理、不能看审计日志。
审计员	AUDITOR	只读查看审计日志；可访问 /api/v1/admin/audit-logs 和 /actuator/prometheus；治理工作台中只能看 activity，不能处理 review/promotion/report，也不能管理用户或技能。

运行时默认平台角色

角色	代码	实际逻辑
默认用户	USER	不是 role 表里的显式初始化记录。只要用户没有任何显式平台角色绑定，登录态和 RbacService#getUserRoleCodes 都会自动补上 USER。它主要表示“普通已登录用户”，没有额外后台治理权限。

需要特别注意的实现细节

• 当前管理接口的“修改用户角色”是单值覆盖，不是追加：PUT /api/v1/admin/users/{userId}/role 先清空该用户现有平台角色，再写入一个目标角色；当目标角色是 USER 时，不会写数据库记录，而是依赖运行时默认补位。
• 代码底层仍然支持“一个用户拥有多个显式平台角色”的读取与鉴权，因为 session、token 和 RbacService 都是按角色集合处理；只是当前管理接口不会这样分配。
• SUPER_ADMIN 是唯一一个在权限查询时被视为“拥有全部 permission code”的角色，其它角色依赖 role_permission 关联表。

命名空间角色

角色	实际能力
OWNER	创建团队空间时自动成为 OWNER。可更新命名空间信息、管理成员、冻结/解冻空间、归档/恢复空间、转移所有权；可提交 review；可审核团队空间 review；可访问私有技能；可管理受限技能生命周期（归档、反归档、删除草稿/驳回版本等）。
ADMIN	可更新命名空间信息、管理成员、冻结/解冻空间；不能归档/恢复空间，也不能直接把别人设为 OWNER；可提交 review；可审核团队空间 review；可访问私有技能；可管理受限技能生命周期。
MEMBER	默认加入全局空间时获得 MEMBER。可在所在命名空间发布技能、提交 review；但不能审核 review、不能管理成员、不能冻结/归档空间；私有技能也不能仅因 MEMBER 身份访问，私有技能要求 owner 或 ADMIN/OWNER。

命名空间角色的边界

• GLOBAL 空间是只读系统空间，不能通过命名空间治理接口修改；全局空间 review/promotion/report 处理依赖平台角色 SKILL_ADMIN/SUPER_ADMIN，不是依赖全局空间成员身份。
• NAMESPACE_ONLY 可见性的技能，任何该命名空间成员都能访问。
• PRIVATE 可见性的技能，只有技能 owner 或命名空间 ADMIN/OWNER 能访问，MEMBER 不行。

权限配置

通过后台分配平台角色，通过命名空间成员关系分配命名空间角色。

下一步

• 审计日志 - 查看操作审计