Compose 健康检查是什么
在 Compose 服务的 healthcheck 段里定义自检命令与探测节奏，Docker 会按周期在容器内执行该命令，并根据退出码维护容器的健康状态。它是 depends_on 的 service_healthy 条件、docker compose up --wait 以及上游编排调度的共同依据，也是容器自愈的基础。健康检查回答的是『服务真的就绪了吗』，比端口能不能连更能反映实际可用性。
基本信息
| test | ["CMD", "curl", "-f", "http://localhost/health"] 或 CMD-SHELL 形式的单串命令 |
|---|---|
| 节奏参数 | interval 间隔 / timeout 单次超时 / retries 连续失败阈值 / start_period 启动宽限 |
| 退出码约定 | 0 视为健康，1 视为不健康，2 保留不用 |
| 状态查看 | docker compose ps 显示 (healthy) 或 (unhealthy) |
| 联动能力 | service_healthy 依赖条件、up --wait 都基于它 |
典型使用场景
- 有依赖顺序的启动：数据库健康后再启动应用，避免应用启动即报连接失败
- 慢启动服务：用 start_period 给出宽限期，避免初始化阶段被判定不健康
- 发布验证：配合 up --wait 确保新版本真正就绪再切流量
- 本地开发复现问题：让 unhealthy 状态在 compose ps 中可见，而不只是应用日志报错
- 编排自愈：健康状态被上游系统读取后触发重启或替换容器
示例
示例
services:
api:
image: app:1.0
depends_on:
db:
condition: service_healthy
healthcheck:
test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:8080/healthz || exit 1"]
interval: 15s
timeout: 5s
retries: 3
start_period: 30s参数与取值建议
| 参数 | 含义 | 取值建议 |
|---|---|---|
| interval | 两次探测之间的间隔 | 5-30 秒，过密会增加容器内负载 |
| timeout | 单次探测超时时间 | 小于 interval，一般 3-5 秒 |
| retries | 连续失败多少次判为不健康 | 3 次左右，避免单次抖动误判 |
| start_period | 启动宽限期，期内失败不计入 retries | 按应用启动耗时设置，宁长勿短 |
| test | 探测命令 | 用轻量接口，避免查库全表等重逻辑 |
健康检查命令必须在容器内真实存在：alpine、distroless 这类精简镜像通常没有 curl，写错就永远是 unhealthy；可用 wget 替代，或调用应用自带的探活接口配合镜像内已存在的工具。
健康检查探测的是容器内视角，不要让它依赖外部系统（数据库、下游接口）：外部抖动会导致容器被误判不健康并被反复重启，把局部故障放大成雪崩。