运行时健康检查参数
运行时用 --health-cmd 等参数给容器加健康检查，效果与镜像里的 HEALTHCHECK 相同，但不用改镜像，适合给第三方镜像补检查。Docker 按周期执行检查命令并记录状态，docker ps 的 STATUS 列会显示 (healthy) 或 (unhealthy)。
基本信息
| 必填项 | --health-cmd 检查命令 |
|---|---|
| 周期参数 | --health-interval 默认 30s，--health-timeout 默认 30s，--health-retries 默认 3 |
| 宽限 | --health-start-period 给启动阶段留时间 |
| 状态变化 | starting → healthy 或 unhealthy，仅作标记不触发重启 |
| 查看 | docker inspect -f '{{.State.Health.Status}}' 容器 |
典型使用场景
- 给官方镜像（nginx、redis 等）补上业务相关的检查，不必自己维护镜像
- 临时容器快速补检查，让编排的依赖等待条件立即可用
- 排查应用假死：进程还在但接口不响应时，健康状态能直接暴露出来
- 验证一条检查命令是否可用，先命令行跑通再固化进 Dockerfile 或 compose
- 演练与压测中用检查结果做自动化判定，免掉人工确认环节
- 给巡检脚本一个稳定的可用性判据，比只判断容器是否在运行更贴近真实
示例
示例
docker run -d --name web \
--health-cmd 'wget -qO- http://localhost/ >/dev/null || exit 1' \
--health-interval 30s --health-timeout 5s --health-retries 3 \
nginx:1.27-alpine
docker inspect -f '{{.State.Health.Status}}' web # healthy/unhealthy/starting
docker inspect -f '{{json .State.Health}}' web | jq . # 含最近几次检查的输出与退出码参数与取值建议
| 参数 | 默认值 | 调整建议 |
|---|---|---|
| --health-cmd | 无，必须显式指定 | 选容器内确实存在的工具，避免退出码 127 |
| --health-interval | 30s | 按可接受的故障发现时间设定，不宜过密 |
| --health-timeout | 30s | 略大于检查命令的正常耗时 |
| --health-retries | 3 | 与 interval 组合决定判定不健康的总延迟 |
| --health-start-period | 0s | 冷启动慢的应用必须加长 |
健康状态只是标记，Docker 不会据此重启容器；Swarm、Kubernetes 等编排会读取它做调度与滚动更新决策，语义与单机不同。
运行时参数与镜像里的 HEALTHCHECK 同时存在时以运行时为准，所以给第三方镜像补检查不需要重新构建镜像。
检查的历史结果保存在容器状态里（docker inspect 的 State.Health.Log，只保留最近若干次），从最近几次的退出码能看出是持续失败还是偶发抖动。