如何在 Docker Compose 中配置健康检查 healthcheck 参数详解

在 Docker Compose 中配置 healthcheck 主要是为了让编排工具知道容器内的应用是否真正就绪，常用于控制服务启动顺序和自动重启策略。

先说结论：健康检查不是必须的，但在多服务依赖场景下能显著减少启动报错，建议核心服务都配上。

适合：依赖其他服务才能运行的应用，或需要自动重启恢复的场景
先准备：确认容器内有哪些命令可用，避免检查命令本身报错
验收：通过 docker compose ps 查看状态是否为 healthy

命令速用版

version: '3.8'
services:
  web:
    image: nginx
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

为什么会这样

Docker 容器启动成功仅代表主进程运行，不代表业务逻辑正常。healthcheck 通过定期执行命令，让 Docker 引擎感知应用内部状态，从而支持 depends_on 的条件等待和自动恢复。

分步处理

1. 确定检查命令：优先使用应用自带的健康接口，其次用 curl 或 wget 访问本地端口，最后才考虑进程存在性检查。

2. 编写 Compose 配置：在 services 下添加 healthcheck 字段，注意 test 字段支持字符串和列表两种格式，列表格式更推荐。

如何在 Docker Compose 中配置健康检查 healthcheck 参数详解

3. 设置合理时间：start_period 给应用预留启动时间，避免刚启动就被判失败；interval 和 timeout 根据应用响应速度调整。

怎么验证是否生效

运行 docker compose up -d 后，执行 docker compose ps。观察 STATUS 列，初期显示 starting，成功后变为 healthy。若显示 unhealthy，查看日志 docker compose logs <service_name>。

常见坑

1. 检查命令依赖缺失：容器内没有 curl 或 wget，导致检查一直失败，需确保基础镜像包含相关工具。

2. 退出码误解：健康检查命令退出码为 0 表示健康，非 0 表示不健康，脚本编写需注意。

3. 资源消耗：高频检查会增加容器负载，生产环境 interval 不建议低于 10s。

参考来源

Docker 官方文档 - Compose file reference 05-services

URL: https://docs.docker.com/compose/compose-file/05-services/#healthcheck