healthcheck 是 docker compose 中保障服务可靠性的基础手段，通过周期性执行命令检测服务真实可用性，配合 depends_on condition: service_healthy 实现健康依赖启动。
在 Docker Compose 中，healthcheck 指令不是“锦上添花”，而是保障服务可靠性的基础手段。它让容器运行时主动报告自身状态，使依赖服务能等待就绪、编排工具可自动重启异常实例，避免“容器跑了但服务没起来”的尴尬。
healthcheck 的核心参数与作用
healthcheck 通过周期性执行命令判断容器内服务是否真正可用。关键字段包括：
-
test：必填，指定检测命令，支持字符串（如
["CMD", "curl", "-f", "http://localhost:8080/health"]）或NONE（禁用） - interval：两次检查的间隔，默认 30s，建议设为服务响应时间的 2–3 倍（如 10s）
- timeout：单次检测超时时间，超过即判为失败（如 5s），需小于 interval
- start_period：容器启动后预留的“宽限期”，用于等待服务冷启动完成（如 40s）
- retries：连续失败多少次才将状态设为 unhealthy（默认 3 次）
常见服务的 healthcheck 编写示例
不同服务适合不同检测方式，重点是“测真实业务能力”，而非仅端口通不通：
-
Web 服务（如 Nginx / Express）：
test: ["CMD", "curl", "-f", "http://localhost:3000/health"]，配合应用内置/health端点（返回 200） -
数据库（如 PostgreSQL）：
test: ["CMD-SHELL", "pg_isready -U postgres -d mydb"]，比单纯 telnet 更准确 -
Redis：
test: ["CMD", "redis-cli", "ping"]，成功返回PONG即健康 -
自定义脚本：若检测逻辑复杂，可挂载脚本文件，如
test: ["CMD-SHELL", "/health.sh"]
结合 depends_on 实现启动顺序控制
depends_on 默认只等容器启动（created 或 running），不等健康。要真正实现“等 DB 健康后再启 App”，需两者配合：
- 为依赖服务（如 db）配置
healthcheck - 在依赖方（如 app）中使用
depends_on并指定条件：
db:
condition: service_healthy - 此时
docker compose up会阻塞，直到 db 状态变为healthy才启动 app
验证与调试技巧
健康状态不是黑盒，可通过以下方式确认是否生效：
- 运行后执行
docker compose ps，查看 STATUS 列是否显示healthy或unhealthy - 用
docker inspect <container-id> | jq '.State.Health'</container-id>查看详细结果（含最近一次输出） - 故意写错 healthcheck 命令（如 curl 错误路径），观察是否快速变为 unhealthy 并触发重启（需配置
restart: on-failure） - 日志中留意
health check failed提示，结合timeout和start_period调整参数
不复杂但容易忽略——一个合理配置的 healthcheck，能让整个 compose 栈从“勉强能跑”变成“稳得住、靠得牢”。
