docker compose健康检查核心是通过service下的healthcheck字段执行业务级命令（如curl健康接口），依退出码0/1判定真实可用性；必配test、interval、timeout、retries、start_period五参数，需确保容器内有执行工具、绑定0.0.0.0地址，并用docker inspect验证状态。
在 docker compose 中配置健康检查，核心是通过 healthcheck 字段定义容器内服务是否“真正可用”，而不仅是进程在不在。它不依赖端口连通性，而是执行一条能反映业务状态的命令（比如调用健康接口或检查数据库连接），并根据退出码（0=健康，1=不健康）判断状态。
基础配置：在 docker-compose.yml 中声明 healthcheck
必须放在具体 service 下，不能写在顶层。一个典型且实用的配置如下：
-
test：指定检测命令，推荐用
["CMD-SHELL", "curl -f http://localhost:8080/health || exit 1"]—— 使用CMD-SHELL更灵活，-f让 curl 在 HTTP 非2xx时直接失败，|| exit 1显式确保非0退出 - interval：两次检查间隔，建议 15–30 秒；太短增加负载，太长延迟故障发现
- timeout：单次命令最长执行时间，建议设为略大于预期响应时间（如 5–10 秒），避免慢请求被误判
-
retries：连续失败多少次才标记为
unhealthy，设为 3 是较稳妥的选择，容忍短暂抖动 -
start_period：容器启动后宽限期，建议 40–60 秒；此期间失败不计入 retries，状态为
starting，防止应用还没初始化完就被判“死”
关键细节：避免常见踩坑
很多问题源于对退出码和执行环境理解偏差：
- 容器内必须有
curl或nc等工具；若基础镜像精简（如alpine），需提前安装或改用sh -c 'echo > /dev/tcp/localhost/8080 2>/dev/null'类原生命令 - 不要用
exit 2—— Docker 将其视为保留值，不会触发 unhealthy，反而让容器卡在starting状态，难以排查 - 健康检查命令运行在容器内部，路径、端口、权限都以容器视角为准；例如
http://localhost指的是容器自身，不是宿主机 - 如果服务监听
127.0.0.1而非0.0.0.0，curl 会失败；务必确认应用绑定的是通配地址
验证与调试：怎么看是否生效
配置完成后，别只靠 docker-compose up 就算完事：
- 运行
docker-compose ps，STATUS 列会显示(healthy)、(unhealthy)或(starting) - 查详细信息：
docker inspect <container_name> --format='{{json .State.Health}}'</container_name>，输出含最近几次检查时间、结果、退出码和日志 - 手动进容器执行相同 test 命令，确认返回值符合预期（
echo $?看退出码） - 临时把 test 改成
["CMD", "sh", "-c", "sleep 2 && exit 0"]可快速验证机制是否触发
进阶建议：按场景选策略
健康检查不是越严越好，要匹配服务特性：
-
Web API 服务：优先用 HTTP 健康端点（如
/health），检查自身状态 + 关键依赖（DB、缓存）是否可连 -
后台任务型容器（如 worker）：可检查本地 socket 文件是否存在，或用
pgrep -f "my-worker"确认主进程存活 - 多阶段启动服务（如 Java 应用）：start_period 设长些（60s+），避免 JVM 初始化未完成就开检
-
禁用默认健康检查：若基础镜像自带 HEALTHCHECK 但你不想要，可在 compose 中写
healthcheck: disable: true
