多租户第二集:读隔离做完之后,写路径才是真坑

0 阅读16分钟

多租户第一集

第一集的结尾我说「每个入口都要回答那句『你属于谁』」。 这一集我要补一句:读的时候回答错了,你只是多看了一眼;写的时候回答错了,你就改到别人家了。


开头:我把所有读接口都堵上了,然后建单漏了一行

第一集里那套东西上线后,读路径我盯得很紧:租户拦截器、afterCompletion 清理、匿名请求必须解析出租户、空租户当基准做对照。伪造租户头的脚本连发 6 次,6 次全部 403。

我以为这事结了。

然后我逐个 review 写接口,发现 OrderService.create() 里少了一行:

// OrderService.update() / updateStatus() / addPayment() / voidPayment() / detail()
storeAccessChecker.require(order.getStoreId()); // 门店归属校验(跨门店 IDOR 防护)

这行在 update、updateStatus、addPayment、voidPayment、detail 里都有,唯独 create 没有。

后果不是串租户——租户拦截器还在,写不进别人家的租户。后果是串门店:一个绑定了 A 门店的店长,可以给 B 门店建单。而多租户系统里,「租户隔离」和「门店隔离」是两层墙,很多人把第一层砌完就收工了。

这件事让我把写路径重新过了一遍。结论是:读路径和写路径不是一个问题。

先分清:读隔离靠过滤,写隔离靠归属

读的时候,你只需要回答一个问题:这条 SQL 该不该看见别人?

这件事拦截器能替你做——它在 SQL 生成时补一句 AND tenant_id = ?,你没写也不会漏。

写的时候,要回答的是另外三个问题:

  1. 这行数据归谁?(归属)
  2. 它的编号会不会撞到别人?(唯一性)
  3. 这个限额/这个名额是不是已经被抢走了?(并发)

这三个问题,拦截器一个都答不了。它只会在 INSERT 时补一列 tenant_id,仅此而已。

所以我把写路径的坑分成四类记下来:错归、撞码、超配、丢租户。下面一条一条说。

坑 1:归属校验写成了 fail-open

先看那个漏掉的 require 为什么会被漏——因为它本身不显眼地放行。

public Long scopedStoreId() {
    Long aid = SecurityContext.getUserId();
    if (aid == null || !SecurityContext.isAdmin()) return null;   // 非后台 admin 上下文不限
    Admin a = adminMapper.selectById(aid);
    if (a == null || a.getRoleId() == null || a.getStoreId() == null) return null;
    Role role = roleMapper.selectById(a.getRoleId());
    if (role != null && "SUPER_ADMIN".equals(role.getRoleCode())) return null;  // 超管不限门店
    return a.getStoreId();
}

这段的设计意图写在注释里,很克制:「避免误伤合法操作」。非后台上下文放行、超管放行、没绑店放行,只有「明确绑了店」且「资源也明确有店」且「两者不一致」才拒绝。

作为读接口的守卫,这个语义可以接受——最多是多看了几条。 作为写接口的守卫,它就是「谁都能改」。

而 require() 只在两个值都非空时才拦:

public void require(Long resourceStoreId) {
    Long scope = scopedStoreId();
    if (scope != null && resourceStoreId != null && !scope.equals(resourceStoreId)) {
        throw new BusinessException("无权操作其他门店的数据");
    }
}

resourceStoreId == null 的时候它什么都不做。所以只要有一个写接口忘了传门店,或者前端传了个 null,这一层就等于不存在。

修法:我给写入口单独加了一层 requireWritable(storeId),语义是反过来的——

  • 后台 admin 上下文 + 绑了店 + 资源门店为空 → 拒绝(宁可让人补一次参数)
  • 后台 admin 上下文 + 绑了店 + 门店不一致 → 拒绝
  • 其余(超管 / 平台 / 小程序用户)→ 放行

给同行的建议:读接口的守卫可以 fail-open,写接口的守卫必须 fail-closed。同一段判断逻辑同时服务读写入口,最后一定会偏向其中一边——通常偏向往松的那边,因为松的那边不会报错。

坑 2:编号生成和唯一索引,不在同一个作用域里

这是写路径里最隐蔽的一类,因为它只在第二个租户出现时才爆。

看质保单号是怎么生成的:

long count = warrantyMapper.selectCount(new LambdaQueryWrapper<Warranty>()
        .likeRight(Warranty::getWarrantyCode, "GA-" + storeCode + "-" + today));
w.setWarrantyCode("GA-" + storeCode + "-" + today + "-" + String.format("%03d", count + 1));

拆开看,这里有三个作用域:

部分作用域
count本租户内(拦截器自动加了 tenant_id)
storeCode前端传的,表上没有任何唯一约束
uk_warranty_code全局唯一(迁移脚本里明确保留了)

三个作用域对不上,撞码就只是时间问题:两个租户都用 storeCode = "001",同一天各自出第一张质保单,都会生成 GA-001-20261118-001。第二个租户的建单事务直接 DuplicateKeyException,整个订单回滚。

而迁移脚本里的注释是这么写的:

-- 单据编号类 order_no/warranty_code/assignment_no 保持全局唯一:
-- 时间戳+随机不冲突且利于跨租户检索

这句话对 order_no 和 assignment_no 成立——它们真的是 OD + 时间戳 + 4 位随机。但 warranty_code 不是随机串,是「门店编码 + 日期 + 租户内序号」。序号被租户隔离了,前缀却可能重复,全局唯一索引就变成了一个定时炸弹。

同一类问题还有一处,更隐蔽:

private Long findOrCreateCategory(String name) {
    ProductCategory exist = categoryMapper.selectOne(...);
    if (exist != null) return exist.getId();
    ProductCategory c = new ProductCategory();
    c.setCategoryKey("cat_" + System.currentTimeMillis());   // 毫秒级时间戳当唯一键
    categoryMapper.insert(c);
    return c.getId();
}

category_key 在迁移后是 (tenant_id, category_key) 唯一。Excel 批量导入时,两行不同的新分类名在同一毫秒内创建,就会生成两个相同的 key,直接撞索引。

修法(这类问题只有三种解法,按可靠性排序):

  1. 让编号带租户前缀:GA-{tenantCode}-{storeCode}-{date}-{seq}。冲突域和唯一索引对齐。
  2. 让唯一索引带上租户:uk (tenant_id, warranty_code)。适合「编号本身不该跨租户可读」的场景。
  3. 换成不含语义的 ID:UUID / 雪花 ID。彻底摆脱「人工可读编号」和「数据库唯一约束」的耦合。

我选了第 1 种——单据号对客户是有意义的信息(能一眼看出是哪家店哪天出的),不该为了唯一性把它变成一串乱码。分类 key 那种纯粹内部的字段,选了第 3 种。

给同行的建议:加 tenant_id 列的时候,把所有唯一索引列出来,逐个问一句「这个唯一性,是业务真的要求全局,还是因为它原来是全局的」。前者保留,后者必须改成租户内——否则你只是把「串数据」换成了「第二个租户开不通」。

坑 3:配额是「先查后插」,并发下必然超配

套餐限额我一开始是这么写的:

public void checkStoreQuota() {
    Long tenantId = TenantContext.get();
    if (tenantId == null || SecurityContext.isPlatform()) return;
    SysTenant t = tenantMapper.selectById(tenantId);
    if (t == null || t.getMaxStores() == null || t.getMaxStores() == 0) return; // 不限
    Long count = storeMapper.selectCount(new QueryWrapper<Store>().eq("tenant_id", tenantId));
    if (count >= t.getMaxStores()) {
        throw new BusinessException("已达套餐门店上限(" + count + "/" + t.getMaxStores() + ")");
    }
}

调用方紧接着 insert。两次操作之间没有任何锁,biz_store 上也没有「每租户最多 N 行」这种约束(SQL 层面表达不了)。

所以套餐写「最多 3 家门店」,管理员把创建按钮点两下,或者前端并发发出两个请求,两个请求都读到 count = 2,都通过校验,最后变成 4 家。

这类问题不是多租户独有的,但多租户会放大它:限额是收钱的依据。多开一家门店,平台就少收一份钱,而且没有任何日志或告警会告诉你「这个租户超了」。

修法(按成本排序):

  1. 唯一约束兜底:给一个 tenant_quota_usage(tenant_id, resource, used, version) 表,用 UPDATE ... WHERE used < limit 做原子占位。改一行成功即扣减成功。
  2. 行锁:SELECT ... FROM sys_tenant WHERE id = ? FOR UPDATE,在事务里把校验和插入串起来。租户表很小,锁粒度可接受。
  3. 业务侧幂等:给创建接口加幂等键,挡住「双击提交」这一个最常见的成因。

改完之后我用的是第 2 种 + 第 3 种:provision 和门店创建都改成在事务里先锁租户行。理由是这个系统的并发量根本撑不到需要无锁方案的程度,而正确性比吞吐重要得多。

给同行的建议:凡是「读一个计数 → 判断 → 写一行」的模式,都要问一句「两个请求同时到会怎样」。如果答案是「都不会报错」,那就是一个还没被触发的 bug。

坑 4:上下文切换不是事务边界

这一条是我写完上面三条之后才想明白的,也是最容易被误用的。

先看开通租户的流水线:

@Transactional
public Map<String, Object> provision(Map<String, Object> body) {
    ...
    // 用平台上下文把模板数据读进内存
    List<Role> templateRoles = roleMapper.selectList(...);

    // 切到新租户上下文:后续 INSERT 由租户拦截器自动补 tenant_id
    TenantContext.set(t.getId());
    try {
        // 复制角色、菜单、配置、创建超管、复制商品目录……
    } finally {
        TenantContext.clear();
    }
    ...
}

这段能跑,而且逻辑是对的。但它有两个容易被忽略的性质:

第一,clear 不是 restore。

} finally {
    TenantContext.clear();   // 恢复的是 null,不是「调用方原来的上下文」
}

今天 provision 只被平台接口调用,平台上下文的租户正好是 null,所以清空等于恢复。但只要这个方法将来被别的场景复用(批量开通、内部任务、定时补数据),调用方的租户就会被悄悄清空。而清空之后,拦截器的 ignoreTable 会返回 true——所有表的租户过滤全部失效。

这就是第一集那个 fail-open,换了个地方又长出来了。

正确的写法是把「调用方是谁」还回去:

Long previous = TenantContext.get();
try {
    TenantContext.set(targetTenantId);
    ...
} finally {
    if (previous != null) TenantContext.set(previous); else TenantContext.clear();
}

商品目录复制那段就是这么写的,cloneCatalog() 里存了 previous 并在 finally 还原——同一个项目里,两种写法并存,说明这件事靠自觉是守不住的。

第二,也是更根本的:事务没有「属于哪个租户」这个概念。

租户值不是绑在事务上的,是在每条 SQL 生成的那一刻从 ThreadLocal 读的:

@Override
public Expression getTenantId() {
    return new LongValue(TenantContext.get());
}

这意味着:

  • 一个事务里可以先后写两个租户的数据,插件不会报错,只会给每条 SQL 套上「当时线程里的那个租户」;
  • 事务回滚的时候,上下文不会跟着回滚;
  • 上下文的生命周期(preHandle → afterCompletion)比事务的生命周期更短——finally 在方法返回前执行,事务提交在方法返回后。

所以在租户插件下,「跨租户的原子操作」是个伪命题。你能做的只有两件事:

  1. 把跨租户操作拆成多个事务,每个事务只在一个租户上下文里跑,用状态机 + 补偿保证最终一致;
  2. 或者明确标注「这是平台级操作」,走白名单表 / 显式 tenant_id 条件,不依赖拦截器。

我选了第 2 种给开通流水线:租户主记录、角色、配置全部用显式 tenant_id 写入,只在复制商品目录时短暂切上下文(因为它要写的表太多,逐条补 tenant_id 不现实)。

给同行的建议:如果你在 @Transactional 方法里看到 TenantContext.set(),先确认三件事——previous 有没有存、finally 里是 restore 还是 clear、这个方法未来会不会被平台上下文以外的地方调用。

坑 5:异步链路丢租户,表现不是报错,是「什么都没发生」

先看通知服务的入口:

public void notify(Long tenantId, String type, String bizType, Long bizId, String title, String content) {
    if (tenantId == null) return;   // 静默返回,连一条 warn 都没有
    try {
        ...
    } catch (Exception e) {
        log.warn("通知发送失败(不影响主业务): ...", e.getMessage());
    }
}

调用方长这样:

notificationService.notify(TenantContext.get(), "warning", "inventory", inv.getId(), ...);

在 HTTP 请求里,TenantContext.get() 有值,一切正常。 在定时任务、@Async 方法、MQ 消费者里,TenantContext.get() 是 null,于是 notify 在第二行就 return 了。

结果是:通知一条都没发出去,日志干净得像什么都没发生,业务继续往下跑。

这比抛异常糟糕得多。抛异常至少会有人看到堆栈;静默返回会让一个功能「安静地消失」,可能在几个月后才发现「库存预警从来没响过」。

我现在的系统里还没有异步线程池,也没有 MQ——所以这条目前只是一个定时任务级别的风险。但正因为没有,才更该现在补:第一次有人写 @Async 的那天,这条会从「不发通知」变成「数据事故」,因为异步方法里第一个 SQL 会以 null 上下文执行,ignoreTable 返回 true,全表不隔离。

修法(三层,缺一层都不算稳):

// 第一层:上下文必须能跨线程传
@Bean
public TaskDecorator tenantTaskDecorator() {
    return runnable -> {
        Long tenantId = TenantContext.get();
        Long userId = SecurityContext.getUserId();
        return () -> {
            TenantContext.set(tenantId);
            SecurityContext.setUserId(userId);
            try { runnable.run(); }
            finally { TenantContext.clear(); SecurityContext.clear(); }
        };
    };
}
// 第二层:异步入口第一行就断言,不许「没有上下文」悄悄跑
private void requireContext(String where) {
    if (TenantContext.get() == null) {
        throw new IllegalStateException("租户上下文缺失:" + where);
    }
}
// 第三层:租户是数据,不是环境——跨租户调用一律显式传参
notificationService.notify(tenantId, ...);   // 不读 ThreadLocal

第三层是我认为最重要的一层。notify 的签名接收 tenantId 是对的,错的是调用方传了 TenantContext.get()。凡是「可能要跨租户调用」的方法,租户必须走参数;只有「一定在本租户内」的方法,才允许读上下文。

给同行的建议:grep 一遍 TenantContext.get() 的所有调用点,逐个问「这个方法会不会在没有 HTTP 请求的线程里被调用」。会的话,改成显式参数。

坑 6:定时任务「碰巧」跨租户

@Scheduled(cron = "0 10 4 * * ?")
public void dailyWarrantyExpireJob() {
    LambdaUpdateWrapper<Warranty> uw = new LambdaUpdateWrapper<Warranty>()
            .eq(Warranty::getStatus, 1)
            .lt(Warranty::getExpireDate, LocalDate.now())
            .set(Warranty::getStatus, 2);
    int n = warrantyMapper.update(null, uw);   // 上下文为 null → 不加 tenant_id → 覆盖所有租户
}

它今天是正确的:定时任务跑在没有上下文的线程里,拦截器不追加条件,于是这条 UPDATE 扫了全平台。

但它的正确性来自一个巧合:null 上下文 = 不过滤 恰好等于「我要处理全部租户」。

这个巧合会在三种情况下破掉:

  1. 有人给 @Scheduled 加了 @Async,或者接了个线程池,上下文变成「上一个任务的残留」;
  2. 有人把这个方法抽成 WarrantyService.expireAll(),被运维后台的「立即执行」按钮调用——那时候上下文是当前登录租户,它会只处理一家;
  3. 有人在任务里加了一句写操作,它会写到「租户 1」上(因为 null 上下文下拦截器不补列,tenant_id 落成默认值)。

这三种情况都不会报错。

修法:让定时任务显式表达「我要跨租户」,而不是依赖 null 的副作用。

// 方案 A:显式遍历租户(最啰嗦,但语义最清楚,也最容易加日志和重试)
for (SysTenant t : tenantMapper.selectList(...)) {
    TenantContext.set(t.getId());
    try { warrantyService.expireForTenant(t.getId()); }
    finally { TenantContext.clear(); }
}

// 方案 B:显式标注平台级,走白名单表 + 显式条件
@PlatformJob   // 自定义注解,任务入口断言「这不是租户上下文」

我用的是 B + A 混合:批量任务用 A(可以按租户打点、失败隔离),跨租户统计用 B。

给同行的建议:null 上下文 这个状态不该存在——这是第一集的核心结论,这一集要再加一句:如果它必须存在,就必须有一个显式的名字(比如 TenantContext.platform() 返回一个哨兵值),而不是用「null」这种既表示「没有」又表示「全部」的东西。

怎么守住写路径:读的那套用例,只覆盖了一半

第一集的验证方式是三层:空租户对照、伪造头连发、上下文泄漏。它们全部是读用例。写路径得另配一套。

项目里现成那个 saas-tenant-test.sh 覆盖了三件事:租户 1 的数字非空、空租户所有列表全空、租户禁用即时 403。

三条全是读。

写路径一条都没有。所以我按同样的风格补了一套「双租户写入对照」,结构是这样:

# A 写,B 查:B 必须看不到
A_TOKEN=$(sign_token 1 admin)
B_TOKEN=$(sign_token 2 admin)

OID=$(curl -s -X POST "$API_BASE/v1/admin/orders" \
        -H "Authorization: Bearer $A_TOKEN" \
        -d '{"storeId":1,"customerName":"测试客户","customerPhone":"13800138000",...}' \
      | jv data.id)

ck "B 查 A 的订单 → 404/空" \
   "$(api /v1/admin/orders/$OID -H "Authorization: Bearer $B_TOKEN")" '404'

# B 写,A 查:对称验证(防止只在一个方向做了校验)
...

三个关键点:

1. 每个写接口都要有「反向」用例。 只测「A 能写 A 的」没有意义——它本来就是对的。必须测「B 能不能写 A 的」和「A 能不能写 B 的」,两个方向都过才算。

2. 唯一性要单独造两个租户来测。 编号撞码只在「第二个租户」出现,所以用例必须真的开两个租户,各自建同一个 storeCode 的门店——biz_store.store_code 上没有任何唯一约束,两个租户同时写 001 是合法的,撞的只是质保单号。这条用例是我在坑 2 里栽过之后才补的:

# 两个租户都用 storeCode=001,同一天各建一张质保单
for T in "$A_TOKEN" "$B_TOKEN"; do
  create_warranty "$T" "001" || fail "质保单号冲突"
done

3. 并发要真并发。 配额那条用例,串行跑一百次也不会红:

seq 1 20 | xargs -P 20 -I{} curl -s -X POST "$API_BASE/v1/admin/stores" \
  -H "Authorization: Bearer $A_TOKEN" -d '{"storeName":"并发店{}"}' > /dev/null
ck "门店数不超过套餐上限" "$(api /v1/admin/tenants/1/usage | jv storeCount)" '^3$'

4. 异步要断言「副作用真的发生了」。 通知这类东西,测试断言不能只看接口返回 200,要去查通知表有没有行。这是唯一能抓住「静默 return」的办法。

上线前必查清单(写路径版)

  • 每个写接口都有归属校验吗?create 类接口最容易漏
  • 归属校验是 fail-open(不确定就放行)还是 fail-closed(不确定就拒绝)?
  • 所有唯一索引,逐个确认「全局唯一」是不是业务真的要求
  • 自动生成的编号,前缀里有没有租户标识?序号的作用域和索引的作用域一致吗?
  • 「查计数 → 判断 → 插入」的地方,有没有锁或唯一约束兜底
  • @Transactional 里切上下文的地方,存了 previous 吗?finally 是 restore 还是 clear?
  • TenantContext.get() 的每个调用点,会不会在无 HTTP 请求的线程里执行
  • 异步/定时入口,第一行有没有断言上下文(或显式传租户)
  • 定时任务的「跨租户」是显式写的,还是依赖 null 的副作用
  • 有没有「两个租户都开一遍」的写入用例

写在最后

第一集我说,多租户的命门是「这次请求属于哪个租户」。

写完这一篇,我更愿意把它拆成两句话:

读的时候,命门是「你看见了谁」; 写的时候,命门是「你改的是谁、撞的是谁、算的是谁」。

读隔离可以靠一个拦截器一次性解决,因为它是一个过滤器——漏了会多看见,但不会多改。 写隔离只能靠每个入口自己回答,因为它是一个归属判断——漏了就是改错、就是撞码、就是超配。

而这两件事的失败方式完全不同:读漏了,你会在屏幕上看到别人的数据,当场就发现;写漏了,一切看起来都正常,直到有人来对账。

如果你也在跑多租户系统,建议今晚就做一件小事:把所有带 create / insert / save 的 Service 方法列出来,看有几个传了 storeId 或类似的范围参数,又有几个真的校验了它。

这个数字,通常比你以为的少。


作者 | 老K写系统

10 年 Java,做过智能手环、电商、支付、健身四条业务线的多套上线系统,擅长多租户 SaaS 从 0 到生产交付,以及把 AI 接进企业老系统。有项目或岗位想聊,欢迎留言。