最近一次微服务容器化部署，生产环境直接爆出 API 500。日志里堆满了 Connection refused 和 Failed to connect to mysql:3306。原因很直接：Docker Compose 默认只检查进程是否存活，不检查服务是否真正可写。数据库容器启动后监听端口需要几秒，API 容器却立即发起连接，握手失败导致后端 500。这类问题在缺乏健康检查的微服务编排中极其常见，尤其是在 CI/CD 流水线频繁触发重启时，竞态条件被放大，引发级联故障。
一、 故障现场与初步判断
部署脚本执行 docker compose up -d 后，业务入口立刻不可用。通过 docker compose logs -f api 查看 API 服务，错误日志显示 JDBC 驱动无法建立连接，抛出的异常栈帧指向 Communications link failure: Could not connect to database。同期数据库容器状态显示为 Up，但应用层实际尚未完成初始化。这种现象具有典型性：容器生命周期管理（Container Lifecycle）关注的是进程退出码，而应用就绪度（Application Readiness）关注的是端口监听与逻辑初始化，两者存在时间差。
此时不能只看容器状态，Up 仅说明主进程在运行，不代表网络端口开放或数据库接受连接。在容器网络中，DNS 解析、端口监听、应用初始化是三个独立阶段。需要逐个验证网络连通性，并确认依赖服务的真实就绪状态。这里可以参考 DNS 解析故障排查实战：超时、污染与本地缓存 中关于容器内 DNS 解析延迟的分析，避免把网络延迟误判为代码 bug。此外，若怀疑底层网络不通，可结合 tcpdump 实战：用命令行抓包排查网络故障 在宿主机层面捕获 SYN 包，确认网络层是否丢包。
二、 Docker Compose 依赖机制的误区
很多开发者误以为 depends_on 能解决服务就绪问题。实际在 Compose v3+ 版本中，depends_on 默认只保证容器启动顺序，即 API 容器在 DB 容器启动后才会启动，但不会等待 DB 就绪。DB 容器启动后，MySQL 或 PostgreSQL 需要时间加载数据字典、恢复事务日志（WAL Recovery），这段时间内连接请求会被拒绝。对于 PostgreSQL，冷启动可能需要数十秒，若 API 服务在 T+1 秒尝试连接，必然失败。
1. 默认行为与条件等待的差别
要区分“启动”与“就绪”。启动是进程创建成功，就绪是应用能处理请求。传统应用启动慢，微服务依赖健康检查探针，但探针需要显式配置。默认情况下，depends_on 的 condition: service_started 是唯一的默认值，condition: service_healthy 必须配合 healthcheck 使用。没有健康检查定义，service_healthy 无法触发。这是一个常见的配置陷阱：开发者以为加了依赖就不会报错，却忽略了“进程存在”不等于“服务可用”。
三、 定位连接失败的根因
在 DB 容器内执行 mysqladmin ping 或 pg_isready 并不足以完全判断就绪。对于 MySQL，mysqladmin ping 即使数据库处于错误状态或正在启动中，只要进程存活也可能返回 mysqld is alive，这容易误导排查。更准确的做法是执行 mysql -u root -p -e "SELECT 1"，如果返回成功，说明数据库引擎已完全加载并可以处理查询。在 API 容器内执行 nc -vz db-host 3306，若超时或拒绝，证明网络层或 DB 层未就绪。这种跨容器验证能快速隔离是 DNS 问题、网络问题还是 DB 进程问题。
# 在 API 容器内执行，验证与 DB 的连通性
# 替换 db-host 为实际服务名，3306 替换为目标端口
# 1. 基础网络连通性测试
docker compose exec api-service nc -vz db-host 3306
# 预期输出：Connection to db-host 3306 port [tcp/mysql] succeeded!
# 2. 应用层就绪测试（更可靠）
# 进入 DB 容器，执行 SELECT 1 确保引擎真正接受连接
docker compose exec db mysql -u root -p -e "SELECT 1"
# 若失败，检查 DB 容器日志，确认 MySQL 是否处于 Recovery 模式若 nc 成功但 JDBC 仍报错，问题可能在连接池配置。应用启动时连接池立即建立，但 DB 此时虽可连接，可能正处于只读模式或事务恢复中。检查 DB 日志中是否有 Recovery mode 相关输出。同时查看 API 服务连接池配置，是否缺少重试机制。如果 API 容器内部没有安装 nc，可以使用 Bash 的 /dev/tcp 特性进行替代测试，避免额外安装工具。
# 如果容器内没有 nc 命令，使用 bash 内置功能测试端口
# 在 API 容器内执行：
docker compose exec api-service bash -c 'echo > /dev/tcp/db-host/3306'
# 如果无报错，说明端口已打开；如果报错 "Connection refused"，说明未就绪四、 修复方案：配置健康检查
核心是给每个关键服务添加 healthcheck，并在依赖中指定 condition: service_healthy。健康检查必须使用服务内部可达的命令，避免使用容器外的工具。对于 MySQL，使用 mysqladmin ping 是标准做法，但该命令在 MySQL 客户端中存在，无需额外安装。然而，为了更严谨地检测“可查询”状态，建议组合使用。对于 Python 服务，python -c "import requests; requests.get('http://localhost:8080/health')" 是常用方式。健康检查命令必须在容器内可执行，路径需与镜像内一致。
# 示例 docker-compose.yml，API 服务依赖 DB 健康
version: '3.8'
services:
db:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: "your_password"
# 关键修复：定义健康检查
healthcheck:
# 使用 mysqladmin ping 检测进程，结合 SELECT 1 检测引擎（可选更严）
test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
interval: 10s # 每 10 秒检查一次
timeout: 5s # 单次检查超时 5 秒
retries: 5 # 连续 5 次失败视为不健康
start_period: 30s # 启动宽限期：允许 30 秒内检查失败而不标记为 Unhealthy
api:
image: your-api-image
# 关键修复：等待 DB 真正健康，而非仅仅启动
depends_on:
db:
condition: service_healthy
environment:
DB_HOST: db
DB_PORT: "3306"start_period 参数很关键，它告诉 Docker 在健康检查失败后，给服务多长的时间完成初始化。没有这个参数，MySQL 启动慢时，容器会反复判死并重启，形成死循环。Docker 官方文档强调，start_period 期间，即使检查失败，容器状态也不会变为 unhealthy，这为慢启动服务提供了缓冲。
1. 不同语言服务的健康检查差异
对于 Java 应用，若容器内没有 curl 或 wget，可用 /opt/java/healthcheck.sh 等脚本，或直接使用 Java 自带的 telnet 类似工具。对于 Go 服务，可以利用其内置的 net/http 包编写简单的探测逻辑。对于非 HTTP 协议的服务（如 RabbitMQ、Redis），健康检查需要针对协议特性。例如 Redis 使用 redis-cli ping，Kafka 使用自定义脚本检查 broker 连接。
五、 连接池重试机制的兜底
即使配置了健康检查，仍存在竞态窗口。API 服务自身启动慢时，其依赖的其他服务可能还未就绪。此时需要 API 层实现指数退避重试。以 Spring Boot 为例，配置 spring.datasource.hikari.connection-timeout 为 30 秒，并开启 leak-detection-threshold，可在连接不可用时快速失败，避免线程阻塞。这类配置与 Spring Boot 线程池配置不当导致服务雪崩 中的线程保护思路一致，避免重试耗尽线程池。HikariCP 默认会尝试建立连接，如果持续失败，它会抛出异常，但若配置了重试策略，可以容忍短暂的 DB 不可用。
# application.yml 连接池重试配置片段
spring:
datasource:
hikari:
maximum-pool-size: 20
# 等待连接的最大毫秒数，过短会导致 DB 启动慢时 API 直接报错
connection-timeout: 30000
# 验证超时时间
validation-timeout: 5000
# 连接测试查询，用于验证连接有效性
connection-test-query: SELECT 1
# 自动提交
auto-commit: true
# 重要：HikariCP 内置的重试机制
# 如果 DB 暂时不可用，HikariCP 会不断尝试获取连接直到超时
# 结合 JVM 的 -XX:+UseGC 等调优，避免 GC 停顿导致的假性超时六、 优化建议：降低启动等待时间
健康检查间隔不宜过短。频繁探测会消耗 CPU，且对 DB 压力过大。建议间隔 5-10 秒，超时 3-5 秒。对于启动较慢的服务，适当增大 start_period。此外，使用 init 脚本在容器启动前预热依赖，例如先执行 wait-for-it.sh 等待网络可达，再启动应用。这种“双重保险”策略在复杂微服务架构中非常有效。
1. 使用 wait-for-it 脚本
该脚本可嵌入 Dockerfile 或 Compose 中，等待特定主机端口开放后再启动主进程。相比 depends_on，它能在网络层真正建立连接后才放行。对于非 HTTP 协议的服务，wait-for-it 比健康检查更可靠，因为它直接模拟客户端连接行为。以下是一个典型的 Dockerfile 集成示例：
# Dockerfile 示例：集成 wait-for-it
# 假设基础镜像是 slim 版本，需要安装 bash
RUN apt-get update && apt-get install -y bash && \
wget -O /usr/local/bin/wait-for-it.sh \
https://raw.githubusercontent.com/vishnubob/wait-for-it/master/wait-for-it.sh && \
chmod +x /usr/local/bin/wait-for-it.sh
# 启动命令：先等待 DB 的 3306 端口，再启动 Java 应用
CMD ["/bin/bash", "-c", "/usr/local/bin/wait-for-it.sh db:3306 -t 60 -- java -jar /app/app.jar"]七、 对比：有/无健康检查的部署行为
| 场景 | 无健康检查 | 有健康检查 |
|---|---|---|
| API 启动时机 | DB 容器启动后立即启动 | DB 健康检查通过后启动 |
| 连接失败概率 | 高，尤其首次启动 | 极低，DB 就绪后才放行 |
| 自动重启行为 | DB 连接失败导致 API 反复崩溃重启 | DB 不健康时 API 保持 Waiting，不崩溃 |
| 运维复杂度 | 需手动干预，排查困难 | 自愈能力强，日志清晰 |
| 资源消耗 | 低（无额外检查进程） | 略高（每 interval 执行一次命令） |
有健康检查时，若 DB 长时间不健康，API 容器会停在 Waiting 状态，而非反复崩溃重启。这种状态在监控中更容易识别，也便于排障。结合 Kafka 消息积压排查实战：消费滞后定位与快速恢复 中的思路，若依赖的是消息队列，健康检查应指向 Kafka broker 的 controller 状态，而非仅进程存活。对于消息中间件，健康检查不仅要确认 TCP 连通，还要确认 ZK 或 KRaft 集群已选举出 Leader。
八、 排查与修复后的监控落地
修复完成后，在 Prometheus 中暴露 docker_container_health_status 指标，配合 Grafana 面板监控各服务健康状态。告警规则设置为健康状态非 healthy 持续 2 分钟，通知值班人员。同时保留 docker compose logs -f 作为第一手排查工具。对于生产环境，建议通过 SELinux 导致服务异常：实战排查与修复 中提到的方法，检查容器内是否有权限问题导致健康检查命令执行失败。例如，某些镜像中 mysqladmin 可能因缺少 /tmp 写入权限而报错，需配置临时卷。
小结
Docker Compose 依赖顺序问题本质是“启动”与“就绪”的混淆。通过为关键服务配置健康检查，并在 depends_on 中使用 service_healthy 条件，可从根本上消除 API 500 的启动竞态。配合连接池重试与 wait-for-it 脚本，能进一步提升系统韧性。这套方案无需改动业务代码，仅需调整 Compose 配置，实施成本低，适用于绝大多数容器化微服务架构。在实际落地中，务必关注 start_period 参数，它决定了系统对慢启动服务的容忍度，是避免“假性故障”的关键配置。
