主题
多租户
一句话:租户号是「请求级上下文」,入口由
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 | 做什么 | 为什么在这个位置 |
|---|---|---|---|
| -104 | TenantContextWebFilter | 从 header tenant-id 取值,setTenantId;finally 里 clear() | 必须早于访问日志(日志要带租户),也早于所有业务 Filter |
| -100 | Spring Security 链(含 TokenAuthenticationFilter) | 解析 token,得到 LoginUser.tenantId | 平台安全链的固定位置,见 WebFilterOrderEnum#L28 注释 |
| -99 | TenantSecurityWebFilter | 校验「请求租户」=「登录用户租户」;非忽略 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」+「扫出来的@TenantIgnoreURL」的并集(同文件#L113-L132);命中且请求没带租户时setIgnore(true)(#L105),SQL 侧就整体不拼租户条件。
3. TenantContextHolder:为什么是 TTL
core/context/TenantContextHolder.java:
| 行 | 内容 | 作用 |
|---|---|---|
#L16 | TransmittableThreadLocal<Long> TENANT_ID | 线程池复用线程时也能带上租户 |
#L21 | TransmittableThreadLocal<Boolean> IGNORE | 「本次不拼租户」的开关 |
#L37-L44 | getRequiredTenantId() 无租户抛 NullPointerException | 漏建上下文时快速失败,不静默查全表 |
#L59-L61 | isIgnore() 用 Boolean.TRUE.equals | 避免拆箱空指针 |
#L63-L66 | clear() | 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-L43 | new 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 的三个落点
| 标注位置 | 生效范围 | 收集方式 |
|---|---|---|
| 方法 | 仅该方法内的 SQL | TenantIgnoreAspect#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、Stream | TenantRedisMessageInterceptor 发送前写 header、消费前 setTenantId、消费后 clear(core/mq/redis/TenantRedisMessageInterceptor.java#L21-L40) | 平台内唯一「收发都管」的实现之一 |
| RabbitMQ | TenantRabbitMQInitializer 只给 RabbitTemplate 加 beforePublish 处理器(#L16-L22) | 只有生产端,消费端要自己 TenantUtils.execute |
| RocketMQ | TenantRocketMQInitializer 同时注册 send hook 与 consume hook | 消费 hook 要求单条消息(Assert) |
| Kafka | TenantKafkaEnvironmentPostProcessor 往 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. 怎么验证
- 看当前上下文:在 Service 打断点或加日志,输出
TenantContextHolder.getTenantId()与isIgnore();请求带tenant-id时应等于 header,@TenantIgnore内应为true。 - 看真实 SQL:开 MyBatis SQL 日志,确认
WHERE tenant_id = ?出现在 count 与 list 两条 SQL 上;分页 SQL 里如果 count 没有,说明插件顺序被改坏了。 - 看缓存 key:
redis-cli KEYS 'user_role_ids*',应看到user_role_ids:1、user_role_ids:2;事务内清缓存要等提交后再看。 - 看 MQ 消费:消费端第一行打印租户号;RabbitMQ/Kafka 无拦截器时必然是
null。 - 看任务:
DemoJob(pmforge-module-system/.../job/DemoJob.java#L20-L23)同时打印租户号并查一次adminUserMapper,能在日志里看到每个租户一组输出,就说明 SQL 与上下文都生效。
10. 排错清单
| 症状 | 先看 | 判断依据 |
|---|---|---|
NullPointerException 提示缺少租户 | TenantContextHolder#L37-L44 | 上下文没建:Filter 没走到,或线程池没传 TTL |
| 400「请求的租户标识未传递」 | TenantSecurityWebFilter#L87-L107 | URL 不在忽略名单,且 header 没带 tenant-id |
| 403「您无权访问该租户的数据」 | 同文件 #L69-L84 | 登录用户租户 ≠ 请求租户,检查前端切换租户逻辑 |
SQL 里没有 tenant_id | TenantDatabaseInterceptor#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 返回为空 |