在 Docker Compose 编排多容器应用时，服务依赖启动失败是高频问题。典型表现是后端服务日志中出现 connection refused 或数据库尚未准备好的报错，随后容器退出。排查时很多人会检查 depends_on 配置，但即便已经写上依赖，问题依旧存在。这是因为 depends_on 只保证容器启动的顺序，并不会等待被依赖服务真的可以接收请求。要解决这个问题，需要把关注点从启动顺序转移到健康就绪状态。
depends_on 的真实行为与局限
Compose 文件中的 depends_on 关键字只能控制服务容器的启动先后顺序。比如让 api 服务在 db 服务之后启动，Compose 会先创建并启动 db 容器，等 db 容器进入运行状态后再启动 api 容器。但“容器运行”并不等于“服务可用”。数据库进程可能已经起来，但还需要完成数据目录初始化、执行启动脚本、建立监听套接字等操作，这些步骤耗时从几百毫秒到几十秒不等。如果 api 容器在 db 容器刚进入运行态时就发起连接，很可能会遇到连接拒绝或认证失败。
下面这个配置就存在这样的问题：
services:
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: example
api:
build: .
depends_on:
- db
ports:
- "8080:8080"
实际运行中，api 服务很可能在数据库还没准备好接受连接时就启动，导致初始化代码抛出异常并退出。这种情况在首次启动或者数据库数据目录为空时尤其明显，因为 PostgreSQL 需要先执行 initdb 并创建系统表，耗时更长。即便数据库容器已经运行了几秒，应用也可能因为重试次数不够而失败。因此，单纯依赖 depends_on 无法解决服务依赖就绪的问题。
使用 healthcheck 和 condition: service_healthy
Docker 提供了健康检查机制，可以定期执行命令来判断容器内的服务是否真正就绪。在 Compose 中可以为每个服务定义 healthcheck，然后让依赖方通过 depends_on 的 condition 选项等待被依赖服务变为 healthy 状态。这样 Compose 会先启动 db 容器，并持续检查其健康状态，只有健康检查通过后才会启动 api 容器。
以 PostgreSQL 为例，可以使用 pg_isready 命令来检测数据库是否接受连接：
services:
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: example
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
timeout: 5s
retries: 10
api:
build: .
depends_on:
db:
condition: service_healthy
ports:
- "8080:8080"
healthcheck 中的 test 可以是 CMD 形式或 CMD-SHELL 形式，CMD-SHELL 会通过 shell 执行字符串命令。interval 表示检查间隔，timeout 表示单次检查超时时间，retries 表示连续失败多少次才判定为 unhealthy。还可以设置 start_period 给容器预留初始化的缓冲时间，避免在启动阶段过早判定失败。对于 MySQL，可以使用 mysqladmin ping；对于 Redis，可以使用 redis-cli ping。关键是选一个能真实反映服务可用性的探测命令。
condition: service_healthy 是 Compose 规范中的条件依赖语法。除了 service_healthy，还支持 service_started（默认值）和 service_completed_successfully。后者适用于一次性任务，比如数据库迁移工具执行成功后才启动主服务。需要注意的是，condition 语法在较老的 Compose 文件版本中可能不受支持，如果使用 version 字段，建议移除或使用较新的 Compose V2。如果遇到 condition 不生效的情况，可以检查 Docker Engine 版本和 Compose 版本是否足够新。
外部等待工具与自定义入口脚本
在某些环境中，Compose 的 healthcheck 可能不方便使用，或者需要更细粒度的等待逻辑，比如等待多个服务、等待某个 HTTP 端点返回 200，或者需要在启动前执行额外的准备工作。此时可以借助外部等待工具，将等待逻辑封装到容器入口脚本中。常见的有 wait-for-it、dockerize 等。
wait-for-it 是一个纯 Bash 脚本，用于等待指定主机的端口可连接。可以在 Dockerfile 中下载并复制该脚本，然后通过 ENTRYPOINT 或 command 来包装真正的启动命令。例如：
FROM python:3.12-slim WORKDIR /app COPY requirements.txt . RUN pip install -r requirements.txt COPY . . ADD https://raw.githubusercontent.com/vishnubob/wait-for-it/master/wait-for-it.sh /usr/local/bin/wait-for-it RUN chmod +x /usr/local/bin/wait-for-it ENTRYPOINT ["wait-for-it", "db:5432", "--", "python", "app.py"]
然后在 Compose 中正常声明 depends_on，让容器启动顺序正确，但真正的就绪等待交给 wait-for-it 完成。这样即使数据库端口暂时不可达，wait-for-it 也会持续重试，直到端口打开或超时。wait-for-it 默认会等待 15 秒，可以通过 -t 参数调整超时时间，例如 -t 60 表示最多等待 60 秒。
dockerize 是另一个功能更丰富的工具，除了等待 TCP 端口，还支持等待 HTTP 接口、文件生成等。用法类似：
dockerize -wait tcp://db:5432 -wait http://web:8080/health -timeout 60s python app.py
这种方案的优势是不依赖 Compose 版本，容器镜像自包含等待逻辑，可以迁移到 Kubernetes 等其他平台时继续使用。缺点是需要在镜像中额外引入脚本，增加了构建复杂度。对于团队内部，也可以编写一个简单的 shell 循环来等待端口，但要注意控制超时和退出码，避免无限等待导致容器无法退出。
重启策略与常见失败排查
有些团队会通过设置 restart: on-failure 来缓解依赖启动失败。当 api 容器因为连不上数据库而崩溃退出时，Docker 会自动重启它。如果数据库在几秒后完成初始化，第二次或第三次重启就可能成功。这种方式虽然简单，但属于被动容错，可能掩盖真实的启动顺序问题，而且每次重启都会有失败的日志噪音，不利于追踪问题根源。更推荐的做法是结合 healthcheck 或等待脚本，让 api 容器在启动前就确认依赖已就绪。
当依赖启动失败已经发生时，需要快速定位原因。常用的排查命令包括：
docker compose ps
docker compose logs api
docker inspect --format='{{.State.Health.Status}}' 容器名或ID
通过 docker compose ps 可以查看各服务的当前状态，如果某个服务处于 unhealthy 或反复重启，说明健康检查未通过。docker compose logs 可以查看具体报错信息，例如连接超时、密码错误、数据库不存在等。docker inspect 的 Health.Status 字段能直接看到容器的健康状态是 starting、healthy 还是 unhealthy。如果健康检查一直卡在 starting，可能是探测命令本身有问题或 start_period 设置过短。
针对不同的错误信息，处理思路也不同。如果是连接拒绝，说明目标端口还没监听，需要增加等待逻辑；如果是认证失败，可能是环境变量配置错误，需要检查密码和用户名；如果是数据库不存在，则可能需要先执行初始化脚本。把这些基础问题解决后，再通过 healthcheck 或等待工具加固启动流程，才能从根本上避免 Compose 服务依赖启动失败。
Docker Compose服务依赖启动失败修改时间：2026-09-21 01:01:40