多租户与工作区隔离
本文属于“当前架构”文档,描述已经生效的多租户实现与隔离边界。 尚未覆盖的部分在文末单列,不要把它当成“多租户已完成”来读。
为什么需要
改造前,/api/v1 只区分“已登录 / 未登录”。任何登录账号都能:
列出全部项目、按 ID 读取任意镜头、上传与下载任意素材、看到全公司的生成任务。
对一个内部 MCN 制作团队,这意味着实习生账号与项目负责人看到的是同一份数据。 引入工作区是为了给“数据属于谁”一个可判定的边界,而不是只加一个 UI 概念。
数据模型
workspaces (id, name, slug, owner_id, is_active)
└── workspace_members (workspace_id, user_id, role, is_active) -- (ws, user) 唯一
└── projects (workspace_id NOT NULL, created_by)
└── chapters
└── shots
└── shot_details / shot_dialog_lines / shot_frame_images
└── characters / scenes / props / costumes (经 project_*_links 关联)关键取舍:
只有 projects 加 workspace_id,其余 53 张表不动。
章节、镜头、资产都通过项目间接归属,鉴权时只需校验一次项目归属就能覆盖其下全部资源;
若给每张表都加列,等于把同一个条件在几十处查询里重复一遍,漏一处就是一次泄露。
角色放在成员表里,不建 roles / permissions 两张表。
当前团队是“个位数成员、权限只有能否改内容这一层”,完整 RBAC 会让每次鉴权多两次 join,
收益不足。等出现“按项目授权”的真实需求再升级,WorkspaceRole 枚举可平滑映射为初始数据。
成员退出置 is_active=false,不删行。
否则历史操作记录里的 user_id 会变成悬空引用。
workspaces.owner_id 用 ON DELETE RESTRICT。
工作区是有价值的业务容器,不允许因为误删账号而连带删除全部项目。
角色矩阵
| 角色 | 等级 | 读 | 写(增删改 / 触发生成) | 管理成员 |
|---|---|---|---|---|
viewer | 1 | ✅ | ❌ | ❌ |
editor | 2 | ✅ | ✅ | ❌ |
admin | 3 | ✅ | ✅ | ✅(预留) |
owner | 4 | ✅ | ✅ | ✅ |
viewer 只读的设计意图:外部审片 / 甲方预览账号不应能触发模型生成,
因为生成会真实消耗供应商额度。
注册账号如何加入工作区
邀请码 + 邮箱注册成功后,账号会在同一个事务里加入工作区
(实现见 app/services/auth_registration.py::_attach_default_workspace):
- 优先加入启用中的
ws-default; ws-default不存在或已停用时,加入最早创建的启用工作区;- 系统里一个工作区都没有时,创建
ws-default,注册者为owner。
加入既有工作区的角色固定为 editor(可读写内容,不能管理成员);
ws-default 被停用且没有其他可用工作区时注册返回 503,不会擅自重新启用工作区。
这解决了“注册成功但登录后提示未加入任何工作区”的断点。 Google 登录创建的账号不经过邀请码注册流程,仍按原有逻辑处理。
请求上下文
工作区经 X-Workspace-ID 请求头传递,不塞进 URL:
- 不必给 119 个路径批量加路径参数,前端只需设一个全局头;
- 与“项目归属哪个工作区”解耦,同一项目 ID 不会被拼进另一个租户的 URL。
解析优先级(app/dependencies.py::get_workspace_context):
X-Workspace-ID请求头;- 路径参数
workspace_id(为将来 REST 风格路由预留); - 都没有时,取该用户加入的第一个工作区。
第 3 条是刻意保留的兼容路径:当前全部存量用户只属于一个工作区, 因此前端不改一行也能正常工作。等前端真正支持切换工作区时再依赖请求头。
失败语义:越权一律 404
访问自己不是成员的工作区、或读取别的工作区的资源,统一返回:
{ "code": 404, "message": "工作区不存在", "data": null, "meta": null }不返回 403。 403 等于告诉调用方“这个 ID 是真的,只是你没权限”, 把其他租户的资源 ID 变成可枚举的探测面。
例外:用户一个工作区都没加入时返回 403(当前账号未加入任何工作区)。
这不是资源不存在,而是账号没被分配,需要明确提示而不是给一个空列表
——空列表会被误读为“项目都删了”。
隔离实现
app/api/scoping.py 是唯一的归属校验入口,路由不再直接 db.get(Project, id)。
核心机制是 router 级守卫:
router = APIRouter(dependencies=[
Depends(require_scoped_resource("shot_id", get_shot_in_workspace)),
])为什么挂 router 而不是逐个端点:shots 有 23 个端点、entities 有 11 个,
逐个加依赖时漏一个就是一个越权口子,而且新增端点极易忘记补。
router 级守卫让新端点默认受保护。
守卫行为:
- 路径里没有该参数(列表接口、
/runtime-summary)→ 跳过归属校验, 列表自身的工作区过滤由 service 的workspace_id参数负责; - 有该参数 → 校验归属,不通过抛 404;
- 写方法(
POST/PUT/PATCH/DELETE)额外要求 editor 及以上。
归属链的两类资产(容易搞错)
| 资产 | 归属方式 |
|---|---|
characters | 项目内资产,自身直接持有 project_id |
scenes / props / costumes / actors | 全局资产,可跨项目复用,自身没有 project_id,归属经 project_{scene,prop,costume,actor}_links 确定 |
对全局资产采用「任一关联项目属于当前工作区即放行」的语义: 同一场景被两个工作区的项目引用时,两个工作区都能看到它,但都改不到对方的关联。
隔离覆盖范围
已隔离(全部业务路由)
| 路由 | 方式 |
|---|---|
studio/projects | 项目级 + apply_workspace_filter |
studio/chapters | 经 project join |
studio/shots(含 5 个子 router) | router 级守卫 |
studio/entities | router 级守卫(含资产两类归属链) |
studio/image-tasks | router 级守卫(actor/character/asset/project/shot) |
studio/timeline | router 级守卫(project) |
studio/files | 守卫经 EXISTS(file_usages ⋈ projects) |
film/task_status | 守卫用 generation_tasks.workspace_id |
studio/audio-tasks | 业务 ID 在请求体,端点内显式解析比对 |
studio/shot-character-links | shot_id 走 query,端点内显式校验 |
为什么 files 不新增归属列
files 表没有 project_id:一个文件可被多个项目复用(演员定妆照、公共 BGM),
归属唯一可靠的记录在 file_usages.project_id。因此判定语义是
任一条使用记录指向当前工作区的项目即放行。
不新增 files.workspace_id 的原因:上传时往往还不知道会挂到哪个项目,
加列会引入「先建后补」的时序漏洞(先落一条 NULL 归属,再靠后续写入补齐,
中间窗口对该文件没有归属约束)。代价是未被任何项目引用的孤儿文件对所有租户不可见
—— 孤儿文件本就不该被业务读取,可接受。
为什么 generation_tasks 必须独立持有 workspace_id
不能像章节/镜头那样经 project 归属:
- 一次任务可能产出多个资源、跨多个项目(批量资产图),没有唯一父 project;
- 任务关联走
generation_task_links的多态字段 (resource_type+relation_type+relation_entity_id), 反查要先解析类型才知道去查哪张表,无法用于鉴权; - 任务状态/取消是高频只读接口,鉴权路径必须是一次主键查询。
列定义为 NOT NULL 且无默认值:漏传直接报错,避免产生「所有租户都能看到」的匿名任务。
归属由 app/services/common/workspace.py::resolve_workspace_id 统一回溯,
调用方无需感知租户概念。
迁移注意事项
022 必须幂等
compose 的启动顺序是 init_db(SQLAlchemy create_all)→ mysql-init-sql
(按文件名排序 apply 全部 SQL)。在全新库上 create_all 已按 models 建好新表,
脚本硬写 CREATE TABLE 会直接撞车让整条 compose 起不来;存量库则需要脚本补列。
两种场景都要跑通,所以:建表用 IF NOT EXISTS,加列/索引查 information_schema,
回填用 INSERT IGNORE。
字符集必须先对齐
生产库的存量表是 utf8mb4_unicode_ci,而 MySQL 8/9 的建库默认是
utf8mb4_0900_ai_ci。新表若用默认 collation,
projects.workspace_id → workspaces.id 的外键会直接失败:
ERROR 3780 (HY000): Referencing column 'workspace_id' and referenced column 'id'
in foreign key constraint 'fk_projects_workspace' are incompatible022 因此把 collation 修正放在所有 CREATE 之前。
原因:CREATE TABLE IF NOT EXISTS 遇到已存在的表时,MySQL 仍会校验外键列兼容性,
此时若引用表 collation 未对齐,一样报 3780。
存量数据回填策略
在这台生产库上执行 022 的实际结果:
| 项 | 结果 |
|---|---|
| 默认工作区 | ws-default(owner 取最早创建的账号) |
| 成员 | 2 人全部加入:最早账号为 owner,其余为 editor |
| 项目 | 2 个项目全部挂到 ws-default |
| 外键 | 5 条全部建立(projects×2、workspace_members×2、workspaces×1) |
回填原则是宁可多给权限,也不能让存量用户登录后发现自己的项目全没了。
因此既有用户一律先给 editor(而非 viewer),后续按需下调。
验证方式
# 契约与测试
cd backend && uv run pytest -q
cd front && pnpm run typecheck
# 线上冒烟(token 由 JWT_SECRET 签发)
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/health # 200
curl -s -o /dev/null -w '%{http_code}\n' \
-H "Authorization: Bearer $TOKEN" http://127.0.0.1:8000/api/v1/studio/projects # 200
curl -s -o /dev/null -w '%{http_code}\n' \
-H "Authorization: Bearer $TOKEN" -H "X-Workspace-ID: ws-nope" \
http://127.0.0.1:8000/api/v1/studio/projects # 404
curl -s -o /dev/null -w '%{http_code}\n' \
http://127.0.0.1:8000/api/v1/studio/projects # 401