Spring Boot 3.3下配置THC_PORT与THC_PATH修复Paketo健康检查问题

问题根源 #

Spring Boot 3.3升级后，Paketo Buildpack的健康检查逻辑、环境变量传递机制发生变化，原有的Maven插件配置方式失效；直接设置THC_*运行时变量可能因优先级或配置覆盖问题，未被健康检查器正确读取。

解决方案 #

1. 构建阶段指定Paketo健康检查参数（推荐） #

Paketo支持通过构建时环境变量BP_HEALTH_CHECK_*直接配置健康检查规则，配置会固化到镜像中，无需运行时额外传参：

• 使用pack build命令时添加参数：

  pack build your-image-name \
    --env BP_HEALTH_CHECK_HTTP_PORT=8081 \
    --env BP_HEALTH_CHECK_HTTP_PATH=/health \
    --env BP_HEALTH_CHECK_TYPE=http
  

• 如果用Maven插件构建，在spring-boot-maven-plugin中配置Paketo构建环境变量：

  <plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
      <image>
        <env>
          <BP_HEALTH_CHECK_HTTP_PORT>8081</BP_HEALTH_CHECK_HTTP_PORT>
          <BP_HEALTH_CHECK_HTTP_PATH>/health</BP_HEALTH_CHECK_HTTP_PATH>
          <BP_HEALTH_CHECK_TYPE>http</BP_HEALTH_CHECK_TYPE>
        </env>
      </image>
    </configuration>
  </plugin>
  

2. 让Paketo自动读取Spring Boot健康端点配置 #

确保Spring Boot健康端点配置正确，Paketo会自动识别管理端口和端点路径：

• 在application.properties中配置：

  # 健康端点所在端口
  management.server.port=8081
  # 暴露健康端点
  management.endpoints.web.exposure.include=health
  # 调整健康端点路径（若不是默认的/actuator/health）
  management.endpoints.web.base-path=/
  management.endpoint.health.path=/health
  

  配置完成后，Paketo会自动检测上述参数，无需额外设置环境变量。

3. 自定义健康检查命令（兜底方案） #

若上述方法无效，可直接指定健康检查命令，绕过默认逻辑：

• 运行容器时指定健康检查规则：

  docker run -d \
    --name your-container \
    --health-cmd "curl -f http://localhost:8081/health" \
    --health-interval 10s \
    --health-timeout 5s \
    your-image-name
  

• 或构建时通过Paketo变量固化命令：

  pack build your-image-name \
    --env BP_HEALTH_CHECK_CMD="curl -f http://localhost:8081/health" \
    --env BP_HEALTH_CHECK_TYPE=cmd
  

验证步骤 #

1. 构建镜像后，进入容器执行echo $BP_HEALTH_CHECK_HTTP_PORT确认变量已正确设置；
2. 手动执行curl http://localhost:8081/health，确认端点返回{"status":"UP"}；
3. 查看容器健康状态：docker inspect --format='{{.State.Health.Status}}' your-container，确认状态为healthy。

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