多租户系统设计:Spring Boot 从 tenant_id 到完整数据隔离
做企业管理系统、商城后台或 SaaS 平台时,经常会遇到一个需求:
同一套系统要服务多家公司,但每家公司只能看到自己的数据。
这就是多租户。
多租户并不只是给业务表增加一个 tenant_id 字段。真正的目标是让不同租户共享一套系统能力,同时在数据、缓存、文件、消息和权限上保持清晰边界。
如果只在部分查询中手写:
WHERE tenant_id = ?漏掉一次,就可能把 A 公司的订单返回给 B 公司。多租户设计首先是安全问题,其次才是减少部署成本的问题。
这一篇从原理开始,完成一套适合普通 Spring Boot 项目的第一版设计:
识别当前租户 ↓建立可信的租户上下文 ↓数据库查询自动追加 tenant_id ↓新增数据自动写入 tenant_id ↓缓存、消息、文件等资源继续隔离 ↓测试和审计保证没有遗漏1. 什么是租户
租户可以理解为使用系统的一组独立客户。
例如一个 SaaS 进销存平台有三家客户:
租户 1001:星海贸易有限公司租户 1002:青山制造有限公司租户 1003:远航供应链有限公司它们使用同一个域名、同一套后端代码,但业务数据互相不可见:
用户商品订单客户库存报表租户不是普通用户。一个租户下面通常还有多个用户和角色:
租户 ├── 租户管理员 ├── 运营人员 ├── 财务人员 └── 普通员工所以系统里至少有两层边界:
| 边界 | 解决的问题 |
|---|---|
| 租户隔离 | 当前用户能访问哪一家公司的数据 |
| 用户权限 | 在这家公司内,当前用户能做什么 |
tenant_id 不能代替 RBAC 权限,角色权限也不能代替租户隔离。
2. 三种常见隔离方案
多租户数据库通常有三种模型。
2.1 共享数据库、共享表
所有租户使用相同数据库和相同表,通过 tenant_id 区分数据:
oms_order ├── id ├── tenant_id ├── order_sn ├── member_id └── status查询租户 1001 的订单:
SELECT *FROM oms_orderWHERE tenant_id = 1001;优点:
- 开发和部署成本低;
- 新增租户不需要创建新数据库;
- 数据库连接数容易控制;
- 适合租户数量多、单租户数据量不大的系统。
缺点:
- SQL 隔离一旦遗漏,影响严重;
- 单租户备份与恢复更麻烦;
- 大租户可能影响其他租户;
- 表和索引设计必须始终考虑
tenant_id。
这是中小型 SaaS 最常见的第一版方案,本文也以它为例。
2.2 共享数据库、独立 Schema
每个租户使用独立 Schema:
tenant_1001.oms_ordertenant_1002.oms_ordertenant_1003.oms_order优点是隔离程度更高,单租户迁移和备份更方便;缺点是 Schema 数量多以后,建表、升级和连接管理会变复杂。
它适合租户数量有限、希望加强数据隔离,又不想给每个租户准备独立数据库实例的场景。
2.3 独立数据库
每个租户拥有独立数据库:
tenant_1001_dbtenant_1002_dbtenant_1003_db它的隔离最强,单租户扩容、备份、迁移和合规处理也最方便。但数据库实例、连接池、版本升级和运维成本最高。
适合大型客户、金融等强合规业务,或者需要为特定客户提供独立部署的场景。
2.4 怎么选择
可以从租户规模和隔离要求判断:
| 方案 | 隔离程度 | 成本 | 典型场景 |
|---|---|---|---|
| 共享表 | 较低 | 低 | 中小型 SaaS、租户数量多 |
| 独立 Schema | 中等 | 中等 | 租户数量有限、需要独立备份 |
| 独立数据库 | 高 | 高 | 大客户、强合规、独立部署 |
现实项目也可以使用混合模式:普通客户使用共享表,大客户迁移到独立数据库。这个方案更灵活,但路由、迁移和运维系统也会更复杂。
3. 第一版表结构怎么设计
以共享表方案为例,所有租户业务表都要有 tenant_id:
CREATE TABLE oms_order ( id BIGINT NOT NULL, tenant_id BIGINT NOT NULL, order_sn VARCHAR(64) NOT NULL, member_id BIGINT NOT NULL, status INT NOT NULL, create_time DATETIME NOT NULL, PRIMARY KEY (id), UNIQUE KEY uk_tenant_order_sn (tenant_id, order_sn), KEY idx_tenant_member (tenant_id, member_id), KEY idx_tenant_create_time (tenant_id, create_time));这里有三个关键点。
3.1 tenant_id 不能为空
如果允许为空,就会出现“不属于任何租户”的业务数据。后续查询时,这类数据很容易成为隔离漏洞。
业务表应尽量使用:
tenant_id BIGINT NOT NULL3.2 唯一索引要包含 tenant_id
订单号可能只要求在一个租户内唯一,而不是全平台唯一:
UNIQUE KEY uk_tenant_order_sn (tenant_id, order_sn)如果只给 order_sn 建唯一索引,不同租户就不能使用相同编号。
类似的还有:
(tenant_id, username)(tenant_id, product_code)(tenant_id, role_name)(tenant_id, external_id)3.3 常用索引把 tenant_id 放在前面
多租户查询通常先限定租户,再查询业务字段:
WHERE tenant_id = ? AND member_id = ?因此 (tenant_id, member_id) 往往比单独的 member_id 更符合访问方式。
但索引不能机械添加,仍然要结合查询条件、选择性和执行计划判断。
4. 租户 ID 从哪里来
常见租户来源有:
- 二级域名:
acme.example.com; - 登录后的 JWT Claim;
- 服务端 Session;
- API Key 绑定的租户;
- 内部服务调用携带的可信身份信息。
最危险的做法是直接相信客户端请求头:
X-Tenant-Id: 1002如果普通用户可以随意修改这个值,就可能从租户 1001 切换到 1002。
更安全的思路是:
用户登录 ↓服务端校验账号所属租户 ↓签发包含 tenantId 的可信登录凭证 ↓请求进入后端 ↓从已验证的认证信息中读取 tenantId请求头可以作为网关和内部服务之间的传递载体,但必须由可信网关写入,下游还要防止外部请求伪造。
5. 建立租户上下文
在同步 Spring MVC 项目中,可以先用 ThreadLocal 保存当前租户:
public final class TenantContext {
private static final ThreadLocal<Long> CURRENT = new ThreadLocal<>();
private TenantContext() { }
public static void setTenantId(Long tenantId) { if (tenantId == null) { throw new IllegalArgumentException("tenantId must not be null"); } CURRENT.set(tenantId); }
public static Long getRequiredTenantId() { Long tenantId = CURRENT.get(); if (tenantId == null) { throw new IllegalStateException("Tenant context is missing"); } return tenantId; }
public static void clear() { CURRENT.remove(); }}注意这里使用 getRequiredTenantId(),上下文不存在时直接失败,而不是返回一个默认租户。
默认租户会掩盖调用链问题,严重时会让数据写入错误客户名下。
6. 从登录用户建立上下文
可以在 Spring Security 完成认证以后,通过过滤器读取当前用户:
@Componentpublic class TenantContextFilter extends OncePerRequestFilter {
@Override protected void doFilterInternal( HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
try { Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
if (authentication != null && authentication.getPrincipal() instanceof LoginUser user) { TenantContext.setTenantId(user.getTenantId()); }
filterChain.doFilter(request, response); } finally { TenantContext.clear(); } }}finally 中的 clear() 不能省略。Web 服务器会复用线程,如果旧租户上下文残留,下一个请求可能继承上一个请求的租户。
过滤器顺序也要明确:
认证过滤器 ↓解析并验证登录用户 ↓租户上下文过滤器 ↓Controller / Service / Mapper如果租户过滤器先执行,就无法从认证信息中获得可信租户。
7. 用 MyBatis-Plus 自动追加租户条件
如果每个 Mapper 都手写 tenant_id,很难保证没有遗漏。
MyBatis-Plus 提供 TenantLineInnerInterceptor,可以统一改写 SQL:
@Configurationpublic class MybatisPlusConfig {
@Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
interceptor.addInnerInterceptor( new TenantLineInnerInterceptor(new TenantLineHandler() { @Override public Expression getTenantId() { return new LongValue( TenantContext.getRequiredTenantId()); }
@Override public String getTenantIdColumn() { return "tenant_id"; }
@Override public boolean ignoreTable(String tableName) { return TenantTableRegistry.isGlobalTable(tableName); } }) );
return interceptor; }}原始查询:
SELECT id, order_sn, statusFROM oms_orderWHERE status = 1;经过拦截器后类似于:
SELECT id, order_sn, statusFROM oms_orderWHERE status = 1 AND tenant_id = 1001;更新和删除同样需要租户条件:
UPDATE oms_orderSET status = 2WHERE id = 10 AND tenant_id = 1001;否则即使查询接口安全,更新接口仍可能修改其他租户的数据。
8. 新增数据也要防止串租户
只给查询追加条件还不够,新增时必须写入租户 ID。
可以使用 MyBatis-Plus 的字段自动填充:
@Componentpublic class TenantMetaObjectHandler implements MetaObjectHandler {
@Override public void insertFill(MetaObject metaObject) { strictInsertFill( metaObject, "tenantId", Long.class, TenantContext.getRequiredTenantId() ); }
@Override public void updateFill(MetaObject metaObject) { }}实体字段:
@TableField(fill = FieldFill.INSERT)private Long tenantId;同时不要直接采用前端提交的 tenantId:
// 不推荐order.setTenantId(request.getTenantId());
// 推荐:来自服务端可信上下文order.setTenantId(TenantContext.getRequiredTenantId());DTO 中如果不需要租户字段,最好根本不要暴露它。
9. 哪些表不需要 tenant_id
并不是所有表都是租户表。
常见全局表包括:
- 国家和地区;
- 行政区划;
- 系统字典;
- 平台级菜单;
- 租户套餐;
- 租户本身;
- 平台公告。
可以维护明确的全局表白名单:
private static final Set<String> GLOBAL_TABLES = Set.of( "sys_tenant", "sys_tenant_plan", "sys_region", "sys_global_dict");白名单应该尽量短,并经过评审。不要使用“表名以 sys_ 开头就忽略”这种过宽规则,因为系统表中也可能保存租户私有数据。
10. 超级管理员怎么处理
平台管理员可能需要跨租户查询,但不能简单写成:
if (isAdmin) { ignoreTenant = true;}一个“管理员角色”如果被错误授予,就会直接获得全平台数据。
更稳妥的做法是:
- 平台管理员和租户管理员使用不同身份体系或明确权限;
- 跨租户接口单独设计,不复用普通租户接口;
- 必须声明目标租户或经过专门审批;
- 记录操作者、目标租户、查询条件和操作结果;
- 导出、删除、修改等高风险操作增加二次确认。
绕过租户隔离应该是小范围、显式、可审计的能力,而不是随处可调用的工具方法。
11. 事务和异步任务中的上下文
普通事务仍然可以读取当前线程中的租户:
@Transactionalpublic void createOrder(CreateOrderCommand command) { // Mapper 自动使用当前 tenantId}但 ThreadLocal 不会自动传播到异步线程:
@Asyncpublic void generateReport() { // 这里可能没有 tenantId}可以显式传递租户 ID:
reportService.generate(tenantId, reportId);任务执行时再建立作用域:
try { TenantContext.setTenantId(tenantId); reportService.doGenerate(reportId);} finally { TenantContext.clear();}定时任务也不存在“当前登录用户”。如果要为所有租户结算,可以先遍历租户,再逐个建立上下文:
查询有效租户 ↓租户 1001:建立上下文 → 执行 → 清理 ↓租户 1002:建立上下文 → 执行 → 清理不要在无租户上下文时直接执行全表任务。
12. Redis 也必须隔离
数据库做了隔离,缓存 Key 如果仍然共用,也会串数据。
错误示例:
product:detail:100如果不同租户都有商品 100,就会读到同一个缓存。
推荐:
tenant:1001:product:detail:100tenant:1002:product:detail:100统一封装 Key 构造器:
public String tenantKey(String businessKey) { return "tenant:" + TenantContext.getRequiredTenantId() + ":" + businessKey;}还要检查:
- Spring Cache 的 Key;
- 分布式锁 Key;
- 幂等 Token;
- 验证码和限流计数;
- Session;
- Redis Stream 或 List 队列。
缓存击穿不只是性能问题,在多租户系统中也可能变成数据泄漏问题。
13. MQ 消息要携带 tenant_id
消息消费者通常运行在独立线程中,没有请求上下文。
消息体或消息头必须携带租户信息:
{ "eventId": "evt_202608290001", "tenantId": 1001, "eventType": "ORDER_CREATED", "orderId": 90001}消费流程:
校验消息 ↓读取 tenantId ↓建立租户上下文 ↓执行业务逻辑 ↓清理上下文幂等记录也要考虑租户:
UNIQUE KEY uk_tenant_event (tenant_id, event_id)否则两个租户使用相同业务事件号时,可能被错误判定为重复消息。
14. 文件、搜索和日志同样有租户边界
多租户不能只盯着 MySQL。
文件存储
对象存储路径建议包含租户:
/tenant/1001/contracts/xxx.pdf/tenant/1002/contracts/xxx.pdf下载时不能只凭文件 URL,还要验证当前租户是否有权访问对象。
Elasticsearch
可以在同一个索引中保存 tenantId,所有查询强制追加过滤:
{ "term": { "tenantId": 1001 }}也可以按租户拆索引,但租户数量很大时会导致索引和分片数量膨胀。
日志与链路追踪
日志建议记录:
traceIdtenantIduserIdoperationresourceIdresult这样出现跨租户问题时,才能沿调用链审计。但日志中仍要对手机号、地址和业务正文等敏感信息脱敏。
15. 租户生命周期也要设计
多租户系统不仅要考虑查询,还要考虑租户从创建到退出的全过程:
创建租户 ↓初始化管理员、角色和基础数据 ↓开通套餐与资源配额 ↓正常使用 ↓到期、冻结或注销 ↓数据导出、保留和最终删除租户状态可以包含:
PENDINGACTIVESUSPENDEDEXPIREDDELETINGDELETED冻结租户时,不应只禁止登录,还要考虑:
- 已登录 Token 是否立即失效;
- API Key 是否停用;
- 定时任务是否继续执行;
- MQ 消息是否继续消费;
- Webhook 是否继续发送;
- 数据是否允许导出。
真正删除租户数据前,应有保留期限、备份策略和审计记录,不能只执行一条 DELETE。
16. 多租户系统怎么测试
至少准备两个测试租户:
tenant A:用户 A、订单 A、商品 Atenant B:用户 B、订单 B、商品 B核心测试包括:
查询隔离
A 查询订单列表 → 只能看到 AA 使用 B 的订单 ID 查询详情 → 返回不存在或无权限更新与删除隔离
A 修改 B 的订单 → 影响行数必须为 0A 删除 B 的商品 → 影响行数必须为 0新增归属
A 创建订单 → tenant_id 必须由服务端写成 A前端伪造 tenant_id=B → 必须被忽略或拒绝非数据库资源
A 不能读取 B 的 Redis 缓存A 不能下载 B 的文件A 的消费者不能处理成 B 的数据A 的搜索结果不能出现 B 的商品上下文清理
连续发送 A、B 两个请求,验证线程复用时不会继承上一请求的租户。
除了单元测试,最好增加真实数据库集成测试。因为复杂联表、子查询、自定义 SQL 和批量操作能否被正确改写,不能只靠阅读代码判断。
17. 常见错误
把 tenant_id 当成前端筛选条件
租户隔离必须由服务端强制执行,不能依赖前端每次传参。
只隔离 SELECT
UPDATE、DELETE、批量操作和自定义 SQL 同样可能越权。
忘记唯一索引
只添加字段但不调整唯一索引,会让不同租户之间产生不必要冲突。
ThreadLocal 不清理
线程池复用会导致请求串租户,必须在 finally 中清理。
异步任务丢失租户
@Async、定时任务和 MQ 消费都要显式恢复租户上下文。
缓存 Key 没有租户前缀
数据库安全不代表缓存安全,分布式锁和幂等 Key 也要隔离。
绕过开关过于随意
“忽略租户”的能力必须小范围、显式授权并记录审计日志。
认为用了插件就绝对安全
SQL 插件可能无法正确处理某些复杂 SQL、存储过程或手写 JDBC。所有绕过 ORM 的路径都要单独检查。
18. 一套可落地的第一版
如果是中小型 Spring Boot SaaS 项目,可以先这样实现:
1. 选择共享数据库、共享表2. 所有租户业务表增加非空 tenant_id3. 唯一索引和常用查询索引包含 tenant_id4. tenantId 从已验证的登录信息获取5. 过滤器建立并在 finally 清理 TenantContext6. MyBatis-Plus 自动处理查询、更新和删除条件7. 新增数据由服务端自动填充 tenant_id8. 全局表使用最小白名单9. Redis、MQ、文件、搜索统一带租户维度10. 平台管理员跨租户操作走独立接口并审计11. 用两个租户完成查询、写入和异步链路测试如果后续出现大客户、数据合规或单租户性能压力,再把部分租户迁移到独立 Schema 或独立数据库,而不是一开始就承担最高复杂度。
总结
多租户的核心不是 tenant_id 这个字段,而是建立一条不可绕过的隔离链路:
可信身份 ↓租户上下文 ↓数据库读写隔离 ↓缓存、消息、文件和搜索隔离 ↓测试、日志与审计设计时要记住:
- 租户和用户不是同一个概念;
- 共享表成本最低,但必须自动、统一地追加租户条件;
tenant_id要进入唯一索引和常用查询索引;- 租户身份必须来自服务端验证过的认证信息;
- 查询、更新、删除和新增都要隔离;
- ThreadLocal 必须清理,异步任务必须显式传递;
- Redis、MQ、文件和 Elasticsearch 同样会发生串租户;
- 超级管理员的跨租户能力必须独立、最小化并可审计;
- 插件只能降低遗漏概率,不能代替集成测试和安全评审。
真正可靠的多租户系统,不是“每条 SQL 看起来都加了条件”,而是即使某个开发者忘记处理租户,系统的默认行为仍然是拒绝访问,而不是返回其他客户的数据。
If this article helped you, please share it with others!
Some information may be outdated






