Skip to content

多租户 ​

一句话:租户号是「请求级上下文」,入口由 TenantContextWebFilter 写进 TenantContextHolder(TTL),随后 SQL、Redis 缓存、MQ、Job、WebSocket 各自读它做隔离;业务代码不感知租户,只在全局表上标 @TenantIgnore。

适用场景:新增租户维度的表、写跨租户的定时任务/管理接口、排查「A 租户看到 B 租户数据」或「SQL 报 tenant_id 不存在」。

不适用场景:只是某个用户看不到数据(那是数据权限);租户的开通、套餐、过期(那是 SYS-TENANT-01)。

1. 全景:一个租户号走完五条链路 ​

text
请求 Header: tenant-id
  └─ TenantContextWebFilter(-104)  写 TenantContextHolder(TTL)
       └─ TokenAuthenticationFilter(-100 内)  读 LoginUser.tenantId 并校验一致
            └─ TenantSecurityWebFilter(-99)  非忽略 URL 校验租户存在
                 ├─ SQL:TenantLineInnerInterceptor 拼 tenant_id = ?
                 ├─ 缓存:TenantRedisCacheManager 给 cache name 加 :tenantId
                 ├─ MQ:Redis interceptor / RabbitMQ 生产者 / RocketMQ / Kafka 写 header
                 └─ Job:TenantJobAspect 按租户循环

2. 入口:两个 Filter 的分工与顺序 ​

顺序Filter做什么为什么在这个位置
-104TenantContextWebFilter从 header tenant-id 取值,setTenantId;finally 里 clear()必须早于访问日志(日志要带租户),也早于所有业务 Filter
-100Spring Security 链(含 TokenAuthenticationFilter)解析 token,得到 LoginUser.tenantId平台安全链的固定位置,见 WebFilterOrderEnum#L28 注释
-99TenantSecurityWebFilter校验「请求租户」=「登录用户租户」;非忽略 URL 校验租户存在必须晚于 Security,才能拿到登录用户
  • TenantContextWebFilter 只负责「取」,不负责「校验」:WebFrameworkUtils.getTenantId 解析 header(pmforge-spring-boot-starter-web/.../WebFrameworkUtils.java#L50-L52),非数字返回 null。
  • TenantSecurityWebFilter 才负责校验:未登录时只做 URL 白名单判断;已登录时先比 tenant-id 与 LoginUser.tenantId,不一致直接 FORBIDDEN("您无权访问该租户的数据",TenantSecurityWebFilter.java#L76);非忽略 URL 且没带 tenant-id 则 BAD_REQUEST,带了则走 tenantFrameworkService.validTenant(同文件 #L87-L107)。
  • 忽略判定是「配置里的 ignore-urls」+「扫出来的 @TenantIgnore URL」的并集(同文件 #L113-L132);命中且请求没带租户时 setIgnore(true)(#L105),SQL 侧就整体不拼租户条件。

3. TenantContextHolder:为什么是 TTL ​

core/context/TenantContextHolder.java:

行内容作用
#L16TransmittableThreadLocal<Long> TENANT_ID线程池复用线程时也能带上租户
#L21TransmittableThreadLocal<Boolean> IGNORE「本次不拼租户」的开关
#L37-L44getRequiredTenantId() 无租户抛 NullPointerException漏建上下文时快速失败,不静默查全表
#L59-L61isIgnore() 用 Boolean.TRUE.equals避免拆箱空指针
#L63-L66clear()Filter finally 必须调用,防止污染下一次请求

TTL 只是「能传递」,真正传递靠两处装饰:@Async 由 PmforgeAsyncAutoConfiguration 给线程池装 TtlRunnable::get;Security 上下文由 PmforgeSecurityAutoConfiguration 换掉 SecurityContextHolder 的策略(见定时任务与异步)。

4. SQL 侧:TenantLineInnerInterceptor ​

注册在 PmforgeTenantAutoConfiguration#L77-L85:先建 TenantLineInnerInterceptor(handler 是 TenantDatabaseInterceptor),再用 MyBatisUtils.addInterceptor(interceptor, inner, 0) 插到索引 0——#L82-L83 的注释写明「需要排在分页插件前面」,这是 MyBatis-Plus 的硬要求(分页会先算 count,晚于租户会导致 count SQL 漏条件)。

是否拼条件由 TenantDatabaseInterceptor 决定:

方法行逻辑
getTenantId()#L41-L43new LongValue(TenantContextHolder.getRequiredTenantId())
ignoreTable()#L46-L61全局忽略 → 直接 true;否则剥掉反引号后查缓存 ignoreTables
computeIgnoreTable()#L68-L81找不到 TableInfo → true;DO 继承 TenantBaseDO → false;类上 @TenantIgnore → true

TenantBaseDO 只比 BaseDO 多一个 tenantId 字段(core/db/TenantBaseDO.java#L14-L19),因此「要不要租户隔离」这个决定落在实体继承关系上,不落在建表 SQL 或配置里。tenant_id 的赋值与查询条件都由 TenantLineInnerInterceptor 负责(INSERT 补列、SELECT/UPDATE/DELETE 补 WHERE),业务代码不要手写。

5. @TenantIgnore 的三个落点 ​

标注位置生效范围收集方式
方法仅该方法内的 SQLTenantIgnoreAspect#L24-L37:@Around("@annotation(tenantIgnore)"),enable 支持 SpEL,finally 还原
Controller 类该类所有 URL 跳过租户校验启动时扫 RequestMappingHandlerMapping,把 patterns/pathPatterns 放进 ignoreUrls(PmforgeTenantAutoConfiguration#L135-L158)
DO 类该表全局不拼租户条件TenantDatabaseInterceptor#L68-L81 读类注解,表名进 ignoreTables

坑:方法上的 @TenantIgnore 只影响 SQL,不会让 URL 进入忽略名单。想让某个接口「不登录也能访问 / 不带租户也能访问」,要标在 Controller 类上,或写进 pmforge.tenant.ignore-urls。

6. Redis 缓存:name 加租户后缀 ​

TenantRedisCacheManager#L37-L48 在 getCache(name) 时判断三件事:没开 ignore、有租户、names[0] 不在 ignore-caches 里,就把 name 改成 name + ":" + tenantId 再交给父类。因此:

  • @Cacheable("user_role_ids") 在租户 1 下实际 key 前缀是 user_role_ids:1,不同租户天然隔离,注解里不用写 tenantId。
  • 全局缓存(字典、短信模板、邮件模板等)要配进 pmforge.tenant.ignore-caches;application.yaml#L319-L328 已列了 user_role_ids、permission_menu_ids、oauth_client、notify_template 等 9 项,加新缓存时先想清楚它是「租户内」还是「全局」。
  • #L18 注释里的「后缀」指 cache 名可能带 #ttl(SPLIT="#",#L25),所以比较忽略名单只用 names[0]。
  • 清缓存时机:自动配置里 cacheManager.setTransactionAware(true)(PmforgeTenantAutoConfiguration#L212),@Transactional 内的 @CacheEvict/@CachePut 会延迟到事务提交后执行,避免「缓存清了、事务回滚了」。

7. MQ / Job / WebSocket 的透传 ​

链路透传方式注意
Redis Pub/Sub、StreamTenantRedisMessageInterceptor 发送前写 header、消费前 setTenantId、消费后 clear(core/mq/redis/TenantRedisMessageInterceptor.java#L21-L40)平台内唯一「收发都管」的实现之一
RabbitMQTenantRabbitMQInitializer 只给 RabbitTemplate 加 beforePublish 处理器(#L16-L22)只有生产端,消费端要自己 TenantUtils.execute
RocketMQTenantRocketMQInitializer 同时注册 send hook 与 consume hook消费 hook 要求单条消息(Assert)
KafkaTenantKafkaEnvironmentPostProcessor 往 interceptor.classes 追加生产者拦截器同样只有生产端
定时任务@TenantJob → TenantJobAspect 取全部租户,parallelStream 逐个 TenantUtils.execute(core/job/TenantJobAspect.java#L34-L56)Handler 必须幂等,失败重试会让已成功租户重跑
WebSocket 入站JsonWebSocketMessageHandler#L76-L77 从 session 取租户,TenantUtils.execute 包裹 onMessage出站广播的租户过滤见下
WebSocket 出站WebSocketSessionManagerImpl#L92-L113,上下文租户非空时只保留同租户 session#L104 是 if (contextTenantId != null):上下文为空就不过滤

手工补上下文用 TenantUtils:execute(Long, Runnable/Callable) 会强制 setIgnore(false) 并在结束后还原(core/util/TenantUtils.java#L26-L64);executeIgnore 反之(#L71-L99);跨服务传 header 用 addTenantHeader(#L107-L111,header 名与 Web 端一致)。

8. 常见坑 ​

坑表现处理
新表忘了继承 TenantBaseDO查询不带 tenant_id,数据串租户让 DO 继承 TenantBaseDO;全局表则显式标 @TenantIgnore
方法上标 @TenantIgnore 却仍被拦不带租户访问报 400/403改标 Controller 类,或加 pmforge.tenant.ignore-urls
定时任务跨租户一个任务只跑了一个租户 / 重复跑用 @TenantJob;全局清理用 @TenantIgnore(示例 JobLogCleanJob#L33)
MQ 消费丢上下文消费端 getRequiredTenantId() 抛 NPE,或查出全量Redis/RocketMQ 有拦截器;RabbitMQ/Kafka 消费端自己 TenantUtils.execute
WebSocket 广播串租户A 租户收到 B 租户通知检查消费线程是否有租户上下文,#L104 的空上下文分支不设防
缓存跨租户读到别人的全局缓存出现在租户内 / 租户缓存不失效ignore-caches 只放真全局的;名字变更会重新生成 key,老 key 需手工清

9. 怎么验证 ​

  1. 看当前上下文:在 Service 打断点或加日志,输出 TenantContextHolder.getTenantId() 与 isIgnore();请求带 tenant-id 时应等于 header,@TenantIgnore 内应为 true。
  2. 看真实 SQL:开 MyBatis SQL 日志,确认 WHERE tenant_id = ? 出现在 count 与 list 两条 SQL 上;分页 SQL 里如果 count 没有,说明插件顺序被改坏了。
  3. 看缓存 key:redis-cli KEYS 'user_role_ids*',应看到 user_role_ids:1、user_role_ids:2;事务内清缓存要等提交后再看。
  4. 看 MQ 消费:消费端第一行打印租户号;RabbitMQ/Kafka 无拦截器时必然是 null。
  5. 看任务:DemoJob(pmforge-module-system/.../job/DemoJob.java#L20-L23)同时打印租户号并查一次 adminUserMapper,能在日志里看到每个租户一组输出,就说明 SQL 与上下文都生效。

10. 排错清单 ​

症状先看判断依据
NullPointerException 提示缺少租户TenantContextHolder#L37-L44上下文没建:Filter 没走到,或线程池没传 TTL
400「请求的租户标识未传递」TenantSecurityWebFilter#L87-L107URL 不在忽略名单,且 header 没带 tenant-id
403「您无权访问该租户的数据」同文件 #L69-L84登录用户租户 ≠ 请求租户,检查前端切换租户逻辑
SQL 里没有 tenant_idTenantDatabaseInterceptor#L46-L81表被判成忽略:未继承 TenantBaseDO,或 DO 上标了 @TenantIgnore
SQL 里多出 tenant_id 导致报错同上全局表(配置、任务、文件、代码生成)应标 @TenantIgnore,见 pmforge-module-infra 的 ConfigDO、JobDO
缓存读不到刚写的数据TenantRedisCacheManager#L37-L48 + #L212写缓存时无租户上下文(异步线程),key 少了 :tenantId
任务只跑了一个租户TenantJobAspect#L37-L46没用 @TenantJob,或 tenantFrameworkService.getTenantIds 返回为空