compose healthcheck 字段
healthcheck 为服务定义健康检查：测试命令、间隔、超时、重试次数与启动宽限期。健康状态既显示在 compose ps 里，也是 depends_on 的 condition: service_healthy 与 up --wait 的判定依据。
基本信息
| 字段 | test、interval、timeout、retries、start_period |
|---|---|
| 关闭方式 | healthcheck: disable: true |
| test 形式 | CMD 直接执行、CMD-SHELL 交给 shell、NONE 继承镜像设置 |
| 状态显示 | compose ps 里的 healthy 与 unhealthy 标记 |
| 判定用途 | 依赖等待与 up --wait 的完成条件 |
典型使用场景
- 让上游服务真正等到依赖就绪再启动，配合 depends_on 的条件判断
- 部署完成后确认服务进入可用状态，而不是只看容器在运行
- 慢启动应用留足宽限期，避免初始化阶段被误判为故障
- 巡检与告警按健康状态判断可用性，比查进程更贴近实际
- 覆盖基础镜像自带的检查，换成贴合业务语义的探测
- 排查服务已启动但一直不健康：核对检查命令在容器内是否存在
示例
示例
services:
db:
image: postgres:16-alpine
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"] # 容器内可执行的命令
interval: 5s
timeout: 3s
retries: 10
start_period: 20s # 启动宽限期
api:
image: app/api:1.4.2
depends_on:
db:
condition: service_healthy字段与取值建议
| 字段 | 作用 | 取值建议 |
|---|---|---|
| test | 健康检查命令 | 用镜像里确实存在的工具 |
| interval | 检查间隔 | 比业务响应慢一个量级即可 |
| timeout | 单次检查超时 | 略大于检查命令的正常耗时 |
| retries | 连续失败次数 | 结合 interval 决定判定延迟 |
| start_period | 启动宽限期 | 按冷启动时间设置 |
start_period 内的失败不计入重试次数，适合启动慢的应用；检查命令本身必须在镜像里真实存在，否则会一直不健康。
interval 设得太小会让日志与 CPU 开销上升，按应用特性定合理间隔，不要写成高频探测。
健康检查只影响状态标记与依赖等待，不会触发容器重启，自愈要靠重启策略或编排层来解决。
test 用 CMD 形式不经过 shell，重定向与管道这类语法会失效；需要用 shell 特性时写成 CMD-SHELL，或把检查逻辑放进一个脚本文件。