多租户 SaaS 踩坑实录:5 个租户隔离陷阱
交付验收那周,一个伪造的租户编码,3 次请求里有 2 次拿到了 200。
开头:一个伪造请求打脸
交付验收那周,我写了个脚本,拿一个伪造的租户编码去请求公开接口。
第一次,403。 第二次,403。 第三次——200。
不是压测,是我自己系统的真实表现。一个已经跑在生产上的多租户 SaaS,每 3 次请求就有 2 次能绕过租户校验。
最要命的是它"间歇性":本地复现不了,测试同学跑十次全是 403,上线后偶尔冒一次。这种 bug 最像鬼。
查完之后我发现,根因不在业务代码里,在两个看起来非常合理的架构决定上。
先定义问题:多租户的命门只有一个
多租户 SaaS 的功能可以堆得很复杂:门店、员工、商品、订单、预约、施工、质保、退款、计费……
但所有这些,最终都压在同一句话上:
这次请求,到底属于哪个租户?
这个答案一旦错了,后果不是"界面显示不对",而是 A 公司的客户名单出现在 B 公司的后台里。对 SaaS 来说这不叫 bug,叫事故。
所以租户隔离不是"加个 tenant_id 字段"的事,它是一条从 HTTP 入口到 SQL 落库的链路。链路上任何一环漏了,整条链路就废了。
我用的方案是 MyBatis-Plus 的 TenantLineInnerInterceptor:所有 SQL 自动追加 tenant_id 条件,INSERT 自动补列值。这个方案本身没问题,问题是它周围的那几个决定。
[图:配图2-租户上下文链路.png —— 发嵘金时手动上传此图]
坑 1:fail-open —— 上下文为空时,过滤器整个跳过
这是最危险的一个,也是元凶。TenantLineHandler 的写法长这样:
@Override
public boolean ignoreTable(String tableName) {
// 无租户上下文(登录前 / 平台运营)→ 全部跳过过滤
if (TenantContext.get() == null) return true;
return TENANT_IGNORE_TABLES.contains(tableName.toLowerCase());
}
这个决定的初衷完全合理:平台运营要跨租户查数据,登录前的请求还没有租户。所以"没有上下文 = 不过滤"。
但它带来的后果是:
只要能让 TenantContext 变成 null,就能看到全部租户的数据。
而让上下文为 null 太容易了——任何不带 JWT 的接口都是 null。
我的白名单接口包括:商品、案例、门店、估价、质保查询。它们不带登录态,于是 TenantContext 为空,于是租户过滤器整条跳过,于是——
// 公开列表接口,本该只返回本租户的商品
productMapper.selectList(
new LambdaQueryWrapper<Product>().eq(Product::getStatus, 1));
这条 SQL 被自动改写成了不带 tenant_id 条件的版本,把所有租户的商品一起吐了出去。
这就是为什么第三个请求返回了 200。不是校验被绕过,是根本没人校验。
修法:匿名请求也必须先确定租户,再进业务。我加了一个最前置的拦截器:
public boolean preHandle(HttpServletRequest req,
HttpServletResponse res, Object handler) {
if (TenantContext.get() != null) return true;
String code = req.getHeader("X-Tenant-Code");
if (code == null || code.isBlank()) {
TenantContext.set(DEFAULT_TENANT_ID); // 兼容已发布的老小程序
} else {
SysTenant t = tenantMapper.selectOne(
new LambdaQueryWrapper<SysTenant>()
.eq(SysTenant::getTenantCode, code).last("LIMIT 1"));
if (t == null) throw new BusinessException(403, "租户编码无效");
if (t.getStatus() != null && t.getStatus() == 0)
throw new BusinessException(403, "该租户已停用");
TenantContext.set(t.getId());
}
return true;
}
给同行的建议:多租户系统里,null 上下文 这个状态不应该存在。它要么是明确的"平台运营上下文"(有独立标识、有权限校验),要么就该直接拒绝请求。fail-open 是隔离系统的原罪。
坑 2:ThreadLocal 用完不清理 —— 线程是复用的
上面那个拦截器加完之后,我以为完事了。没有。
修完坑 1 的当天,我又跑了一次伪造脚本:第一次 403,第二次 403,第三次又是 200。
根因在拦截器本身:它只 set,不 remove。
// 当时的写法(错误):只有 preHandle
public boolean preHandle(...) {
TenantContext.set(resolveTenantId(request));
return true;
}
// 没有 afterCompletion
TenantContext 是 ThreadLocal:
private static final ThreadLocal<Long> TENANT = new ThreadLocal<>();
而 Tomcat 的线程是复用的。一次请求结束,线程回到池子里,下一个请求可能落在同一个线程上。
于是:第一个伪造请求被校验拒掉(403),但线程里残留着上一个合法请求写下的租户值;第二个、第三个请求进来,if (TenantContext.get() != null) return true; 直接短路返回——校验被跳过了。
这就是"间歇性"的来源:撞上线程复用就中,撞不上就是 403。取决于线程池调度,跟代码看起来对不对完全无关。
修法只有一个字:清。
@Override
public void afterCompletion(HttpServletRequest req,
HttpServletResponse res,
Object handler, Exception ex) {
TenantContext.clear(); // 必须
}
修完之后,连发 6 次伪造编码,6 次全部 403。
给同行的建议:任何往 ThreadLocal 里塞东西的(租户、用户、traceId、数据源),都必须有一个"一定会被执行"的清理点。别指望业务代码自觉。ThreadLocal + 线程池 = 定时炸弹。
坑 3:匿名接口的租户来自可伪造的 Header
坑 1 的修法引入了一个新问题,我必须写清楚。
匿名请求没有登录态,那租户从哪来?只能从请求头来。 而请求头是客户端可以随便改的。这意味着:租户编码必须被当作公开信息对待。
所以我在设计上做了两个决定,也把它当成显式约束写进了代码注释:
- 匿名接口只做只读(商品、门店、案例、估价、质保查询),不做任何写操作。租户编码可伪造,但伪造的后果只是"看到别家公开的商品",不是"改别家数据"。
- 写操作一律走 JWT,AuthInterceptor 从 token 里解析租户,并且覆盖掉请求头解析出来的值。
后者靠的是拦截器的注册顺序——租户头解析在最前,AuthInterceptor 在后覆盖。
还有一处我认为仍然有风险,写出来给大家提个醒:缺省兜底到默认租户。
if (code == null || code.isBlank()) {
TenantContext.set(DEFAULT_TENANT_ID);
}
这是为了兼容已经发布出去的、不会带这个头的老版本小程序。但它的代价是:任何不带租户头的请求,都会默认落到租户 1。 一旦有第二个租户上线,这个兜底就成了"串租户"的通道。
如果让我重做一遍,我会给它加一个时间炸弹:兜底逻辑带过期时间,到点直接 403,逼客户端升级。
坑 4:拦截器顺序错了,分页的 total 会算错租户
这个坑不危险,但很隐蔽,而且我一开始就踩了。
MyBatis-Plus 的内置拦截器是按添加顺序执行的。租户拦截器会自动改写 SQL,分页拦截器会额外发一条 count 语句。如果分页在前、租户在后:
// 错误顺序
interceptor.addInnerInterceptor(pagination);
interceptor.addInnerInterceptor(new TenantLineInnerInterceptor(tenantHandler));
那么 count 语句会在租户条件还没补上的时候生成——列表返回的是本租户的 10 条数据,total 显示的却是全平台的总数。
这个 bug 不会报错,也不会越权,只会让你在后台看到一个永远对不上的数字,然后怀疑自己的业务逻辑。
正确顺序:
interceptor.addInnerInterceptor(new TenantLineInnerInterceptor(tenantHandler)); // 先租户
interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); // 后分页
给同行的建议:如果你的分页总数和实际列表对不上,先去看拦截器顺序,别去查业务代码。
坑 5:没有请求上下文的地方,会静默退化成"全租户"
这是坑 1 的连锁反应,也是最容易被忽略的一条。
fail-open 的设计意味着:所有没有 HTTP 请求上下文的地方,TenantContext 都是 null,租户过滤全部失效。
哪些地方没有请求上下文?
- 定时任务(我的订阅到期扫描、状态清理任务)
- 异步线程池 /
@Async - MQ 消费者
- 后台运维脚本
我有个定时任务扫描所有租户的到期状态。它跑起来的时候 TenantContext 是 null,于是那条查询扫了全库所有租户的数据。
对它来说这恰好是想要的行为——但这不是设计出来的,是碰巧。哪天我在这个任务里加一句写操作,它就会写到默认租户上,而且不会有任何报错。
给同行的建议:把"没有上下文"和"平台级上下文"当成两件事。前者的正确行为是抛异常,后者才允许跨租户。你现在混用,只是因为还没出事。
怎么守住它:不靠 review,靠能跑的用例
写到这里,方法论其实只有一句:
租户隔离不能靠人记得,只能靠每次上线都跑一遍的测试。
我最后的验证方式有三层,都很朴素。
第一层:造一个空租户做对照。 这招我觉得最划算。新建一个只有 0 条数据的租户,然后直接签发一个属于它的 JWT(HS256 手签,不用真的登录):
T2=$(sign_token 2) # payload 里 tenantId=2,空租户
for ep in orders appointments products warranties stores; do
R=$(curl -s "$API_BASE/v1/admin/$ep?page=1&pageSize=1" \
-H "Authorization: Bearer $T2")
check "租户2 $ep 列表为空" "$R" '"total":0'
done
空租户看到的任何一条数据,都是泄漏。 不需要写预期值,不需要维护基线,判断标准简单到不可能误判。
第二层:伪造租户头连发。
ck "伪造租户编码403" \
"$(api /v1/home -H 'X-Tenant-Code: no-such-tenant')" '403'
ck "租户B视角商品为空" \
"$(api '/v1/products?page=1&pageSize=1' \
-H 'X-Tenant-Code: tenant-b' | jv data.total)" '^0$'
关键不是单发一次,而是连发 6 次——只打一次,坑 1 和坑 2 都测不出来。
第三层:把上下文泄漏单独列成一条。 连续用不同租户请求同一接口,检查返回值是否串值。这条用例存在的唯一目的,就是钉死 ThreadLocal 残留。
三个套件加起来,租户相关的一共 12 条用例。数量不多,但每一条都对应上面某个坑。这就是我理解的"工程化交付":不是用例多,是每条用例都知道自己在防什么。
上线前必查清单
-
TenantContext为 null 时,是拒绝请求还是放行全部?(必须是前者) - 所有 ThreadLocal 上下文,有没有
afterCompletion清理 - 匿名接口是否只读?租户编码是否被当作公开信息对待
- 写操作是走 JWT 取租户,还是信任请求头
- 缺省兜底租户,有没有过期机制
- 租户拦截器是否在分页拦截器之前
- 定时任务 / 异步 / MQ 里,
TenantContext是 null 会发生什么 - 有没有一个"空租户"用来对照验证隔离
写在最后
写这篇不是为了说我的系统多好。恰恰相反——它是在被一个伪造请求打脸之后,我才把上面这些东西一条条补上的。
多租户这件事的残酷在于:你不会因为"写得优雅"而安全,只会因为"每个入口都回答了那句'你属于谁'"而安全。
如果你也在跑多租户系统,建议今晚就做一件小事:把 TenantContext 的读写点全部 grep 一遍,看有没有一处 set 找不到配对的 clear。
作者 | 老K写系统 。