Dockerfile 中 ENTRYPOINT 与 CMD 的深度解析

一、核心概念与 Spring Boot 场景适配

在 Docker 化 Spring Boot 应用时，CMD 和 ENTRYPOINT 是控制容器启动行为的关键指令。它们的核心区别如下：

二、Spring Boot 项目基础准备

假设我们有一个标准的 Spring Boot 项目，打包后的 jar 文件名为 demo-1.0.0.jar（位于 Docker 构建上下文的 target/ 目录）。该 jar 包默认通过 java -jar demo-1.0.0.jar 启动，支持通过命令行参数指定端口（如 --server.port=8081）或 JVM 参数（如 -Xms256m）。

三、实战案例：不同配置组合解析

案例 1：基础配置（推荐 exec 形式组合）

​​需求​​：固定使用 java -jar 启动 jar 包，但允许通过 docker run 覆盖默认参数（如修改端口）。

# 使用官方 OpenJDK 镜像（根据实际需求选择版本，如 17-jdk-slim）
FROM eclipse-temurin:17-jdk-jammy

# 将构建好的 jar 包复制到容器中（假设 jar 在宿主机的 target/ 目录）
COPY target/demo-1.0.0.jar /app/demo.jar

# 推荐：ENTRYPOINT 固定启动命令，CMD 提供默认参数
ENTRYPOINT ["java", "-jar", "/app/demo.jar"]  # 固定启动逻辑（exec 形式）
CMD ["--server.port=8080"]                   # 默认端口 8080（可被覆盖）

​​构建与运行​​：

# 构建镜像
docker build -t springboot-entrypoint-demo .

# 运行容器（使用默认端口 8080）
docker run -p 8080:8080 springboot-entrypoint-demo
# 实际命令：java -jar /app/demo.jar --server.port=8080

# 覆盖默认端口（通过 CMD 传递新参数）
docker run -p 8081:8081 springboot-entrypoint-demo --server.port=8081
# 实际命令：java -jar /app/demo.jar --server.port=8081

​​关键点​​：

• ENTRYPOINT 固定了 java -jar /app/demo.jar 的核心逻辑（exec 形式确保 Spring Boot 进程 PID=1，能直接接收 SIGTERM 信号）。
• CMD 提供了默认参数 --server.port=8080，但用户可通过 docker run 的末尾参数覆盖它（覆盖的是 CMD 的内容，而非 ENTRYPOINT）。

案例 2：灵活调试（Shell 形式与参数分离）

​​需求​​：开发阶段需要快速调整 JVM 参数（如内存）和启动参数，不固定默认值。

FROM eclipse-temurin:17-jdk-jammy

COPY target/demo-1.0.0.jar /app/demo.jar

# Shell 形式（不推荐生产环境！仅用于调试）
CMD java -jar /app/demo.jar  # 直接作为默认命令（无 ENTRYPOINT）

​​运行示例​​：

# 使用默认命令（无额外参数）
docker run -p 8080:8080 springboot-entrypoint-demo
# 实际命令：java -jar /app/demo.jar（默认端口 8080）

# 覆盖为自定义 JVM 参数和端口
docker run -p 8081:8081 springboot-entrypoint-demo java -Xms512m -Xmx1024m -jar /app/demo.jar --server.port=8081
# 注意：此时需要手动写全命令（因为没有 ENTRYPOINT 固定逻辑）

​​问题​​：

• Shell 形式的 CMD 会通过 /bin/sh -c 执行命令，导致 Spring Boot 进程不是 PID=1，可能无法正确接收 docker stop 发送的 SIGTERM 信号（容器停止时应用不会优雅关闭）。
• 生产环境务必使用 exec 形式！

案例 3：生产级配置（ENTRYPOINT 脚本 + 动态参数）

​​需求​​：在启动前执行初始化逻辑（如检查配置文件、打印环境信息），同时固定 jar 启动命令，允许覆盖参数。

步骤 1：创建初始化脚本 entrypoint.sh

#!/bin/bash
# entrypoint.sh

# 打印环境信息（调试用）
echo "===== 容器启动环境 ====="
echo "JAVA_HOME: $JAVA_HOME"
echo "当前时间: $(date)"
echo "传入的额外参数: $@"  # $@ 是 docker run 传递给 CMD 的参数

# 检查 jar 包是否存在
if [ ! -f "/app/demo.jar" ]; then
  echo "错误：未找到 /app/demo.jar 文件！"
  exit 1
fi

# 执行核心命令（exec 确保 Spring Boot 进程 PID=1）
exec java -jar /app/demo.jar "$@"

步骤 2：Dockerfile 配置

FROM eclipse-temurin:17-jdk-jammy

# 复制 jar 包和初始化脚本
COPY target/demo-1.0.0.jar /app/demo.jar
COPY entrypoint.sh /app/entrypoint.sh

# 赋予脚本执行权限
RUN chmod +x /app/entrypoint.sh

# ENTRYPOINT 固定为脚本，CMD 提供默认参数
ENTRYPOINT ["/app/entrypoint.sh"]  # exec 形式（脚本内再用 exec 启动 jar）
CMD ["--server.port=8080"]         # 默认参数

​​构建与运行​​：

# 构建镜像
docker build -t springboot-entrypoint-script-demo .

# 运行容器（使用默认端口 8080）
docker run -p 8080:8080 springboot-entrypoint-script-demo
# 实际流程：entrypoint.sh 打印日志 → 执行 exec java -jar /app/demo.jar --server.port=8080

# 覆盖默认端口（通过 CMD 传递新参数）
docker run -p 8082:8082 springboot-entrypoint-script-demo --server.port=8082
# 实际流程：entrypoint.sh 打印日志 → 执行 exec java -jar /app/demo.jar --server.port=8082

# 传递额外参数（如 Spring Boot 的 --spring.profiles.active）
docker run -p 8080:8080 springboot-entrypoint-script-demo --server.port=8080 --spring.profiles.active=prod
# 实际流程：entrypoint.sh 打印日志 → 执行 exec java -jar /app/demo.jar --server.port=8080 --spring.profiles.active=prod

​​优势​​：

• 脚本可扩展性强（例如添加数据库连接检查、配置文件生成逻辑）。
• exec java -jar 确保 Spring Boot 进程接收信号，实现优雅停机（docker stop 时会触发 Spring Boot 的 shutdown hook）。
• 默认参数通过 CMD 提供，兼顾灵活性和安全性。

四、常见问题与解决方案（Spring Boot 场景）

问题 1：容器启动后立即退出

​​现象​​：docker run 后容器状态为 "Exited (1)"。
​​排查步骤​​：

1. 检查 jar 包路径是否正确（COPY 是否复制到 /app/demo.jar）。
2. 查看容器日志：docker logs <container_id>（如果 ENTRYPOINT 有打印日志）。
3. 确认 jar 包本身能否正常启动（本地运行 java -jar demo-1.0.0.jar 测试）。

​​常见原因​​：

• jar 包未正确打包（缺少依赖或主类配置错误）。
• Dockerfile 中 jar 包路径与 ENTRYPOINT/CMD 中的路径不一致。

问题 2：参数覆盖不生效

​​错误示例​​：

# 错误：混合使用 shell 形式和参数传递
CMD java -jar /app/demo.jar --server.port=8080  # 如果同时有 ENTRYPOINT，可能被错误拼接

​​修正方案​​：

• 统一使用 exec 形式（推荐）：

  ENTRYPOINT ["java", "-jar", "/app/demo.jar"]
  CMD ["--server.port=8080"]

• 若必须用 Shell 形式，确保参数拼接正确（但不推荐）：

  ENTRYPOINT java -jar /app/demo.jar  # shell 形式
  CMD "--server.port=8080"            # 会被拼接到 ENTRYPOINT 后

问题 3：优雅停机失效

​​现象​​：docker stop 后 Spring Boot 服务未及时关闭（线程池未清理）。
​​原因​​：ENTRYPOINT 或 CMD 使用了 Shell 形式（如 CMD java -jar /app/demo.jar），导致 Spring Boot 进程不是 PID=1，无法接收 SIGTERM 信号。

​​解决方案​​：

• 必须使用 exec 形式（ENTRYPOINT ["java", "-jar", "/app/demo.jar"] 或通过脚本内 exec 启动）。
• 确保 Spring Boot 应用配置了 shutdown hook（默认已启用，无需额外配置）。

五、最佳实践总结（Spring Boot 专项）

1. ​​生产环境必备​​：

   • 使用 ENTRYPOINT 固定 java -jar 核心逻辑（exec 形式），CMD 提供默认参数（如端口、profile）。
   • 推荐通过脚本封装初始化逻辑（如环境检查），但脚本内必须用 exec 启动 jar 包以保证 PID=1。

2. ​​开发环境灵活调整​​：

   • 可通过 docker run 末尾参数覆盖 CMD 的默认值（如修改端口或 profile）。
   • 调试时可用 docker run -it --entrypoint /bin/bash 进入容器手动启动 jar 包。

3. ​​信号与优雅停机​​：

   • 始终避免 Shell 形式（如 CMD java -jar ...），确保 Spring Boot 进程直接接收操作系统信号。

4. ​​镜像优化​​：

   • 使用多阶段构建减少镜像体积（例如从 Maven 构建阶段复制 jar 到精简的 JDK 运行时镜像）。

通过以上 Spring Boot 专属案例，开发者可以清晰掌握如何在不同场景下合理使用 ENTRYPOINT 和 CMD，构建出既稳定又灵活的容器化应用。