docker compose 不保证服务就绪，需在 entrypoint 中用 wait-for-it.sh 或 curl 轮询依赖端口或健康接口，并用 exec "$@" 启动主进程；depends_on 仅控启动顺序，须配合 healthcheck 与主动等待。
docker compose 本身不保证服务启动的严格顺序，依赖服务就绪（比如数据库能连上、api 响应健康）才是关键，而不是容器“启动完成”。配合 entrypoint 脚本做主动等待，是实现真正优雅依赖启动最可靠的方式。
用 wait-for-it.sh 或自研脚本轮询依赖服务端口
这是最常用、轻量且可移植的做法。核心逻辑是：在应用容器启动前，先检查依赖服务的 TCP 端口是否可连通（例如 PostgreSQL 的 5432、Redis 的 6379），直到成功或超时才继续执行主命令。
- 把 wait-for-it.sh 下载进镜像（COPY 或 curl），设为可执行
- 在
entrypoint.sh中调用它，例如：./wait-for-it.sh db:5432 --timeout=60 --strict -- echo "DB is ready" -
--strict表示失败直接退出容器，避免应用在无依赖状态下启动 - 注意：只检测端口通 ≠ 服务完全就绪（如 PostgreSQL 可能正在恢复），但对大多数场景已足够；若需更精确判断，可改用 curl 检查健康接口
用 curl 检查 HTTP 健康端点（适合 Web 依赖）
当依赖是另一个 Web 服务（如 Auth API、Config Server），端口通不代表它已加载配置或完成初始化。此时应等待其 /health 或 /ready 接口返回 200。
- 在
entrypoint.sh中写循环：until curl -f http://auth-service:8080/health > /dev/null 2>&1; do sleep 2; done -
-f让 curl 在非 2xx 响应时返回错误，配合until实现重试 - 加上超时保护，避免无限等待（可用
timeout 120s bash -c '...'包裹） - 确保基础镜像含
curl（Alpine 用户装apk add --no-cache curl）
entrypoint 脚本要正确透传 CMD 参数
很多问题源于 entrypoint 执行完后没启动主进程。必须用 exec "$@" 将原始命令（如 npm start 或 python app.py）作为 PID 1 启动，否则信号无法传递、容器无法优雅停止。
- 一个安全的
entrypoint.sh结构： #!/bin/sh<br>./wait-for-it.sh db:5432 --timeout=60 --strict<br>echo "Dependencies ready, starting app..."<br>exec "$@"
- 构建时确保脚本有执行权限：
RUN chmod +x /entrypoint.sh - 在 Dockerfile 中声明：
ENTRYPOINT ["/entrypoint.sh"]，CMD 保持不变
避免误区：depends_on 只控制启动顺序，不等就绪
depends_on 在 Compose v2+ 中仅影响容器创建顺序，不会等待依赖容器的进程监听端口或返回健康响应。即使写了 condition: service_healthy，也要求依赖服务自己定义了 healthcheck，且你仍需在应用侧做等待——因为健康检查通过和你的应用发起连接之间仍有时间差。
- 不要单独依赖
depends_on，它只是辅助手段 - 推荐组合使用：
depends_on + healthcheck（用于依赖服务自身可观测） +entrypoint 等待（用于消费方主动确认） - 例如数据库加 healthcheck：
healthcheck:<br> test: ["CMD-SHELL", "pg_isready -U postgres"]<br> interval: 30s<br> timeout: 10s<br> retries: 5
