Docker环境下PDFBox合并4GB大PDF失败，求参数排查方案

一、优化PDFBox的MemoryUsageSetting配置 #

• 不要依赖默认内存配置，手动指定内存阈值，强制PDFBox在内存紧张时使用磁盘缓存：
  • 优先尝试纯堆内存模式，给JVM留足非堆开销：MemoryUsageSetting.setupMainMemoryOnly(5120)（单位MB，即5GB堆内存用于PDF处理，剩余1GB给JVM自身）。
  • 若纯堆模式仍崩溃，切换到堆+磁盘混合模式：MemoryUsageSetting.setupMixed(4096, 1024, true)，设置4GB堆内存、1GB磁盘缓存，开启临时文件自动清理。
• 原理：合并千级PDF时，每个文档的结构元数据会占用内存，手动配置MemoryUsageSetting能避免PDFBox无限制占用堆内存。

二、调整JVM非堆与GC参数 #

• 除了-Xmx6g的堆内存设置，必须补充以下参数：
  • 添加-XX:MaxDirectMemorySize=2g：PDFBox大量使用直接内存处理IO，限制直接内存上限可避免溢出。
  • 启用G1垃圾回收器：-XX:+UseG1GC -XX:MaxGCPauseMillis=200，G1更适合大内存场景，能有效减少Full GC导致的停顿或崩溃。
  • 开启堆转储：-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/tmp/heapdump.hprof，生成崩溃时的堆快照，方便定位内存泄漏点。

三、Docker容器的资源细节排查 #

• 检查CPU配额：合并PDF是CPU密集型操作，若容器CPU被限制（如仅1核），会导致GC停顿过长触发崩溃。用docker stats查看CPU使用率，必要时通过--cpus 4增加CPU配额。
• 配置swap内存：默认Docker容器可能禁用swap，堆内存不足时直接崩溃。启动容器时添加--memory 6g --memory-swap -1，允许JVM在内存紧张时使用swap缓冲。

四、PDFBox合并策略优化 #

• 分批合并：不要一次性加载1000+个PDF，先每100个合并为一个中间文件，再合并所有中间文件，大幅降低单次内存占用。
• 关闭不必要功能：合并时禁用字体缓存（PDFont.setCacheEnabled(false)），避免缓存大量字体占用内存；若源PDF无表单，关闭XFA处理（PDDocument.setXFAEnabled(false)）。

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