Docker Compose服务显示Waiting但docker ps显示Up的问题排查咨询

问题现象 #

执行docker compose up -d --build启动项目时，多数服务快速进入Started状态，但某一个服务始终显示Waiting。然而通过docker ps查看时，该服务容器状态为Up，且日志输出符合预期。添加健康检查配置后，问题仍未解决。

docker compose up状态的含义与判断逻辑 #

Started状态 #

服务标记为Started需满足以下条件：

• 容器成功启动（PID 1进程正常运行）
• 所有depends_on中配置的依赖条件已满足（默认仅要求依赖容器启动，若配置condition: service_healthy则需依赖服务健康检查通过）
• 无额外自定义启动验证逻辑时，容器启动完成即触发Started状态

Waiting状态 #

服务进入Waiting状态通常由以下场景触发：

• 等待依赖服务满足指定条件：例如depends_on配置了等待依赖服务的健康检查，但依赖服务未通过健康检查；或依赖服务自身处于Waiting状态
• Compose内部状态同步延迟：容器已实际启动，但Compose未及时获取到容器的状态更新
• 服务初始化逻辑未完成：容器进程已启动，但后台初始化操作（如数据库迁移、配置加载）未完成，导致Compose认为服务未就绪（即使未配置健康检查）
• 版本兼容性问题：Docker Engine与Compose版本间的状态同步bug

排查方向 #

• 检查depends_on配置：确认该服务是否依赖其他服务，尤其是是否配置了condition: service_healthy这类强依赖条件，若依赖服务健康检查失败，会导致当前服务持续Waiting
• 查看Compose详细状态：执行docker compose ps，查看服务的完整状态描述，通常会显示等待的具体原因（如Waiting for service "xxx" to be healthy）
• 分析容器状态细节：执行docker inspect <容器ID>，查看State字段中的Health、StartedAt、ExitCode等信息，确认容器是否真的稳定运行
• 临时移除健康检查：若之前添加了健康检查，暂时删除该配置，验证是否还会出现Waiting状态，排除健康检查配置错误的可能
• 升级Compose版本：尝试更新到最新的Docker Compose版本，排查是否为已知的版本兼容性bug导致状态显示异常

环境版本信息 #

$ docker version
Client: Docker Engine - Community
 Version:           27.0.3
 API version:       1.46
 Go version:        go1.21.11
 Git commit:        7d4bcd8
 Built:             Sat Jun 29 00:02:33 2024
 OS/Arch:           linux/amd64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          27.0.3
  API version:      1.46 (minimum version 1.24)
  Go version:       go1.21.11
  Git commit:       662f78c
  Built:            Sat Jun 29 00:02:33 2024
  OS/Arch:          linux/amd64
  Experimental:     true
 containerd:
  Version:          1.7.18
  GitCommit:        ae71819c4f5e67bb4d5ae76a6b735f29cc25774e
 runc:
  Version:          1.7.18
  GitCommit:        v1.1.13-0-g58aa920
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0
$ docker compose version
Docker Compose version v2.28.1

内容的提问来源于stack exchange，提问作者jonathan-dev