角色管理

概述

角色管理模块用于定义和管理系统中的角色。角色是权限分配的桥梁，通过将 API 资源的权限范围（Scope）分配给角色，再将角色分配给用户或机器对机器应用，实现基于角色的访问控制（RBAC）。

导航路径: 侧边栏 -> 角色管理

角色类型

类型	说明
User	用户角色，分配给终端用户
MachineToMachine	机器对机器角色，分配给 MachineToMachine 类型的应用

角色列表

角色列表页面展示所有已定义的角色。

列表字段

字段	说明
名称	角色的显示名称
描述	角色的说明
类型	User / MachineToMachine
默认角色	是否为系统默认角色
创建时间	角色创建时间

搜索与筛选

• 关键词搜索 (search): 模糊匹配角色名称
• 名称 (name): 精确匹配
• 角色 ID (id): 精确匹配
• 用户 ID (user_id): 查找分配给某用户的角色

创建角色

点击 "新建角色" 按钮进入创建页面。

导航路径: 角色管理 -> 新建角色

创建参数

字段	必填	说明
名称	是	角色的显示名称
描述	否	角色的说明文字
类型	否	角色类型，默认为 User

API 调用:

POST /api/v1/roles

请求示例：

{
  "name": "订单管理员",
  "description": "可以管理所有订单相关操作",
  "type": "User"
}

编辑角色

在角色列表中点击角色名称或编辑按钮，进入角色编辑页面。

导航路径: 角色管理 -> 编辑角色

基本信息

可修改角色的名称和描述。

API 调用:

PATCH /api/v1/roles/:id

权限范围（Scope）分配

为角色分配 API 资源的权限范围，控制拥有该角色的用户可以访问哪些 API 操作。

查看角色权限

获取角色当前拥有的权限范围列表。每个权限范围项包含以下信息：

字段	说明
权限名称	权限范围的名称（如 read:orders）
描述	权限范围的说明
所属资源 ID	权限范围所属的 API 资源 ID
所属资源名称	权限范围所属的 API 资源名称

API 调用:

GET /api/v1/roles/:id/scopes

分配/移除权限

通过 PUT 请求同时指定要添加和移除的权限范围 ID。

API 调用:

PUT /api/v1/roles/:id/scopes

请求示例：

{
  "scope_ids": ["scope_id_1", "scope_id_2"],
  "remove_scope_ids": ["scope_id_3"]
}

• scope_ids: 要添加的权限范围 ID 列表
• remove_scope_ids: 要移除的权限范围 ID 列表

用户分配

管理哪些用户拥有该角色。

查看角色用户

获取拥有该角色的用户列表。

API 调用:

GET /api/v1/roles/:id/users

返回字段包括用户 ID、用户名、邮箱和姓名。

分配/移除用户

通过 PUT 请求同时指定要添加和移除的用户 ID。

API 调用:

PUT /api/v1/roles/:id/users

请求示例：

{
  "user_ids": ["user_id_1", "user_id_2"],
  "remove_user_ids": ["user_id_3"]
}

• user_ids: 要添加的用户 ID 列表
• remove_user_ids: 要移除的用户 ID 列表

删除角色

删除角色将移除所有关联的权限分配和用户分配。此操作不可逆。

API 调用:

DELETE /api/v1/roles/:id

注意: 删除角色前，请确认已将受影响的用户迁移到其他角色，避免用户失去必要的访问权限。

RBAC 权限模型示例

以下是一个典型的权限分配流程：

1. 定义 API 资源: 创建 "订单 API" 资源，添加 read:orders、write:orders 权限范围
2. 创建角色: 创建 "订单查看者" 角色，分配 read:orders 权限范围
3. 创建角色: 创建 "订单管理员" 角色，分配 read:orders 和 write:orders 权限范围
4. 分配用户: 将需要查看订单的用户分配到 "订单查看者" 角色
5. 分配用户: 将需要管理订单的用户分配到 "订单管理员" 角色

用户在请求访问令牌时，令牌中会包含其所有角色关联的权限范围。