docker compose 起栈失败——依赖服务没就绪（Connection refused / unhealthy / depends_on 不生效）

症状

```

app-1 | wget: can't connect to remote host (172.18.0.3): Connection refused

app-1 | APP_CONN_REFUSED

```

```

db-1 | httpd: applet not found

db-1 exited with code 127

dependency failed to start: container depstest-db-1 exited (127)

```

```

Container depstest-db-1 Waiting

Container depstest-db-1 Error

dependency failed to start: container depstest-db-1 is unhealthy

```

特征：compose 里写了 depends_on 仍然连接被拒；或 ps 显示 unhealthy；或容器 exit 127。

原因

普通 `depends_on` 只保证启动顺序不保证就绪；就绪需 `healthcheck` + `condition: service_healthy`。健康检查失败三来源：命令在镜像中不存在（exit 127）、启动慢没配 start_period（误判 unhealthy）、检查命令自身错误（持续 unhealthy）。

解法

1. 依赖服务加 `healthcheck`（test 命令必须存在于镜像；启动慢加 `start_period`）；

2. app 改用 `depends_on: db: condition: service_healthy`；

3. `docker compose up -d` 后 `docker compose up --wait --wait-timeout 60` 验收；

4. unhealthy 时 `docker inspect <容器> --format "{{json .State.Health.Log}}"` 看检查命令真实报错。

验证证据

- 本机实测复现（2026-08-31，WSL 定制预构建版，docker 29.1.3 + compose 2.40.3）：

- 相位1：普通 depends_on → app 立即启动 → `APP_CONN_REFUSED`（db sleep 4s）；

- 相位2：healthcheck + `condition: service_healthy` + start_period 6s → db healthy 后 app 启动 → `APP_OK`；

- 变体A：无 start_period → 启动期 3 次失败 → `dependency failed to start ... is unhealthy`（服务 4s 后才就绪）；

- 变体B：db 用 `busybox httpd`（alpine 无此 applet）→ `httpd: applet not found`、exit 127；

- 相位3：healthcheck `["CMD","false"]` → ps 显示 `Up 7 seconds (unhealthy)`、`up --wait` 报 unhealthy 错误。

- 实测复现日志（2026-08-31）