发版前用健康检查卡住不健康容器：Dockerfile HEALTHCHECK与compose period

准备工作

• 已安装Docker Engine，并能运行docker version。

• 官方文档：Dockerfile HEALTHCHECK 指令说明见 Docker Docs。[1]

操作步骤

1、在镜像里声明HEALTHCHECK

做什么：在Dockerfile末尾增加例如：

HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
  CMD curl -f http://127.0.0.1:8080/healthz || exit 1

为什么：编排系统只知道进程在不在；健康检查才告诉你“进程在但服务没好”。[1]
如何确认：docker build成功后，docker inspect镜像配置里能看到Healthcheck字段。

2、跑起来看状态从starting到healthy

做什么：docker run -d --name demo your:image，然后docker ps观察STATUS里的(health: ...)。
为什么：start-period内失败不计入retries，避免启动慢被误杀。[1]
如何确认：就绪后STATUS含(healthy)；故意停掉依赖服务后应变为(unhealthy)。

3、在Compose里对齐interval与依赖顺序

做什么：在compose.yaml服务下写healthcheck:块，并让依赖服务使用depends_on: condition: service_healthy（Compose支持时）。
为什么：只写depends_on服务名只保证启动顺序，不保证可服务。[1]
如何确认：docker compose up时，下游服务在上游healthy之后才创建。

4、失败命令要返回非零

做什么：确保CMD在失败时exit 1（如curl -f）。
为什么：Docker以退出码判断成败。[1]
如何确认：手动在容器内执行同一CMD，失败时echo $?非0。

5、把探测路径做成真正的业务就绪检查

做什么：/healthz（或你选的路径）里检查关键依赖：数据库ping、必要配置已加载，而不是只return 200。
为什么：假健康检查会让编排系统把半残实例继续接流量。[1]
如何确认：人为断开数据库后，容器在数个interval后变unhealthy。

6、为发布流水线加一道“不健康则失败”

做什么：在CI/CD里docker run后轮询docker inspect --format='{{.State.Health.Status}}'，超时仍非healthy则失败回滚。
为什么：镜像能构建不等于服务能就绪。
如何确认：故意弄坏HEALTHCHECK CMD时，流水线变红。

注意事项

• 健康检查不是负载均衡探活的全部；公网探活还要另配。

• 别在HEALTHCHECK里做很重的迁移任务。

常见问题

• 一直卡在starting？ 加大start-period，或检查健康检查是否在服务听端口之前就执行。[1]

• Compose里depends_on不生效？ 确认Compose文件版本支持condition: service_healthy，且拼写无误。

• 探活把自己打挂？ 降低频率、减轻检查逻辑，避免每次检查都跑迁移或全表扫描。

做完后，你应能在docker ps里看到healthy/unhealthy变化，并在上游不健康时挡住下游启动。

说明：以下步骤基于 Docker 官方 Dockerfile HEALTHCHECK 文档，于 2026-10-24 核对；Compose 字段名以你安装的 Compose 规格为准。健康检查只反映容器自身探测结果，不能替代网关与监控告警。

来源

[1] Dockerfile HEALTHCHECK reference，Docker Docs，核对于2026-10-24。

#Docker #HEALTHCHECK #Compose #教程 #运维