--health-start-period不是可选项而是必调项，因为Spring Boot等应用启动需40–90秒，未设或设太短会导致Docker在服务未监听端口时即开始检查，curl失败计入重试，误判unhealthy；应基于实测冷启动时间加10–20秒缓冲，如62秒实测值设90s，并注意docker-compose中必须写为start_period（下划线）。
给复杂容器配足 --health-start-period，核心是让健康检查在应用真正就绪后才开始，避免因初始化慢被误判为 unhealthy。
为什么 start-period 不是“可选项”而是“必调项”
Spring Boot、Node.js、Java 应用或带数据库连接池/缓存预热的微服务，启动过程常需 40–90 秒。若未设或设得太短（比如默认 0s 或 5s），Docker 会在应用连端口都还没监听时就开始检查，curl 失败 → 计入重试 → 连续失败 → 状态变 unhealthy —— 实际服务可能几秒后就完全可用。
怎么定一个靠谱的 start-period 值
不是拍脑袋，而是基于真实冷启动耗时留出安全余量：
- 先手动测：启动容器后，用
docker logs -f <容器名>观察日志，记录从 “Started Application” 到 “Listening on port 8080” 或 “Cache warmed up” 的时间 - 再加缓冲：实测值 + 10–20 秒。例如实测 Spring Boot 启动完要 62 秒，那就设
--start-period=90s - 对多阶段启动的服务（如先连 DB、再加载配置、最后启 HTTP server），以最后一个关键就绪点为准
不同场景下的推荐范围
以下数值来自生产环境验证，非理论值：
- Spring Boot（含 JPA + Redis）：70–90 秒
- Node.js（带大量 npm 模块 + 初始化脚本）：45–60 秒
- PostgreSQL / MySQL 容器自身：30–40 秒（注意：这是数据库服务就绪，不是客户端连上）
- 含远程依赖（如调第三方 API 初始化）：建议 ≥120 秒，并配合超时和重试调松
配置方式与避坑提醒
三种写法都支持，但行为一致：
- Dockerfile：
HEALTHCHECK --start-period=90s CMD curl -f http://localhost:8080/actuator/health || exit 1 - docker run：
--health-start-period=90s - docker-compose.yml：
start_period: 90s（注意字段名是start_period，不是start-period） - ⚠️ 常见错误：写成
start-period: 90s（带短横线）会静默忽略；必须用下划线 - ⚠️ 不要依赖
depends_on替代 start-period —— 它只控制启动顺序，不判断服务是否真就绪
