---
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)。