Appearance
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(权限)
| 字段 | 类型 | 说明 |
|---|---|---|
| ID | uint | 主键 |
| Code | string(128) | 权限码,全局唯一,如 auth.user.read |
| Name | string(128) | 显示名称 |
| Module | string(64) | 所属模块 |
| Description | string(256) | 描述 |
表名: permissions(全局,非租户隔离)
Role(角色)
| 字段 | 类型 | 说明 |
|---|---|---|
| ID | uint | 主键 |
| TenantID | string (UUID) | 租户 ID,复合主键 |
| Name | string(64) | 角色名,租户内唯一 |
| Description | string(256) | 描述 |
| IsSystem | bool | 是否系统角色(不可修改/删除) |
| Permissions | []Permission | 多对多关联 |
表名: roles
关联表
| 表名 | 说明 |
|---|---|
role_permissions | 角色-权限多对多关联(RoleID, PermissionID) |
user_roles | 用户-角色关联(UserID, TenantID, RoleID),三元复合主键 |
权限模型
User ──[user_roles]──> Role ──[role_permissions]──> Permission- 权限 全局定义,所有租户共享
- 角色 租户隔离,每个租户独立管理
- 用户角色 租户隔离,同一用户在不同租户可拥有不同角色
- 权限码命名规范:
{module}.{resource}.{action}
预置权限(37 个)
| 模块 | 权限码 |
|---|---|
| auth | auth.user.read、auth.user.write |
| rbac | rbac.role.read、rbac.role.write、rbac.permission.read、rbac.permission.assign、rbac.user_role.write |
| org | org.tenant.read、org.tenant.write |
| audit | audit.log.read |
| settings | settings.read、settings.write |
| notification | notification.manage |
| dashboard | dashboard.read |
| cms | cms.article.read、cms.article.write、cms.channel.write、cms.category.write、cms.tag.write、cms.media.write |
| comment | comment.read、comment.moderate、comment.report.manage |
| topic | topic.read、topic.write |
| flash | flash.read、flash.write、flash.category.write |
| community | community.board.write、community.post.write、community.post.moderate |
| search | search.log.read、search.hotword.write |
| seo | seo.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/permissions | rbac.permission.read | 获取全部权限列表 |
角色管理
| 方法 | 路径 | 权限 | 说明 |
|---|---|---|---|
| POST | /api/v1/rbac/roles | rbac.role.write | 创建角色 |
| GET | /api/v1/rbac/roles | rbac.role.read | 角色列表 |
| GET | /api/v1/rbac/roles/:id | rbac.role.read | 角色详情(含权限) |
| PUT | /api/v1/rbac/roles/:id | rbac.role.write | 更新角色 |
| DELETE | /api/v1/rbac/roles/:id | rbac.role.write | 删除角色 |
| PUT | /api/v1/rbac/roles/:id/permissions | rbac.permission.assign | 设置角色权限(全量替换) |
| GET | /api/v1/rbac/roles/:id/permissions | rbac.permission.read | 获取角色权限列表 |
用户角色管理
| 方法 | 路径 | 权限 | 说明 |
|---|---|---|---|
| POST | /api/v1/rbac/users/:userId/roles | rbac.user_role.write | 分配角色给用户(幂等) |
| DELETE | /api/v1/rbac/users/:userId/roles/:roleId | rbac.user_role.write | 移除用户角色 |
| GET | /api/v1/rbac/users/:userId/roles | rbac.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:
- 从 Gin Context 读取
user_id - 调用
svc.UserHasPermission(ctx, userID, permCode)校验 - 无
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,
),
)
