6.4 商业化 SaaS 基石:多租户架构与权限控制 (RBAC)
本节目标:把当前“单机 Demo / 无账号体系”的项目,演进为可商业化的 SaaS:支持用户登录、工作空间(Workspace)隔离、角色权限(RBAC)、以及后端的强制数据隔离(Tenant Isolation)。这一节不追求把所有细节一次做完,而是给出从最小可用到可扩展的完整落地路线。
先明确现状:ai-data-analyzer 当前前端(Next.js + React 19)并未集成 NextAuth/Auth.js,后端(NestJS)也未引入 JWT/Passport 等鉴权依赖。这是正常的:Demo 阶段不需要。但要商业化,6.4 这一步必须补齐。
6.4.1 你到底需要什么样的多租户:三种模型与推荐
多租户隔离大致有三种形态:
- 数据库级隔离(每租户一个库):隔离最强,运维成本高
- Schema 级隔离(每租户一个 schema):隔离强,仍有一定运维复杂度
- 行级隔离(同库同表,按 workspace_id 区分):工程最顺滑,最适合快速演进
本项目建议选择 行级隔离 作为第一阶段(最贴近当前 TypeORM 单库模型),并为未来升级保留扩展点(例如支持 Postgres RLS)。
6.4.2 账户体系与登录:前端与后端如何配合
商业化项目一般需要支持:
- Email/Password 或 OAuth 登录(GitHub/Google)
- Session 管理(浏览器端保持登录态)
- API 调用鉴权(后端知道“你是谁”与“属于哪个 workspace”)
推荐方案 A:前端 NextAuth/Auth.js + 后端 JWT(最常见)
思路:
- Next.js 负责登录与 Session(cookies)
- 前端调用后端 API 时附带 access token(或用 session cookie)
- NestJS 校验 token,解析出
userId与workspaceId
优点:生态成熟、控制力强。
代价:需要引入依赖并补齐一套 token 生命周期(刷新/过期/撤销)。
推荐方案 B:使用 Clerk / Supabase Auth
优点:上手更快,后台能力齐全(邮件、OAuth、组织、多因素)。
代价:供应商绑定更强。
结论:教程里可以先写 A(更通用),同时在“扩展阅读”给出 B 的替代路线。
6.4.3 数据模型升级:User / Workspace / Membership / Role
如果只有 User,没有 Workspace,那么所有数据天然“混在一起”。真正的 SaaS 必须引入 Workspace(工作空间)来承载“一个团队/一个项目/一个组织”的数据边界。
建议的最小模型:
A. User
idemail(唯一)namepassword_hash(如果做自建账号)created_at
B. Workspace
idnameowner_user_idcreated_at
C. Membership(用户与空间的关系表)
iduser_idworkspace_idrole:owner | admin | member | viewercreated_at
为什么要用 Membership 而不是在 User 上直接放 workspaceId?
- 用户可以属于多个 workspace(个人空间 + 公司空间)
- RBAC 权限天然是“在某个 workspace 下的角色”
D. 把现有业务数据挂到 workspace 上
从 6.1~6.3 的能力延续下来,你至少要把这些对象加上 workspace_id:
- uploaded datasets(数据集)
- analysis runs / results(分析运行与结果)
- vector chunks(知识库切片)
- artifacts(图表/表格等产物)
这一步是“隔离”的根基。
6.4.4 RBAC 权限设计:先做“够用”,再做“细粒度”
RBAC 的重点是:用最少的角色解决最多的权限需求。
建议先从 4 个角色起步:
- owner:拥有者(计费、删除空间、管理成员)
- admin:管理员(管理成员、配置集成)
- member:普通成员(上传数据、发起分析、查看团队内容)
- viewer:只读(看报告与图表,不允许上传/分析)
权限粒度第一版不要过细,先覆盖核心 API:
- dataset:create/read/delete
- analysis:create/read/cancel
- billing:read/manage(仅 owner)
- members:invite/remove(owner/admin)
当业务增长后,再引入“权限点(permission)+ 角色绑定”的细粒度体系。
6.4.5 后端强制隔离:Tenant Isolation 的三层防线
多租户系统最常见的事故是“越权读到别人数据”。要避免它,推荐三层防线同时上:
防线 1:API 层 Guard(身份认证)
目标:未登录不能访问敏感 API,并在 request context 中解析出 userId。
实现策略(NestJS):
AuthGuard:校验 token/session,注入 user
防线 2:Workspace Guard(租户边界)
目标:即使是已登录用户,也必须属于 workspace 才能访问其资源。
实现策略:
- 前端显式选择 workspace(或默认 personal workspace)
- 请求携带
workspaceId(header 或 path param) WorkspaceGuard校验 membership,并把workspaceId写入 request context
防线 3:数据访问层过滤(硬约束)
目标:所有数据库查询必须自动带上 workspace_id = currentWorkspaceId。
常见实现方式:
- Repository/Service 层统一封装:提供
scopedRepo(workspaceId)或where({ workspaceId })的统一 helper - TypeORM QueryBuilder 统一注入过滤条件(对复杂查询更适用)
加分项(进阶):Postgres RLS(Row-Level Security)
- 优点:就算应用层写漏了 where 条件,数据库也会拒绝越权访问
- 代价:需要更复杂的 DB 会话管理与策略维护
教程建议:先实现“应用层硬过滤”,再以专题形式介绍 RLS。
6.4.6 前端交互设计:让多租户真正“可用”
多租户不是后端加个字段就结束了,前端必须提供“可理解”的工作流:
Step 1:Workspace 选择器
- 顶部导航或侧边栏提供 workspace 切换
- 初次注册自动创建 personal workspace
Step 2:成员管理界面(最小版)
- 列表:成员、角色
- 操作:邀请(发邮件或生成邀请链接)、移除、改角色
Step 3:资源列表按 workspace 展示
- 数据集列表
- 报告/分析结果列表
- 图表模板(如果你做了 6.3 的图表级 RAG)
这一步会让用户清晰理解“我的数据属于哪个团队/空间”。
6.4.7 与 6.1~6.3 的衔接:多租户如何影响多智能体与知识库
你在 6.1 做的多智能体编排、6.2 的执行器、6.3 的向量库,都必须引入 workspace 维度:
- 多智能体上下文 key:
analysis:{workspaceId}:{analysisId}:context - artifacts 存储 key:
artifact:{workspaceId}:{analysisId}:{name} - 向量检索必须过滤 workspace,否则召回会跨租户泄露
这是一个非常值得在教程里强调的“工程细节”,因为它决定系统能否真正上线。
6.4.8 验收标准:做到这一步,你就拥有 SaaS 的基本盘
- 支持用户登录/登出,并能保持会话
- 支持 workspace(至少 personal workspace)并能切换
- 所有数据对象(datasets / analysis results / chunks / artifacts)带
workspace_id - 后端在 API 与数据访问层强制租户隔离,越权访问被拒绝
- RBAC 生效:viewer 无法上传/分析,owner 才能管理计费与成员
