fca3326e34
- 更新 changelog.md: v0.2.0 记录 M2-M8 全部完成，路线图更新 - 新增 5 篇指南: RBAC、组织管理、审计日志、通知模块、质量横切 - 新增 5 篇 API 文档: RBAC(11)、Org(5)、Audit(1)、Settings(7)、Notification(7) - 更新 api/overview.md: 完整 37 端点列表 - 更新 config.ts: 侧边栏分组 + 11 页 SEO 元数据
102 lines
3.1 KiB
Markdown
102 lines
3.1 KiB
Markdown
---
|
||
title: RBAC 权限模型 | 角色权限管理与中间件鉴权 - MengStack官方文档
|
||
---
|
||
|
||
# RBAC 权限模型
|
||
|
||
MengStack 内置基于角色的访问控制（RBAC）模块，支持多租户隔离下的权限管理。
|
||
|
||
## 数据模型
|
||
|
||
RBAC 由 4 张核心表组成：
|
||
|
||
| 表 | 说明 | 关键字段 |
|
||
|------|------|----------|
|
||
| `permissions` | 权限定义 | code（唯一码）、name、module |
|
||
| `roles` | 角色定义 | tenant_id、name、is_system |
|
||
| `role_permissions` | 角色-权限关联（多对多） | role_id、permission_id |
|
||
| `user_roles` | 用户-角色关联 | user_id、tenant_id、role_id |
|
||
|
||
```
|
||
Permission ←→ Role ←→ User
|
||
(M:N) (M:N)
|
||
```
|
||
|
||
## 权限码规范
|
||
|
||
权限码采用 `模块:资源:动作` 三段式命名：
|
||
|
||
```
|
||
auth:user:read # 查看用户
|
||
auth:user:write # 编辑用户
|
||
rbac:role:manage # 管理角色
|
||
org:tenant:manage # 管理租户
|
||
notification:send # 发送通知
|
||
```
|
||
|
||
## 种子数据
|
||
|
||
框架启动时自动创建预置角色和权限：
|
||
|
||
| 角色 | 说明 | 权限范围 |
|
||
|------|------|----------|
|
||
| `admin` | 管理员（系统角色，不可删除） | 全部权限 |
|
||
| `editor` | 编辑者 | 内容读写 + 通知 |
|
||
| `viewer` | 查看者 | 只读权限 |
|
||
|
||
## 使用方式
|
||
|
||
### 1. 给用户分配角色
|
||
|
||
```bash
|
||
curl -X POST http://localhost:2222/api/v1/rbac/users/1/roles \
|
||
-H "Authorization: Bearer <token>" \
|
||
-H "X-Tenant-ID: <tenant_id>" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"role_id": 1}'
|
||
```
|
||
|
||
### 2. 为角色设置权限
|
||
|
||
```bash
|
||
curl -X PUT http://localhost:2222/api/v1/rbac/roles/1/permissions \
|
||
-H "Authorization: Bearer <token>" \
|
||
-H "X-Tenant-ID: <tenant_id>" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"permission_ids": [1, 2, 3]}'
|
||
```
|
||
|
||
### 3. 在路由中使用权限中间件
|
||
|
||
```go
|
||
// 在 routes.go 中
|
||
rbac.GET("/users", h.ListUsers, permMW.Require("auth:user:read"))
|
||
rbac.POST("/users", h.CreateUser, permMW.Require("auth:user:write"))
|
||
```
|
||
|
||
`permMW.Require()` 会从 JWT 中提取用户 ID 和租户 ID，查询该用户在此租户下的所有角色权限并集，判断是否包含所需权限码。
|
||
|
||
## 多租户隔离
|
||
|
||
- 角色按 `tenant_id` 隔离，不同租户的角色互不影响
|
||
- 用户角色关联也按 `tenant_id` 隔离，同一用户在不同租户可拥有不同角色
|
||
- 权限定义是全局共享的（不区分租户）
|
||
|
||
## API 端点
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/v1/rbac/permissions` | 列出权限（可按 module 筛选） |
|
||
| POST | `/api/v1/rbac/roles` | 创建角色 |
|
||
| GET | `/api/v1/rbac/roles` | 列出角色 |
|
||
| GET | `/api/v1/rbac/roles/:id` | 获取角色详情 |
|
||
| PUT | `/api/v1/rbac/roles/:id` | 更新角色 |
|
||
| DELETE | `/api/v1/rbac/roles/:id` | 删除角色 |
|
||
| PUT | `/api/v1/rbac/roles/:id/permissions` | 设置角色权限 |
|
||
| GET | `/api/v1/rbac/roles/:id/permissions` | 获取角色权限 |
|
||
| POST | `/api/v1/rbac/users/:userId/roles` | 分配角色给用户 |
|
||
| DELETE | `/api/v1/rbac/users/:userId/roles/:roleId` | 移除用户角色 |
|
||
| GET | `/api/v1/rbac/users/:userId/roles` | 获取用户角色 |
|
||
|
||
详细接口参数见 [RBAC API 参考](/api/rbac)。
|