Wildfly部署后Metaspace无法被GC清理问题排查求助

核心结论 #

org.jboss.modules.ModuleClassLoader无法被垃圾回收是导致Metaspace持续增长的直接原因——类元数据存储在Metaspace中，只要ClassLoader被强引用持有，其加载的所有类的元数据都无法被释放，最终触发java.lang.OutOfMemoryError: Metaspace。这个问题既可能和JBoss Modules的实现缺陷有关，也可能是应用自身资源未清理或配置遗漏导致的。

可能的原因分析 #

1. JBoss Modules的已知实现问题 #

Wildfly 17/18在搭配JDK 11及以上版本时，存在部分ModuleClassLoader泄漏的已知场景：

• 卸载部署时，JNDI绑定的资源未完全清理，残留的引用指向ModuleClassLoader
• MBean注册后未在卸载时注销，导致MBeanServer持有ClassLoader引用
• 线程上下文类加载器未在任务结束后重置，后台线程持续持有ModuleClassLoader
• 某些内置模块的全局引用未正确隔离，跨部署的引用导致ClassLoader无法回收

2. 应用层面的资源泄漏 #

• Spring/Hibernate资源未清理：Spring ApplicationContext未在卸载时调用close()方法，Hibernate SessionFactory未销毁；部分单例Bean通过静态变量、ThreadLocal持有ClassLoader或类实例，导致引用无法释放。
• 第三方库的静态缓存：某些依赖库使用静态集合（如HashMap）缓存类实例或对象，这些静态引用会绑定到当前ModuleClassLoader，卸载时无法被清理。
• 线程泄漏：应用中创建的自定义线程、定时任务线程未正确终止，且线程的上下文类加载器设置为ModuleClassLoader，导致ClassLoader被长期持有。

需检查的配置遗漏 #

Wildfly部署配置 #

• 确认是否启用强制卸载资源的属性：在standalone.xml或domain.xml中添加

  <system-properties>
      <property name="org.jboss.as.deployment.force-shutdown" value="true"/>
  </system-properties>
  

  该属性会强制卸载时关闭所有与部署相关的资源，减少残留引用。
• 检查jboss.modules.system.pkgs配置是否正确，确保系统类加载器与模块类加载器的边界清晰，避免不必要的引用交叉：

  <system-properties>
      <property name="jboss.modules.system.pkgs" value="com.sun,java.util,javax.servlet"/>
  </system-properties>
  

JVM参数优化 #

• 添加类加载/卸载跟踪参数，定位未被卸载的类：

  -XX:+TraceClassUnloading -XX:+TraceClassLoading
  

• 启用详细GC日志，分析Metaspace在GC前后的变化：

  -XX:+PrintGCDetails -XX:+PrintGCTimeStamps -XX:+PrintMetaspaceStatistics
  

Wildfly模块配置 #

• 避免将应用依赖配置为全局模块，全局模块会被所有部署共享，容易导致ClassLoader引用残留；
• 检查WAR包中的依赖与Wildfly内置模块是否冲突（如Hibernate版本不一致），冲突可能导致类重复加载，增加Metaspace占用且无法回收。

排查步骤 #

1. 定位强引用来源：在部署卸载后，使用jmap -dump:format=b,file=heap.hprof <PID>生成堆转储，通过MAT分析ModuleClassLoader的GC Roots，明确是哪个对象持有它的引用；
2. 检查服务器日志：查看Wildfly的server.log，确认卸载过程中是否有资源未关闭、MBean未注销等警告或错误；
3. 简化应用排查：逐步移除Spring/Hibernate的组件或第三方依赖，定位是否是某个特定组件导致的泄漏；
4. 升级Wildfly版本：尝试升级到Wildfly 20及以上版本，新版本修复了多个ModuleClassLoader泄漏的已知问题。

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