排查多租户内存残留需聚焦ThreadLocal未清理、TTL传播异常、静态强引用及上下文生命周期错配:先用jstack/Arthas查线程级上下文持有,再用jmap分析实例数,结合GC日志确认老年代残留,最后审计静态变量、缓存key设计与clear()的try-finally覆盖。
排查多租户架构中因租户上下文强引用导致的内存残留,核心在于定位“本该随请求结束而释放,却因强持有未被回收”的对象。这类问题常表现为 jvm 堆内存持续增长、old gc 频繁、full gc 后仍无法释放,且现象与高并发租户请求强相关。
确认是否为 ThreadLocal 引发的租户上下文残留
这是最常见路径。ThreadLocal 本身不自动清理,若线程来自线程池(如 Tomcat 线程池、Dubbo 线程池),而业务代码未在请求收尾处调用 remove(),旧租户的 TenantContext 实例就会一直挂在该线程上。
- 用
jstack或 Arthas 的thread -n 10查看活跃线程堆栈,重点关注http-nio-、pool-类命名的线程,观察其ThreadLocalMap中是否存有非空的租户 ID 字符串或上下文对象 - 用
jmap -histo:live <pid></pid>统计实例数,筛选出疑似租户上下文类(如TenantContextHolder、TenantContext)是否长期驻留且数量与活跃租户数严重不匹配 - 启用 JVM 参数
-XX:+PrintGCDetails -XX:+PrintGCTimeStamps,结合 GC 日志判断老年代对象是否稳定不降——若某类对象在 Full GC 后仍大量存活,极可能被线程强引用持有着
检查 InheritableThreadLocal 和 TransmittableThreadLocal 的传播链断裂点
子线程(如异步任务、定时任务、Feign 调用线程)若继承了父线程的租户上下文但未正确清理,也会造成残留。特别是使用 TransmittableThreadLocal(TTL)时,若未配合 TtlRunnable/TtlCallable 包装,或在线程池 submit 时遗漏 TtlExecutors 代理,则上下文会“漏传”或“错传”,进而引发误绑定与残留。
- 检查所有
ExecutorService创建点,确认是否统一使用TtlExecutors.getTtlExecutorService()包装 - 搜索项目中所有
new Thread()、CompletableFuture.supplyAsync()、@Scheduled方法,验证是否显式传递并清理租户上下文 - 用 Arthas 的
watch命令监控TtlThreadLocal.get()返回值,在子线程入口处打印当前租户 ID,确认是否出现“不该出现的租户”或“空租户但上下文未清”
扫描静态单例与缓存容器中的隐式强引用
除 ThreadLocal 外,静态变量、Spring 单例 Bean、本地缓存(Caffeine/ConcurrentHashMap)若直接持有租户上下文对象(而非仅 tenant_id 字符串),也可能阻止 GC。
- 用 JProfiler 或 VisualVM 的“Classes”视图,按“Live Instances”排序,查找自定义上下文类的实例是否集中在某个静态字段下
- 检查所有
@Component或@Service类中是否存在private static TenantContext、private static Map<string tenantcontext></string>等结构 - 审查本地缓存 key 构造逻辑:是否误将整个
TenantContext对象作为 key(应只用tenantId字符串);若用了对象,确认其equals/hashCode是否合理,避免哈希冲突导致假性堆积
验证租户上下文生命周期是否与请求严格对齐
上下文应在 Filter/Interceptor 的 doFilter() 或 preHandle() 中注入,在 finally 块中 clear();若放在 Controller 层手动 set/remove,极易遗漏异常分支。
- 检查所有租户中间件实现,确认
clear()是否包裹在try-finally中,而非仅放在正常流程末尾 - 用单元测试模拟异常场景(如 Controller 抛出 RuntimeException),验证上下文是否仍被残留
- 在关键 clear() 调用前加日志,如
log.debug("Clear tenant context for {}", TenantContext.getTenantId()),上线后观察日志是否完整覆盖所有请求路径

















