Docker中传递Java APM Agent配置致应用启动失败排查

问题场景 #

你本地手动执行带Elastic APM Agent的Java Jar启动命令可正常运行，在镜像构建完成后，尝试通过docker run传入APM配置时应用启动失败，对应命令为：

docker run --name app -e CATALINA_OPTS='-Dspring.config.location=/usr/local/tomcat/application-recette.properties,/usr/local/tomcat/application.yml' 
-e CATALINA_OPTS='-Delastic.apm.service_name=server' 
-e CATALINA_OPTS='-Delastic.apm.server_urls=http://10.128.0.4:8200' 
-e CATALINA_OPTS='-Delastic.apm.application_packages=package.com' 
-d -p 9000:8080 image:v1

核心根因定位 #

几个高频踩坑点会直接导致启动失败：

• 环境变量重复覆盖：Docker的-e参数对同一变量多次赋值时，后传入的值会完全覆盖之前所有赋值，不会自动追加拼接。上述命令重复定义了4次CATALINA_OPTS，最终容器内实际生效的配置只有最后一条-Delastic.apm.application_packages=package.com，前面的Spring配置路径、其他APM参数全部丢失，应用自然无法正常加载。
• JavaAgent核心参数遗漏：手动启动命令中最关键的-javaagent:../infrastructure/agent/apm-agent.jar加载指令，在Docker启动命令中完全没有传入。哪怕APM配置写的完全正确，没有指定Agent路径，Java进程根本不会加载APM Agent，所有相关配置都不会生效。
• 参数变量错位：CATALINA_OPTS是Tomcat官方镜像专用的JVM参数变量，如果你构建的是独立Jar运行的镜像，而非内置Tomcat的Web应用镜像，CATALINA_OPTS根本不会被启动脚本识别，传入的所有参数都不会加到Java启动命令中。
• 路径一致性问题：手动启动时Agent的相对路径为../infrastructure/agent/apm-agent.jar，需要确认镜像构建过程中，是否将apm-agent.jar文件正确拷贝到了容器内的可访问路径下，避免出现文件找不到的报错。
• 配置拼写偏差：你最初手动启动时配置的包路径是package.coù，Docker配置里写为package.com，需要核对实际的业务包名，避免包路径匹配错误。

排查与解决步骤 #

• 先确认镜像的启动机制
  执行docker inspect image:v1 | grep -E 'Entrypoint|Cmd'，查看镜像实际的启动入口和启动脚本：
  • 如果是Tomcat基础镜像，确认启动脚本是否自动加载CATALINA_OPTS变量；
  • 如果是独立Jar启动镜像，确认脚本读取的JVM参数变量名（常见为JAVA_OPTS，而非CATALINA_OPTS）。
• 修正环境变量赋值方式
  不要多次传入同一个环境变量，把所有JVM参数合并到同一组引号内，避免值被覆盖。
• 补全JavaAgent加载参数
  确认容器内apm-agent.jar的实际存储路径，将-javaagent:<容器内实际Agent路径>加入JVM参数列表。
• 临时以前台模式启动校验
  去掉启动命令中的-d参数，直接输出启动日志，逐项确认Java进程是否正确加载所有传入的JVM参数、APM服务地址是否网络可达。
• 参考正确启动命令示例
  以独立Jar镜像使用JAVA_OPTS变量、Agent存储在容器内/opt/agent/apm-agent.jar路径为例，修正后的启动命令为：

  docker run --name app \
    -e JAVA_OPTS="
      -javaagent:/opt/agent/apm-agent.jar
      -Delastic.apm.service_name=server
      -Delastic.apm.server_urls=http://10.128.0.4:8200
      -Delastic.apm.application_packages=package.com
      -Dspring.config.location=/usr/local/tomcat/application-recette.properties,/usr/local/tomcat/application.yml
    " \
    -d -p 9000:8080 image:v1
  

• 兜底校验方法
  容器启动后如果仍有异常，执行docker exec app env查看容器内实际生效的环境变量，和预期配置逐项比对，定位缺失的参数、拼写错误的配置。

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