aiagent/docs/multi-tenant-rbac-guide.md

多租户与 RBAC 权限管理指南

Multi-Tenant & RBAC Guide — 工作区隔离、角色权限、用户管理完整说明

本文档涵盖天工智能体平台 v1.2+ 的多租户架构、RBAC 权限体系、工作区管理和平台管理员功能。

---

一、多租户架构概览

1.1 什么是多租户

天工平台采用 工作区 (Workspace) 作为租户隔离的基本单元：

┌────────────────────────────────────────────────────┐
│                    天工平台                          │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────┐ │
│  │  工作区 A     │  │  工作区 B     │  │ 工作区 C   │ │
│  │  (研发团队)   │  │  (市场团队)   │  │ (个人空间) │ │
│  │              │  │              │  │           │ │
│  │ Agent: 5 个  │  │ Agent: 3 个  │  │ Agent: 2  │ │
│  │ 工作流: 8 个 │  │ 工作流: 4 个 │  │ 工作流: 3 │ │
│  │ 知识库: 3 个 │  │ 知识库: 1 个 │  │ 知识库: 1 │ │
│  │ 成员: 12 人  │  │ 成员: 5 人   │  │ 成员: 1   │ │
│  └──────────────┘  └──────────────┘  └───────────┘ │
└────────────────────────────────────────────────────┘

1.2 核心隔离原则

隔离维度	说明
数据隔离	每个工作区的 Agent、工作流、知识库、执行记录等数据完全隔离
成员隔离	工作区 A 的成员默认无法访问工作区 B 的任何资源
API 隔离	所有资源 API 自动按工作区过滤，返回结果仅限当前工作区
WebSocket 隔离	实时推送按工作区频道隔离，不会跨工作区串消息

1.3 JWT Token 中的工作区标识

登录或切换工作区后，JWT Token 中会携带 ws 字段：

{
  "sub": "user-uuid-xxx",
  "ws": "workspace-uuid-xxx",
  "exp": 1712345678
}

所有后续 API 请求自动按此工作区范围过滤数据。

---

二、工作区管理

2.1 工作区列表

进入「工作区管理」页面，查看你有权限访问的所有工作区：

┌──────────────────────────────────────────────────────┐
│  工作区管理                            [+ 创建工作区]  │
│                                                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │
│  │ 研发团队     │  │ 个人空间     │  │ AI实验室    │  │
│  │ [默认] [管理员]│  │ [成员]      │  │ [管理员]    │  │
│  │ 描述...      │  │ 描述...      │  │ 描述...     │  │
│  │ 状态: 启用   │  │ 状态: 启用   │  │ 状态: 停用  │  │
│  │ [进入] [管理]│  │ [进入]       │  │ [进入] [管理]│  │
│  └─────────────┘  └─────────────┘  └─────────────┘  │
└──────────────────────────────────────────────────────┘

2.2 创建工作区

1. 点击「创建工作区」按钮
2. 填写工作区信息：

字段	说明	限制
名称	工作区唯一标识	1-100 字符
描述	可选说明信息	最多 1000 字符
最大成员数	工作区成员上限	1-500，默认 50

3. 创建者自动成为该工作区的 管理员 (admin)

2.3 切换工作区

• 在工作区列表中点击「进入」自动切换
• 或通过顶部导航栏的工作区下拉选择器切换
• 切换后 JWT Token 刷新，后续所有操作在新工作区上下文中执行

2.4 管理工作区

点击「管理」进入工作区详情页，包含三个标签页：

基本信息

• 修改名称、描述、最大成员数
• 启用/停用工作区（停用后成员无法访问）

成员管理

• 查看当前成员列表（用户名、邮箱、角色）
• 添加新成员（按用户名查找）
• 修改成员角色（管理员 / 成员）
• 移除成员

危险操作

• 删除工作区（软删除，状态标记为 deleted）

2.5 角色说明

角色	权限范围
admin (工作区管理员)	管理成员、修改设置、删除工作区、创建/编辑/删除所有资源
member (成员)	查看和创建资源，编辑自己创建的资源

注意: 工作区管理员 ≠ 平台管理员。工作区管理员仅管理当前工作区，平台管理员拥有全局权限。

---

三、RBAC 权限体系

3.1 系统角色

天工平台定义了 4 个系统级角色：

角色	说明	典型用户
admin (平台管理员)	全局管理权限，绕过所有工作区限制	平台运维
developer (开发者)	创建和管理 Agent、工作流、知识库	核心开发
viewer (只读用户)	仅查看，无创建/编辑/删除权限	审计、管理层
operator (操作员)	管理执行、监控告警，但不创建新 Agent	运维

3.2 权限列表 (23 项)

所有权限按资源类型分组：

权限码	说明	developer	viewer	operator
workflow:create	创建工作流	✅	❌	❌
workflow:read	查看工作流	✅	✅	✅
workflow:update	编辑工作流	✅	❌	❌
workflow:delete	删除工作流	✅	❌	❌
workflow:execute	执行工作流	✅	❌	✅
workflow:publish	发布工作流	✅	❌	❌
agent:create	创建 Agent	✅	❌	❌
agent:read	查看 Agent	✅	✅	✅
agent:update	编辑 Agent	✅	❌	❌
agent:delete	删除 Agent	✅	❌	❌
agent:deploy	部署 Agent	✅	❌	✅
agent:stop	停止 Agent	✅	❌	✅
execution:read	查看执行记录	✅	✅	✅
execution:stop	中止执行	✅	❌	✅
data_source:create	创建数据源	✅	❌	❌
data_source:read	查看数据源	✅	✅	✅
data_source:update	编辑数据源	✅	❌	❌
data_source:delete	删除数据源	✅	❌	❌
model_config:create	创建模型配置	✅	❌	❌
model_config:read	查看模型配置	✅	✅	✅
model_config:update	编辑模型配置	✅	❌	❌
model_config:delete	删除模型配置	✅	❌	❌
permission:manage	管理权限	❌	❌	❌

admin 角色拥有所有 23 项权限（通配符 *），且绕过所有工作区成员资格检查。

3.3 权限检查流程

API 请求
  │
  ├─ 1. JWT 认证 (get_current_user)
  │   └─ 失败 → 401 Unauthorized
  │
  ├─ 2. 工作区成员资格检查 (get_workspace_membership)
  │   ├─ 平台管理员 → 直接放行
  │   ├─ 非成员 → 403 Forbidden
  │   └─ 成员 → 继续
  │
  ├─ 3. 细粒度权限检查 (WorkspacePermission)
  │   ├─ 无该权限 → 403 Forbidden
  │   └─ 有权限 → 继续
  │
  └─ 4. 执行请求

3.4 敏感操作保护

以下操作需要 工作区管理员 权限：

操作	端点	要求
删除 Agent	DELETE /agents/{id}	工作区管理员
删除工作流	DELETE /workflows/{id}	工作区管理员
删除数据源	DELETE /data-sources/{id}	工作区管理员
删除模型配置	DELETE /model-configs/{id}	工作区管理员
删除定时任务	DELETE /agent-schedules/{id}	工作区管理员
部署 Agent	POST /agents/{id}/deploy	工作区管理员
停止 Agent	POST /agents/{id}/stop	工作区管理员
发布工作流	POST /workflows/{id}/publish	工作区管理员
重载工具	POST /tools/reload	工作区管理员

---

四、平台管理员功能

仅 role=admin 的用户可访问以下功能。

4.1 用户管理

进入「运维管理 → 用户管理」：

用户列表

┌──────────────────────────────────────────────────────────────────┐
│ 搜索: [________]  状态: [全部▾]  角色: [全部▾]                    │
├──────┬──────────┬──────┬──────┬──────┬────────┬──────┬──────────┤
│ 用户名 │ 邮箱      │ 角色  │ 状态  │ 订阅  │ 工作区数 │ 创建  │ 操作    │
├──────┼──────────┼──────┼──────┼──────┼────────┼──────┼──────────┤
│ admin │admin@..  │ 管理员│ 启用  │ 免费  │ 2      │06-01 │编辑 重置 │
│ 张三  │zhang@.. │ 开发者│ 启用  │ 专业  │ 1      │06-15 │编辑 重置 │
│ 李四  │li@..    │ 观察者│ 停用  │ 免费  │ 0      │06-20 │编辑 重置 │
└──────┴──────────┴──────┴──────┴──────┴────────┴──────┴──────────┘

功能操作：

• 创建用户: 填写用户名、邮箱、密码（6 位以上）、角色
• 编辑用户: 修改用户名、邮箱、角色、手机号、状态、订阅等级
• 重置密码: 为用户设置新密码
• 禁用/删除: 软删除用户（设置 status=deleted），平台管理员不可被删除

4.2 工作区全局管理

平台管理员在工作区管理页面看到全局视图：

┌── 所有工作区（平台管理员视图）──────────────────────────────────────┐
│ 搜索: [________]  状态: [全部▾]                                    │
├──────────┬────────┬────────┬──────┬──────┬──────────┬────────────┤
│ 名称      │ 所有者  │ 成员数  │ 上限  │ 状态  │ 创建时间   │ 操作      │
├──────────┼────────┼────────┼──────┼──────┼──────────┼────────────┤
│ 研发团队  │ admin  │ 12     │ 50   │ 启用  │ 2026-06  │ [进入][管理]│
│ AI实验室  │ 张三   │ 3      │ 20   │ 停用  │ 2026-07  │ [进入][管理]│
└──────────┴────────┴────────┴──────┴──────┴──────────┴────────────┘

管理操作：

• 点击「管理」可编辑任意工作区的名称和状态
• 可强制删除任意工作区（包括默认工作区）
• 所有操作记录在审计日志中

4.3 审计日志

进入「系统日志 → 审计日志」查看所有管理员操作记录：

• 操作人、操作类型（CREATE/UPDATE/DELETE/LOGIN）
• 资源类型、IP 地址
• 操作时间、操作结果

---

五、API 使用指南

5.1 认证与工作区切换

# 1. 登录获取 Token
curl -X POST http://localhost:8037/api/v1/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=123456"

# 响应: { "access_token": "eyJ...", "token_type": "bearer" }

# 2. 查看当前用户信息（含工作区列表）
curl http://localhost:8037/api/v1/auth/me \
  -H "Authorization: Bearer $TOKEN"

# 响应包含:
# {
#   "id": "...", "username": "admin", "role": "admin",
#   "workspaces": [
#     {"id": "ws-1", "name": "研发团队", "role": "admin"},
#     {"id": "ws-2", "name": "个人空间", "role": "member"}
#   ],
#   "current_workspace_id": "ws-1"
# }

# 3. 切换工作区
curl -X POST http://localhost:8037/api/v1/auth/switch-workspace/ws-2 \
  -H "Authorization: Bearer $TOKEN"

# 响应包含新的 Token（携带新工作区 ID）

5.2 工作区管理 API

# 创建工作区
curl -X POST http://localhost:8037/api/v1/workspaces \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "新项目", "description": "项目协作空间", "max_members": 50}'

# 查看成员
curl http://localhost:8037/api/v1/workspaces/{ws_id}/members \
  -H "Authorization: Bearer $TOKEN"

# 添加成员
curl -X POST http://localhost:8037/api/v1/workspaces/{ws_id}/members \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "zhangsan", "role": "member"}'

# 修改成员角色
curl -X PUT http://localhost:8037/api/v1/workspaces/{ws_id}/members/{user_id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'

# 移除成员
curl -X DELETE http://localhost:8037/api/v1/workspaces/{ws_id}/members/{user_id} \
  -H "Authorization: Bearer $TOKEN"

5.3 管理员 API

# 用户列表（分页、搜索、过滤）
curl "http://localhost:8037/api/v1/admin/users?page=1&page_size=20&search=admin&role=admin" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# 创建用户
curl -X POST http://localhost:8037/api/v1/admin/users \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username":"newuser","email":"new@test.com","password":"123456","role":"developer"}'

# 编辑用户
curl -X PUT http://localhost:8037/api/v1/admin/users/{user_id} \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role":"viewer","status":"disabled"}'

# 重置密码
curl -X POST http://localhost:8037/api/v1/admin/users/{user_id}/reset-password \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"new_password":"newpass123"}'

# 删除用户（软删除）
curl -X DELETE http://localhost:8037/api/v1/admin/users/{user_id} \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# 查看所有工作区
curl "http://localhost:8037/api/v1/admin/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# 查看任意工作区详情
curl http://localhost:8037/api/v1/admin/workspaces/{ws_id} \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# 编辑任意工作区
curl -X PUT http://localhost:8037/api/v1/admin/workspaces/{ws_id} \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"disabled"}'

# 强制删除工作区
curl -X DELETE http://localhost:8037/api/v1/admin/workspaces/{ws_id} \
  -H "Authorization: Bearer $ADMIN_TOKEN"

5.4 WebSocket 连接

WebSocket 连接需要传递 Token 作为 query 参数：

// 执行状态实时推送
const ws = new WebSocket(
  `ws://localhost:8037/api/v1/ws/executions/${executionId}?token=${jwtToken}`
);

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // data.type: "status" | "progress" | "error" | "pong"
  console.log(data);
};

// 协作编辑
const collabWs = new WebSocket(
  `ws://localhost:8037/api/v1/collaboration/ws/workflows/${workflowId}?token=${jwtToken}`
);

// 发送操作
collabWs.send(JSON.stringify({
  type: "operation",
  operation: {
    type: "node_add",
    node: { id: "...", type: "llm", position: { x: 100, y: 200 } }
  }
}));

WebSocket 认证验证：

• JWT Token 有效性
• 用户存在且未被删除
• 工作区成员资格
• 资源归属当前工作区

5.5 错误码说明

HTTP 状态码	WebSocket 关闭码	说明
401	4001	Token 无效或已过期
403	4003	无权访问（非工作区成员 / 无所需权限）
403	4008	违反策略（如缺少 Token）

---

六、数据隔离详解

6.1 已隔离的资源

以下资源通过 workspace_id 字段实现完全隔离：

资源	表	隔离方式
Agent	agents	查询时自动按 workspace_id 过滤
工作流	workflows	查询时自动按 workspace_id 过滤
执行记录	executions	查询时自动按 workspace_id 过滤
数据源	data_sources	查询时自动按 workspace_id 过滤
模型配置	model_configs	查询时自动按 workspace_id 过滤
定时任务	agent_schedules	查询时自动按 workspace_id 过滤
知识库	knowledge_bases	查询时自动按 workspace_id 过滤
聊天消息	chat_messages	查询时自动按 workspace_id 过滤
Agent 会话	agent_sessions	查询时自动按 workspace_id 过滤
告警规则	alert_rules	查询时自动按 workspace_id 过滤
节点模板	node_templates	查询时自动按 workspace_id 过滤
插件	plugins	查询时自动按 workspace_id 过滤
目标/任务	goals / tasks	查询时自动按 workspace_id 过滤
编排模板	orchestration_templates	查询时自动按 workspace_id 过滤
场景契约	scene_contracts	查询时自动按 workspace_id 过滤
团队	teams	查询时自动按 workspace_id 过滤
对话分支	conversation_branches	查询时自动按 workspace_id 过滤
LLM 日志	agent_llm_logs	查询时自动按 workspace_id 过滤
知识条目	knowledge_entries	查询时自动按 workspace_id 过滤
告警日志	alert_logs	查询时自动按 workspace_id 过滤

6.2 创建时自动标记

所有新建资源自动 stamp 当前工作区 ID，确保数据归属正确：

# 后端自动处理（以 Agent 为例）
agent = Agent(
    ...
    user_id=current_user.id,
    workspace_id=workspace_id,  # 从 JWT ws 字段自动提取
)

---

七、常见场景

7.1 企业新员工入职

1. 管理员创建用户账号 — 进入「用户管理」→ 创建用户，设置角色为 developer
2. 将用户加入工作区 — 进入目标工作区「成员管理」→ 添加成员
3. 用户登录 — 使用分配的账号密码登录
4. 用户切换工作区 — 在工作区列表选择目标工作区进入
5. 开始工作 — 创建 Agent、工作流等

7.2 创建新团队协作空间

1. 创建工作区 — 点击「创建工作区」，命名为"XX 项目"
2. 添加团队成员 — 逐个添加成员账号
3. 设置成员角色 — 核心成员设为 admin（可管理成员），普通成员设为 member
4. 团队开始协作 — 所有成员在该工作区中创建的 Agent、工作流自动共享

7.3 权限审查

1. 平台管理员进入「用户管理」查看所有用户及其角色
2. 检查是否有用户拥有不当权限（如普通用户被设为 admin）
3. 通过「编辑用户」调整角色
4. 停用离职员工的账号（设置 status=disabled）

7.4 审计追溯

1. 进入「系统日志 → 审计日志」
2. 按时间、用户、操作类型筛选
3. 查看关键操作：用户创建/删除、权限变更、工作区删除等
4. 所有敏感操作有完整审计轨迹

---

八、安全注意事项

8.1 密码安全

• 默认管理员密码 123456 应在首次部署后立即修改
• 通过个人设置或管理员强制重置修改密码
• 密码至少 6 位，建议使用强密码策略

8.2 权限最小化

• 给用户分配其工作需要的最低权限角色
• 默认使用 developer 角色，而非 admin
• 定期审查工作区成员列表，移除不再需要访问的用户

8.3 工作区删除

• 删除工作区是软删除（status=deleted），数据不会物理删除
• 需要彻底清理数据请联系平台管理员
• 默认工作区建议保留不删除

8.4 Token 安全

• JWT Token 包含工作区上下文，请妥善保管
• Token 过期后需重新登录
• WebSocket 连接的 Token 通过 query 参数传递，注意日志中不要泄露

---

附录 A: 角色权限矩阵速查

操作	platform admin	workspace admin	developer	viewer	operator
查看所有工作区	✅	❌	❌	❌	❌
管理所有工作区	✅	❌	❌	❌	❌
管理所有用户	✅	❌	❌	❌	❌
管理本工作区成员	✅	✅	❌	❌	❌
修改工作区设置	✅	✅	❌	❌	❌
创建 Agent/工作流	✅	✅	✅	❌	❌
编辑自己的资源	✅	✅	✅	❌	❌
删除自己的资源	✅	✅	✅	❌	❌
编辑他人的资源	✅	✅	❌	❌	❌
删除他人的资源	✅	✅	❌	❌	❌
部署/停止 Agent	✅	✅	✅	❌	✅
执行工作流	✅	✅	✅	❌	✅
查看资源	✅	✅	✅	✅	✅
查看执行记录	✅	✅	✅	✅	✅
查看审计日志	✅	❌	❌	❌	❌

附录 B: 数据库表 workspace_id 标记

所有支持多租户隔离的数据表均包含 workspace_id 列：

agents                  agent_schedules         alert_rules
alert_logs              agent_execution_logs    agent_llm_logs
agent_sessions          chat_messages           conversation_branches
data_sources            executions              goals
knowledge_bases         knowledge_entries       model_configs
node_templates          plugins                 scene_contracts
orchestration_templates tasks                   teams
templates               workflows               tools

附录 C: 技术架构要点

• 后端框架: FastAPI + SQLAlchemy ORM
• 认证: JWT (python-jose) + bcrypt 密码哈希
• 依赖注入: FastAPI Depends() 链式调用实现认证→授权→执行
• 数据隔离: 所有查询通过 SQLAlchemy filter(workspace_id=...) 实现
• WebSocket: 连接注册表按 workspace_id 标记，防止跨工作区消息泄露
• 平台管理员绕过: user.role == "admin" 跳过所有 workspace 成员资格检查

---

最后更新：2026-07-04 | 适用版本 v1.2+