Skip to content

RBAC 权限模块 ​

RBAC(基于角色的访问控制)模块提供权限定义、角色管理、用户角色分配等能力。支持多租户隔离,角色租户内唯一,权限全局共享。系统预置 60+ 个权限点(权威清单见 rbac/infrastructure/seed.go 的 defaultPermissions)和 3 个系统角色。

架构概览 ​

modules/rbac/
├── domain/          # Role、Permission、UserRole 实体、Repository 接口
├── application/     # Service(角色/权限/用户角色管理)
├── infrastructure/  # GORM Repository 实现、种子数据、AutoMigrate
├── middleware/      # PermissionMiddleware(权限校验中间件)
└── interfaces/      # HTTP Handler、路由注册

数据模型 ​

Permission(权限) ​

字段类型说明
IDuint主键
Codestring(128)权限码,全局唯一,如 auth.user.read
Namestring(128)显示名称
Modulestring(64)所属模块
Descriptionstring(256)描述

表名: permissions(全局,非租户隔离)

Role(角色) ​

字段类型说明
IDuint主键
TenantIDstring (UUID)租户 ID,复合主键
Namestring(64)角色名,租户内唯一
Descriptionstring(256)描述
IsSystembool是否系统角色(不可修改/删除)
Permissions[]Permission多对多关联

表名: roles

关联表 ​

表名说明
role_permissions角色-权限多对多关联(RoleID, PermissionID)
user_roles用户-角色关联(UserID, TenantID, RoleID),三元复合主键

权限模型 ​

User ──[user_roles]──> Role ──[role_permissions]──> Permission
  • 权限 全局定义,所有租户共享
  • 角色 租户隔离,每个租户独立管理
  • 用户角色 租户隔离,同一用户在不同租户可拥有不同角色
  • 权限码命名规范:{module}.{resource}.{action}

预置权限(37 个) ​

模块权限码
authauth.user.read、auth.user.write
rbacrbac.role.read、rbac.role.write、rbac.permission.read、rbac.permission.assign、rbac.user_role.write
orgorg.tenant.read、org.tenant.write
auditaudit.log.read
settingssettings.read、settings.write
notificationnotification.manage
dashboarddashboard.read
cmscms.article.read、cms.article.write、cms.channel.write、cms.category.write、cms.tag.write、cms.media.write
commentcomment.read、comment.moderate、comment.report.manage
topictopic.read、topic.write
flashflash.read、flash.write、flash.category.write
communitycommunity.board.write、community.post.write、community.post.moderate
searchsearch.log.read、search.hotword.write
seoseo.config.write、seo.sitemap.write、seo.redirect.write、seo.link.write

预置系统角色(3 个) ​

角色权限范围说明
super_admin全部权限超级管理员,拥有所有权限
tenant_admin除 rbac.role.write、rbac.permission.assign、rbac.user_role.write 外的全部权限租户管理员,不可管理 RBAC 角色/权限分配/用户角色
member只读权限:auth.user.read、rbac.permission.read、dashboard.read、cms.article.read、comment.read、topic.read、flash.read、settings.read普通成员

系统角色(IsSystem: true)不可修改、删除或变更权限。

API 接口 ​

所有接口需认证 + 多租户中间件。

权限管理 ​

方法路径权限说明
GET/api/v1/rbac/permissionsrbac.permission.read获取全部权限列表

角色管理 ​

方法路径权限说明
POST/api/v1/rbac/rolesrbac.role.write创建角色
GET/api/v1/rbac/rolesrbac.role.read角色列表
GET/api/v1/rbac/roles/:idrbac.role.read角色详情(含权限)
PUT/api/v1/rbac/roles/:idrbac.role.write更新角色
DELETE/api/v1/rbac/roles/:idrbac.role.write删除角色
PUT/api/v1/rbac/roles/:id/permissionsrbac.permission.assign设置角色权限(全量替换)
GET/api/v1/rbac/roles/:id/permissionsrbac.permission.read获取角色权限列表

用户角色管理 ​

方法路径权限说明
POST/api/v1/rbac/users/:userId/rolesrbac.user_role.write分配角色给用户(幂等)
DELETE/api/v1/rbac/users/:userId/roles/:roleIdrbac.user_role.write移除用户角色
GET/api/v1/rbac/users/:userId/rolesrbac.role.read获取用户角色列表

请求/响应示例 ​

创建角色 ​

json
// POST /api/v1/rbac/roles
// Request
{
  "name": "editor",
  "description": "内容编辑"
}

// Response 200
{
  "id": 10,
  "tenant_id": "uuid-xxx",
  "name": "editor",
  "description": "内容编辑",
  "is_system": false,
  "permissions": []
}

设置角色权限 ​

json
// PUT /api/v1/rbac/roles/10/permissions
// Request
{
  "permission_ids": [1, 2, 14, 15, 16, 17, 18, 19]
}

// Response 200 OK

分配角色给用户 ​

json
// POST /api/v1/rbac/users/5/roles
// Request
{
  "role_id": 10
}

// Response 200 OK

权限中间件 ​

PermissionMiddleware.RequirePermission(permCode) 定义于 rbac/middleware/permission.go:

  1. 从 Gin Context 读取 user_id
  2. 调用 svc.UserHasPermission(ctx, userID, permCode) 校验
  3. 无 user_id → 401;无权限 → 403;内部错误 → 500

业务规则 ​

  • 系统角色(IsSystem: true)不可更新、删除或修改权限,服务层返回 403
  • 角色名租户内唯一(复合唯一索引 idx_tenant_role_name)
  • 角色分配幂等 — 已存在的分配自动跳过
  • SetRolePermissions 全量替换角色权限(非增量)
  • GetUserPermissions 返回去重后的权限并集

依赖注入 ​

go
fx.Module("rbac",
    fx.Provide(
        infrastructure.NewPermissionRepository,
        infrastructure.NewRoleRepository,
        infrastructure.NewUserRoleRepository,
        application.NewService,
        NewHandler,
        rbacmiddleware.NewPermissionMiddleware,
    ),
)

Released under the Apache 2.0 License.