Wiki Notes

Appearance

多租户架构专题 ​

版本：v1.3

最后更新：2026-07-09

适用对象：需要为企业 AI 平台、知识库、Agent、工具网关和 SaaS 型 AI 产品设计租户隔离、权限边界、成本追踪、审计留痕与运维控制的产品、架构、平台与安全同学

只要 AI 系统开始同时服务多个团队、多个客户或多个业务线，多租户问题就会迅速浮出水面。

常见风险不是模型能力不够，而是：

  • 一个租户的数据被另一个租户召回了
  • 同一个向量库里混进了不同租户内容
  • 会话状态和缓存没有租户边界
  • 工具调用没有 tenant scope
  • trace、日志和报表本身就泄露了跨租户信息
  • 成本和配额无法按租户追踪

根据当前可访问的 Pinecone Implement multitenancy / Data modeling / Limits、Weaviate Multi-tenancy / RBAC / Tenant activity logs、OpenAI Your data / File search / Production best practices 等官方资料，可以先建立一个非常关键的共识：

  • 多租户不是在每条记录上加一个 tenant_id 就结束了，而是要把隔离边界同时落到数据、检索、工具、会话、缓存、日志、成本和运维控制里。

1. 什么是多租户 ​

多租户不只是“有很多用户”，而是：

  • 多组用户共享同一套系统
  • 但数据、权限、策略、成本或审计边界必须独立

在 AI 系统里，多租户问题通常比传统 SaaS 更复杂，因为隔离不只发生在数据库层，还发生在：

  • 检索层
  • 工具层
  • 会话层
  • 缓存层
  • tracing 与 audit 层
  • 模型调用与文件上下文层

1.1 为什么 AI 多租户更容易出问题 ​

因为很多隐性状态并不直观可见，例如：

  • 检索召回范围
  • 拼给模型的上下文
  • 中间 Agent 状态
  • 工具返回缓存
  • 文件搜索索引
  • 结果回放和评测样本

这些地方只要少一个 tenant scope，就可能出现跨租户泄漏。

1.2 AI 多租户不是只有“读隔离”，还有“动作隔离” ​

传统 SaaS 很多时候隔离重点在：

  • 谁能看到什么数据

AI 系统还必须额外回答：

  • 谁能调用什么工具
  • 谁能触发什么写操作
  • 谁能上传什么文档
  • 谁能消费什么 quota
  • 谁能看到什么 trace、样例和评测结果

所以多租户在 AI 里，往往同时覆盖：

  • 读边界
  • 写边界
  • 运行边界
  • 观测边界

2. AI 多租户最容易在哪些地方失控 ​

2.1 检索召回范围过宽 ​

这是最常见的场景之一。

例如：

  • 没有带 tenant filter
  • namespace 打错了
  • metadata 过滤表达式漏字段
  • query rewrite 丢掉租户边界

2.2 会话与缓存没有租户边界 ​

例如：

  • 共享缓存 key 不带 tenant 信息
  • 历史消息在租户切换后仍被复用
  • 多轮摘要没有显式 tenant scope

2.3 工具层没有 tenant-aware 设计 ​

例如：

  • 查订单工具默认查全局
  • 导出工具没要求传 tenant scope
  • Agent handoff 丢掉了租户上下文
  • 审批恢复后上下文跑到了别的租户空间

2.4 观测与日志本身泄露租户信息 ​

例如：

  • trace 面板能看到其他租户数据
  • audit 报表没有访问边界
  • 错误样例库把跨租户文本混在一起

2.5 成本和配额没有隔离 ​

例如：

  • 一个大客户把全局模型配额吃满
  • 离线补算挤占在线租户请求
  • 账单只能看到总额，无法做租户归因

所以多租户问题从来不只是存储问题。

3. 多租户架构至少要隔离哪些东西 ​

建议至少明确下面六层隔离对象。

3.1 数据隔离 ​

包括：

  • 文档
  • 向量记录
  • 元数据
  • 文件和附件
  • 对话历史
  • 结构化业务数据

3.2 权限隔离 ​

包括：

  • 用户身份
  • 租户身份
  • 角色与部门
  • 工具可用范围
  • 审批范围

3.3 运行隔离 ​

包括：

  • 并发
  • 限流
  • 队列
  • 配额
  • 降级策略
  • lane 资格

3.4 观测隔离 ​

包括：

  • trace
  • audit log
  • 错误样例
  • 报警视图
  • 回放数据

3.5 成本隔离 ​

包括：

  • token 成本
  • 存储成本
  • 检索成本
  • 工具调用成本
  • 后台任务成本

3.6 运维隔离 ​

包括：

  • 变更审批范围
  • 恢复与回滚对象
  • tenant 级开关
  • tenant 级熔断与隔离

4. 常见的多租户实现方式 ​

4.1 逻辑隔离 ​

逻辑隔离的典型做法是：

  • 多租户共享同一套基础设施
  • 通过 tenant 字段、权限和过滤规则做区分

优点通常是：

  • 资源利用率高
  • 运维成本低

缺点通常是：

  • 边界更依赖实现细节
  • 任何一个过滤缺失都可能出事故

4.2 资源级隔离 ​

资源级隔离更接近：

  • 不同租户或租户组有独立的 collection、namespace、索引、队列或存储边界

优点通常是：

  • 边界更硬
  • 风险更低

缺点通常是：

  • 资源成本更高
  • 运维复杂度更高

4.3 混合隔离 ​

企业里很常见的最终形态其实是混合隔离：

  • 高敏租户或大客户使用更硬边界
  • 普通租户共享基础设施，但严格控制过滤、权限和观测边界

这种方式更现实，因为它允许你按：

  • 风险
  • 合规
  • 规模
  • 预算

来决定隔离强度。

5. 不同隔离强度更像“分层治理”，不是非黑即白 ​

一个更实用的多租户心智模型是把隔离强度分成几层：

  1. 共享基础设施 + 逻辑过滤
  2. 共享基础设施 + namespace / collection 分层
  3. 租户级资源隔离
  4. 区域 / 合规级物理隔离

这比简单问“是不是独立库”更有工程意义。

5.1 小租户不一定需要最硬隔离 ​

如果：

  • 数据敏感性不高
  • 成本压力大
  • 租户规模小

逻辑隔离可能是合理的起点。

5.2 高敏租户通常需要更硬边界 ​

如果：

  • 合规要求高
  • 法务要求强
  • 审计要求严
  • 风险承受能力低

更硬的 namespace、collection、索引乃至区域边界通常更合适。

6. Retrieval 场景里的多租户设计 ​

AI 多租户里最危险的泄漏路径之一，往往发生在检索层。

6.1 更稳妥的检索隔离顺序 ​

一个更稳的顺序通常是：

  1. 先确定租户边界
  2. 再在租户内做文档、部门、区域或权限过滤
  3. 最后才做排序和 rerank

不要把租户边界留到生成层再兜。

6.2 为什么 tenant scope 不能只靠 prompt ​

如果只是告诉模型：

  • “只回答本租户内容”

但检索层已经把别的租户内容召回了，那么风险已经发生。

Prompt 可以帮助模型更守规则，但不能替代：

  • 检索边界
  • namespace
  • metadata filter
  • 权限检查

6.3 高敏租户更适合更硬的边界 ​

在高敏场景里，更合理的设计通常是：

  • 先在存储或检索空间上做硬隔离
  • 再在租户内做更细粒度过滤

这样即便上层逻辑有 bug，破坏面也更小。

7. 为什么 namespace 和 metadata filter 不能混为一谈 ​

很多团队会把它们都理解成：

  • “反正都能筛数据”

这会埋下很大隐患。

7.1 namespace 更像第一层硬隔离 ​

namespace 的价值更接近：

  • 先把检索面切开

它适合：

  • tenant 间先做大边界隔离
  • 高敏数据先物理或半物理分开

7.2 metadata filter 更像租户内细粒度约束 ​

metadata filter 更适合处理：

  • 租户内部门权限
  • 文档类型
  • 业务线
  • 区域
  • 时间范围

7.3 把所有租户都塞进一个大 namespace 的代价 ​

最常见的代价包括：

  • 一次 filter 缺失就串租
  • 性能受大租户拖累
  • 排查复杂
  • 召回质量抖动更明显

这也是为什么很多官方文档都在多租户场景强调：

  • 先做作用域边界，再做细过滤

8. Pinecone、Weaviate 这类官方多租户文档最值得记住的工程结论 ​

8.1 Pinecone 的启发 ​

Pinecone 当前多租户和 data modeling 文档最值得借鉴的点通常是：

  • records 设计里 tenant scope 不是可有可无字段
  • namespace 与 metadata 都是治理手段
  • limits 与扩容边界要提前考虑

真正的工程启发是：

  • 不要等租户规模上来后再补 tenant 设计

8.2 Weaviate 的启发 ​

Weaviate 当前 multi-tenancy、RBAC、tenant activity logs 文档更强调：

  • collection / tenant 活动边界
  • 角色权限控制
  • 审计与活动日志

真正值得学的是：

  • 多租户不是只有“查得对”，还要“看得见谁做了什么”

9. 工具、会话状态和 handoff 也必须租户感知 ​

9.1 工具必须知道当前 tenant ​

工具 contract 里最好显式包含：

  • tenant_id
  • org_id
  • scope
  • actor

而不是隐式依赖：

  • 当前 session 猜测

9.2 会话状态必须显式带 tenant scope ​

任何会被持久化或复用的状态对象，最好都显式带：

  • tenant_id
  • conversation_id
  • workspace_id

9.3 Agent handoff 也要保留租户边界 ​

Agent 之间交接时，除了任务描述，还要保留：

  • tenant scope
  • allowed tools
  • 权限级别
  • 数据访问边界

9.4 缓存 key 也必须是多租户安全的 ​

一个最常见事故根因就是：

  • cache key 只按 query 文本算

正确做法通常至少要带：

  • tenant_id
  • route
  • permission scope
  • data version

10. 文件、向量库和外部知识接入也要算多租户边界 ​

OpenAI Your data 和 File search 文档给我们的核心提醒是：

  • 文件、索引和检索上下文本身也是数据边界对象

也就是说，你不应该只看：

  • 应用数据库有没有 tenant_id

还要看：

  • 文件上传是否分 tenant
  • 文件索引是否分 tenant
  • file search 或知识检索时是否能只访问允许范围

如果这些边界没设计好，很容易出现：

  • 文件库串租
  • 检索库串租
  • 结果回放串租

11. 配额与成本追踪为什么也属于多租户问题 ​

11.1 如果不做成本隔离，会带来什么问题 ​

最常见的问题包括：

  • 大租户吃满全局额度
  • 低价值租户挤掉高价值租户
  • 出了成本问题找不到责任归属

11.2 成本隔离还能帮助做风险治理 ​

一旦你能按租户统计：

  • token 成本
  • 检索成本
  • 工具调用成本
  • 后台任务成本

你就能做：

  • tenant 级预算
  • tenant 级降级
  • tenant 级优先级治理

11.3 quota 和 lane 资格最好一起治理 ​

对企业系统来说，更成熟的设计通常不是只限流，而是同时定义：

  • 谁能走 priority lane
  • 谁能跑 batch
  • 谁能触发重型工具
  • 谁能上传大规模文档

12. 观测与审计也要按租户隔离 ​

12.1 trace 面板必须有租户边界 ​

如果 trace 面板没有 tenant 级权限控制，往往会直接把：

  • 输入
  • 检索证据
  • 工具结果
  • 输出内容

暴露给不该看的人。

12.2 租户活动日志很适合做审计与排查 ​

这类日志至少应该能回答：

  • 谁在什么时间访问了什么租户空间
  • 上传了什么文件
  • 调用了什么工具
  • 触发了什么审批或导出

12.3 告警最好也带 tenant 标签 ​

否则你很难判断：

  • 是系统性问题
  • 还是某个租户自己的数据或行为导致

13. 多租户系统怎么测试 ​

13.1 串租召回测试 ​

验证：

  • 租户 A 的 query 不会命中租户 B 的文档

13.2 工具越界测试 ​

验证：

  • 只要 tenant scope 错误，工具是否会被拒绝

13.3 会话污染测试 ​

验证：

  • 租户切换后旧状态是否被彻底隔离

13.4 缓存安全测试 ​

验证：

  • 同 query 在不同租户不会误命中共享缓存

13.5 观测隔离测试 ​

验证：

  • trace、log、sample、dashboard 是否严格按租户可见

13.6 配额与限流测试 ​

验证：

  • 某租户打满是否只影响自己

13.7 变更与恢复测试 ​

验证：

  • tenant 级回滚、暂停、恢复是否真的只作用于目标租户

14. 更适合企业的最小多租户方案 ​

一个很实用的最小方案通常包括：

  1. 检索空间先按 tenant 分边界
  2. 租户内再用 metadata 控部门、区域、文档类型
  3. 工具调用必须显式 tenant-aware
  4. 会话与缓存对象必须带 tenant scope
  5. trace、audit、样例与报表按 tenant 授权
  6. 配额、预算、lane 资格按 tenant 记录

这套方案未必最豪华，但已经能覆盖最关键的风险面。

15. 多租户、权限和治理的边界怎么分 ​

15.1 多租户架构 ​

核心问题是：

  • 数据和运行边界怎么隔离

15.2 权限模型 ​

核心问题是：

  • 同一租户内谁能看什么、做什么

15.3 AI 治理 ​

核心问题是：

  • 哪些任务允许自动执行
  • 哪些必须审批
  • 哪些要留痕与评测

三者相关，但不等价。

不要把“有 tenant_id”误当成：

  • 权限做完了
  • 治理也做完了

16. 常见反模式 ​

16.1 只在 UI 层区分租户 ​

这会导致：

  • 后端和检索层仍可能串租

16.2 检索层没有 tenant filter 或 namespace 边界 ​

这是最常见、也最危险的反模式之一。

16.3 工具没有 tenant-aware 设计 ​

哪怕检索做对了，工具层仍可能越权。

16.4 会话和缓存没有按租户分区 ​

这会产生最隐蔽、最难复现的串租问题。

16.5 只做数据隔离，不做观测与成本隔离 ​

这样出了问题后，你既难排查，也难治理。

16.6 把所有租户共享在同一恢复与回滚平面 ​

这会让：

  • 一个租户的故障处理动作影响其他租户

16.7 只做逻辑隔离，不定义何时升级到更硬边界 ​

这会让系统在规模和风险上来后毫无演进路线。

17. 推荐搭配阅读 ​

18. 重点官方资源 ​

19. 落地检查清单 ​

  1. 检索、文件、会话、缓存、工具、trace 是否全部有 tenant scope。
  2. tenant 边界是否优先在检索层和存储层落地，而不是只靠 prompt。
  3. namespace、collection、metadata filter 的分工是否明确。
  4. 缓存 key、回放样例、评测样本是否包含 tenant 维度。
  5. quota、lane、预算和 tenant 级降级策略是否明确。
  6. tenant 级暂停、恢复、回滚和告警机制是否可执行。

20. 一句话总结 ​

AI 系统里的多租户不是“加一个 tenant_id”这么简单，而是：

  • 把租户边界同时落在检索、工具、会话、缓存、观测、成本和运维控制上的一整套隔离与治理工程