multi-tenancy

多租户

应将租户身份视为授权边界，而非查询便利项。

选择隔离模型

• 每个租户使用独立数据库：隔离性最强，运维成本也最高。
• 每个租户使用独立 Schema：逻辑隔离性强，基础设施共享。
• 共享 Schema，使用 tenant_id：运维最简单，但每条访问路径都必须强制限定范围。
• 记录所选模型，并禁止仓库绕过该模型。

解析租户身份

• 从经过验证的令牌声明、受信任的主机映射或已认证的 API 密钥中确定租户。
• 拒绝缺失、未知、已禁用或互相冲突的租户标识符。
• 切勿仅信任公开的 X-Tenant-Id 标头。
• 在 finally 中清除 servlet 线程本地上下文；响应式流程使用 Reactor Context。

强制隔离

• 在打开持久化会话或事务之前选择租户。
• 在唯一约束、缓存键、幂等键和对象存储路径中包含租户身份。
• 防止跨租户联接和不受限制的管理仓库。
• 明确授权支持人员模拟身份的操作，并审计每次使用。

运维

• 按数据库／Schema 运行迁移，并提供可恢复的进度和版本报告。
• 将租户身份显式传递到计划任务、消息和异步任务中。
• 使用配额限制高负载租户，并通过有界标识符提供按租户划分的可观测性。
• 测试跨租户访问失败的情况，而不仅是成功的租户查询。

示例

• 请参阅 examples/good-tenant-filter.java 和 examples/bad-tenant-filter.java。

注意事项

• Agent 信任调用方提供的租户标头——应从已认证的上下文中确定租户。
• Agent 忘记清除 servlet ThreadLocal——线程池中的线程可能会将一个租户的信息泄漏到另一个请求。
• Agent 限定数据库查询范围，却未限定缓存键——缓存数据可能跨租户泄漏。
• Agent 在选择租户前启动事务——路由可能会选择错误的数据库。
• Agent 在没有租户上下文的情况下运行后台任务——应将租户作为显式的任务参数。