使用Apache Ignite时Tomcat停服触发ThreadLocal移除失败报错

典型报错场景 #

应用日常运行状态完全正常，但停止Tomcat容器时，日志输出大量WebappClassLoader的ThreadLocal泄漏检测错误，所有未清理的ThreadLocal均来自Ignite内部组件，业务代码没有主动创建ThreadLocal：

SEVERE: Web应用[/webapp-name]创建了类型为[org.apache.ignite.internal.binary.BinaryThreadLocalContext$1]的ThreadLocal键（值为[org.apache.ignite.internal.binary.BinaryThreadLocalContext$1@5826d221]），关联的值类型为[org.apache.ignite.internal.binary.BinaryThreadLocalContext]（值为[org.apache.ignite.internal.binary.BinaryThreadLocalContext@47a32716]），但在Web应用停止时未能完成该ThreadLocal的移除。容器将通过周期性刷新线程的方式尽可能规避潜在的内存泄漏风险。
Apr 08, 2021 10:39:34 AM org.apache.catalina.loader.WebappClassLoaderBase checkThreadLocalMapForLeaks
SEVERE: Web应用[/webapp-name]创建了类型为[java.lang.ThreadLocal]的ThreadLocal键（值为[java.lang.ThreadLocal@63b81d02]），关联的值类型为[org.apache.ignite.internal.marshaller.optimized.OptimizedObjectStreamRegistry.StreamHolder]（值为[org.apache.ignite.internal.marshaller.optimized.OptimizedObjectStreamRegistry$StreamHolder@58474af2]），但在Web应用停止时未能完成该ThreadLocal的移除。容器将通过周期性刷新线程的方式尽可能规避潜在的内存泄漏风险。
Apr 08, 2021 10:39:34 AM org.apache.catalina.loader.WebappClassLoaderBase checkThreadLocalMapForLeaks
SEVERE: Web应用[/webapp-name]创建了类型为[java.lang.ThreadLocal.SuppliedThreadLocal]的ThreadLocal键（值为[java.lang.ThreadLocal$SuppliedThreadLocal@67782fee]），关联的值类型为[org.apache.ignite.internal.binary.BinaryContextHolder]（值为[org.apache.ignite.internal.binary.BinaryContextHolder@482bfe01]），但在Web应用停止时未能完成该ThreadLocal的移除。容器将通过周期性刷新线程的方式尽可能规避潜在的内存泄漏风险。

问题根因 #

• 这类报错是Tomcat内置的类加载泄漏检测逻辑触发的：Ignite在初始化阶段，会把二进制序列化上下文、对象流复用器等组件的状态以ThreadLocal的形式绑定到Tomcat公共线程池的工作线程上。
• 当Web应用停止时，如果没有触发Ignite实例的全资源清理流程，这些绑定在公共线程上的ThreadLocal条目就会持有Web应用类加载器的引用，导致类加载器无法被GC回收，最终形成热部署场景下的元空间泄漏。
• 日志里提到的三类未清理ThreadLocal，全部是Ignite内部的组件实现，和业务代码的ThreadLocal使用没有关系。

正确清理操作步骤 #

• 第一优先级：在Web应用的销毁回调中触发Ignite的优雅停机流程。在实现了ServletContextListener的上下文销毁方法中，调用Ignition.stop(igniteInstanceName, true)关闭对应Ignite节点，第二个参数传入true代表等待所有内部线程停止、序列化上下文释放、绑定的ThreadLocal完成主动清理后再退出，不要使用无参的快速停机接口。
• 兜底清理：如果完成Ignite优雅停机后仍有残留的ThreadLocal条目，可在应用销毁阶段遍历Tomcat公共工作线程池的所有线程，通过反射读取每个线程的threadLocals属性（即ThreadLocalMap），仅移除key属于Ignite内部类的条目，不要全量清空所有ThreadLocal值，避免误清其他组件的上下文。
• 根源解决：将Ignite核心依赖从Web应用的WEB-INF/lib目录移动到Tomcat的全局lib目录，由容器级类加载器加载Ignite类。这种模式下Web应用卸载时不会触发针对Ignite类的ThreadLocal泄漏检测，从配置层面消除这类报错。

常见错误处理方式 #

• 不要直接修改Tomcat源码或配置关闭WebappClassLoader的ThreadLocal泄漏检测逻辑，类加载泄漏是真实存在的风险，长期热部署会快速消耗元空间内存，最终触发OutOfMemoryError: Metaspace。
• 不要在Ignite节点仍处于运行状态时直接中断Web容器进程，这种半停机状态下Ignite的内部组件不会触发资源清理，必然会输出泄漏日志，还可能导致缓存数据落盘异常。

内容的提问来源于stack exchange，提问作者Midulaj