Compose 依赖服务未就绪导致连接拒绝报错 wait_for 配置无效怎么办

遇到 Compose 启动时报连接拒绝，通常是因为依赖服务容器虽已启动但内部进程尚未监听端口，原生 depends_on 不等待服务就绪，建议改用健康检查配合条件启动。

先说结论：原生 Docker Compose 没有 wait_for 配置项，依赖服务未就绪需通过 healthcheck 结合 depends_on 条件控制启动顺序

适合：数据库、消息队列等需要监听端口就绪的后端服务依赖
先准备：为依赖服务编写合理的健康检查命令
验收：确认主服务启动前依赖服务状态已变为 healthy

命令速用版

version: '3.8'
services:
  db:
    image: postgres
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
  web:
    image: myapp
    depends_on:
      db:
        condition: service_healthy

为什么会这样

Docker Compose 的 depends_on 默认只等待容器状态变为 started，不代表内部应用已完成初始化。连接拒绝报错是因为主服务尝试连接时，依赖服务的进程尚未绑定端口。公开资料中没有看到可靠的量化数据说明具体延迟多久，但通常数据库初始化需要数秒到数十秒不等。

分步处理

1. 编辑 docker-compose.yml，找到依赖服务定义。

2. 添加 healthcheck 块，设置测试命令、间隔和重试次数。

3. 修改主服务的 depends_on，将依赖项改为对象格式，指定 condition 为 service_healthy。

Compose 依赖服务未就绪导致连接拒绝报错 wait_for 配置无效怎么办

4. 保存文件，执行 docker compose down 和 docker compose up -d 重建容器。

怎么验证是否生效

运行 docker compose ps 观察状态列，依赖服务应显示 healthy 后主服务才开始启动。查看主服务日志 docker compose logs web，确认不再有 Connection refused 错误。

常见坑

健康检查命令需要容器内存在对应工具，如 mysql 需安装 mysqladmin。网络别名需一致，避免服务间无法通过服务名解析。健康检查超时时间设置过短会导致服务反复重启。

参考来源

Docker 官方文档 - Compose file specification - depends_on 和 healthcheck 配置说明

URL: https://docs.docker.com/compose/compose-file/