mobile wallpaper 1mobile wallpaper 2mobile wallpaper 3mobile wallpaper 4
3605 words
9 minutes
多租户系统设计:Spring Boot 从 tenant_id 到完整数据隔离
2026-08-29

多租户系统设计: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_order
WHERE tenant_id = 1001;

优点:

  • 开发和部署成本低;
  • 新增租户不需要创建新数据库;
  • 数据库连接数容易控制;
  • 适合租户数量多、单租户数据量不大的系统。

缺点:

  • SQL 隔离一旦遗漏,影响严重;
  • 单租户备份与恢复更麻烦;
  • 大租户可能影响其他租户;
  • 表和索引设计必须始终考虑 tenant_id。

这是中小型 SaaS 最常见的第一版方案,本文也以它为例。

2.2 共享数据库、独立 Schema#

每个租户使用独立 Schema:

tenant_1001.oms_order
tenant_1002.oms_order
tenant_1003.oms_order

优点是隔离程度更高,单租户迁移和备份更方便;缺点是 Schema 数量多以后,建表、升级和连接管理会变复杂。

它适合租户数量有限、希望加强数据隔离,又不想给每个租户准备独立数据库实例的场景。

2.3 独立数据库#

每个租户拥有独立数据库:

tenant_1001_db
tenant_1002_db
tenant_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 NULL

3.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 完成认证以后,通过过滤器读取当前用户:

@Component
public 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:

@Configuration
public 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, status
FROM oms_order
WHERE status = 1;

经过拦截器后类似于:

SELECT id, order_sn, status
FROM oms_order
WHERE status = 1
AND tenant_id = 1001;

更新和删除同样需要租户条件:

UPDATE oms_order
SET status = 2
WHERE id = 10
AND tenant_id = 1001;

否则即使查询接口安全,更新接口仍可能修改其他租户的数据。

8. 新增数据也要防止串租户#

只给查询追加条件还不够,新增时必须写入租户 ID。

可以使用 MyBatis-Plus 的字段自动填充:

@Component
public 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;
}

一个“管理员角色”如果被错误授予,就会直接获得全平台数据。

更稳妥的做法是:

  1. 平台管理员和租户管理员使用不同身份体系或明确权限;
  2. 跨租户接口单独设计,不复用普通租户接口;
  3. 必须声明目标租户或经过专门审批;
  4. 记录操作者、目标租户、查询条件和操作结果;
  5. 导出、删除、修改等高风险操作增加二次确认。

绕过租户隔离应该是小范围、显式、可审计的能力,而不是随处可调用的工具方法。

11. 事务和异步任务中的上下文#

普通事务仍然可以读取当前线程中的租户:

@Transactional
public void createOrder(CreateOrderCommand command) {
// Mapper 自动使用当前 tenantId
}

但 ThreadLocal 不会自动传播到异步线程:

@Async
public 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:100
tenant: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
}
}

也可以按租户拆索引,但租户数量很大时会导致索引和分片数量膨胀。

日志与链路追踪#

日志建议记录:

traceId
tenantId
userId
operation
resourceId
result

这样出现跨租户问题时,才能沿调用链审计。但日志中仍要对手机号、地址和业务正文等敏感信息脱敏。

15. 租户生命周期也要设计#

多租户系统不仅要考虑查询,还要考虑租户从创建到退出的全过程:

创建租户
↓
初始化管理员、角色和基础数据
↓
开通套餐与资源配额
↓
正常使用
↓
到期、冻结或注销
↓
数据导出、保留和最终删除

租户状态可以包含:

PENDING
ACTIVE
SUSPENDED
EXPIRED
DELETING
DELETED

冻结租户时,不应只禁止登录,还要考虑:

  • 已登录 Token 是否立即失效;
  • API Key 是否停用;
  • 定时任务是否继续执行;
  • MQ 消息是否继续消费;
  • Webhook 是否继续发送;
  • 数据是否允许导出。

真正删除租户数据前,应有保留期限、备份策略和审计记录,不能只执行一条 DELETE。

16. 多租户系统怎么测试#

至少准备两个测试租户:

tenant A:用户 A、订单 A、商品 A
tenant B:用户 B、订单 B、商品 B

核心测试包括:

查询隔离#

A 查询订单列表 → 只能看到 A
A 使用 B 的订单 ID 查询详情 → 返回不存在或无权限

更新与删除隔离#

A 修改 B 的订单 → 影响行数必须为 0
A 删除 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_id
3. 唯一索引和常用查询索引包含 tenant_id
4. tenantId 从已验证的登录信息获取
5. 过滤器建立并在 finally 清理 TenantContext
6. MyBatis-Plus 自动处理查询、更新和删除条件
7. 新增数据由服务端自动填充 tenant_id
8. 全局表使用最小白名单
9. Redis、MQ、文件、搜索统一带租户维度
10. 平台管理员跨租户操作走独立接口并审计
11. 用两个租户完成查询、写入和异步链路测试

如果后续出现大客户、数据合规或单租户性能压力,再把部分租户迁移到独立 Schema 或独立数据库,而不是一开始就承担最高复杂度。

总结#

多租户的核心不是 tenant_id 这个字段,而是建立一条不可绕过的隔离链路:

可信身份
↓
租户上下文
↓
数据库读写隔离
↓
缓存、消息、文件和搜索隔离
↓
测试、日志与审计

设计时要记住:

  • 租户和用户不是同一个概念;
  • 共享表成本最低,但必须自动、统一地追加租户条件;
  • tenant_id 要进入唯一索引和常用查询索引;
  • 租户身份必须来自服务端验证过的认证信息;
  • 查询、更新、删除和新增都要隔离;
  • ThreadLocal 必须清理,异步任务必须显式传递;
  • Redis、MQ、文件和 Elasticsearch 同样会发生串租户;
  • 超级管理员的跨租户能力必须独立、最小化并可审计;
  • 插件只能降低遗漏概率,不能代替集成测试和安全评审。

真正可靠的多租户系统,不是“每条 SQL 看起来都加了条件”,而是即使某个开发者忘记处理租户,系统的默认行为仍然是拒绝访问,而不是返回其他客户的数据。

Share

If this article helped you, please share it with others!

多租户系统设计:Spring Boot 从 tenant_id 到完整数据隔离
https://mizuki.mysqil.com/posts/spring-boot-multi-tenant-design/
Author
梦幻晨风
Published at
2026-08-29
License
CC BY-NC-SA 4.0

Some information may be outdated

Table of Contents