Docker Compose wait 怎样等服务退出并判断任务结果

如果 Compose 项目里有一个负责迁移、报表或批处理的一次性服务，启动命令返回后还不能立刻判断任务是否完成。docker compose wait 的作用是阻塞到指定服务容器停止；真正的成功或失败，要再读取已停止容器的 ExitCode。需要立即销毁项目资源时，才考虑 --down-project。

官方地址：https://docs.docker.com/reference/cli/docker/compose/wait/

最稳妥的顺序是：先等待一次性服务结束，再查看 docker compose ps --all --format json 的退出码，最后按日志保留需求决定是否清理项目。

• 等待对象：选择会自然退出的任务服务，不要把长期运行的 Web 服务当成完成信号。
• 结果判断：服务显示 stopped 或 exited 只代表进程结束，ExitCode: 0 才表示正常结束。
• 清理选择：需要保留容器和网络排查时不要使用 --down-project；临时流水线可以在第一个容器停止后清理。

先把等待对象限定为一次性任务服务

打开项目的 Compose 配置，先区分长期服务和一次性任务。下面的示例把 worker 设计成执行完就退出的任务容器，把 report 作为另一个可选服务；实际项目中应替换成自己的服务名。

services:
  worker:
    image: alpine:3.21
    command: ["sh", "-c", "echo run task; exit 0"] # 示例任务执行完主动退出

  report:
    image: alpine:3.21
    command: ["sh", "-c", "sleep 30"] # 长时间服务不适合作为任务完成信号

这个区分很重要：docker compose wait worker 等待的是 worker 容器停止，不会因为另一个长期运行的服务仍然存在而把任务完成条件混在一起。如果目标是等待所有服务结束，可以不传 service 名；但批处理脚本通常应该显式指定目标，避免把无关服务纳入等待范围。

用 docker compose wait 等服务结束

确认服务名后，先创建并后台启动任务，再等待指定服务结束。下面的命令块展示的是可复制的操作顺序；其中注释说明每个参数的用途。

# 后台启动 worker，不让当前终端一直附着在容器日志上
docker compose up -d worker

# 阻塞到 worker 容器停止；SERVICE 写 Compose 文件中的服务名
docker compose wait worker

wait 解决的是“什么时候可以继续往下做”，不是“这次任务是否成功”。因此不要只根据命令返回后就写入成功标记，也不要用日志最后一行代替退出码。若服务一直不结束，优先回到 Compose 配置检查它是否本来就是常驻进程，或者检查任务是否卡在外部依赖上。

如果要等待项目中的全部服务停止，可以使用：

# 不指定服务名时等待项目内所有相关容器停止
docker compose wait

全量等待适合整个项目都是一次性任务的场景；混合项目更适合写出明确的 worker 或 migration，让脚本意图和配置边界保持一致。

等待结束后读取 ExitCode

Docker Compose 的 ps 命令默认偏向展示正在运行的容器。要查看已经停止的任务，并让后续脚本稳定读取字段，应同时使用 --all 和 --format json。

# 输出已停止容器的 JSON Lines，包含 Service、State 和 ExitCode
docker compose ps --all --format json

# 只筛选 worker，并把退出码交给脚本判断；jq 负责读取 JSON 字段
worker_exit=$(docker compose ps --all --format json \\
  | jq -r 'select(.Service == "worker") | .ExitCode') # 只读取目标服务

if [ "$worker_exit" = "0" ]; then
  echo "worker completed" # 0 表示任务正常结束
else
  echo "worker failed: exit code $worker_exit" >&2 # 非 0 进入失败分支
  exit 1
fi

官方示例的 JSON 记录会包含 State 和 ExitCode。脚本应先确认筛选结果不是空字符串：没有匹配到服务时，不能把空值误判为成功；服务仍在运行时也应先继续等待，而不是提前读取旧容器的结果。

根据清理需求选择 --down-project

docker compose wait 支持 --down-project：第一个容器停止后丢弃 Compose 项目。它适合一次性 CI 任务或临时验证，但会让你失去继续查看容器状态、网络和卷的机会，所以不要把它当成默认的成功判断开关。

# 一次性流水线：worker 停止后自动清理 Compose 项目
docker compose wait --down-project worker # 适合不需要保留容器现场的临时任务

如果任务失败后还要调查，先不加这个参数，读取 ExitCode、查看日志并保存必要信息，最后再显式执行 docker compose down。如果任务成功且项目没有持久化数据需要保留，使用 --down-project 可以把清理动作和等待动作放在同一段流水线里。

常见问题

为什么 wait 返回后不能直接当成成功？

因为 wait 只说明目标容器已经停止，停止可能是正常完成，也可能是程序报错退出。应读取 docker compose ps --all --format json 的 ExitCode 并按 0 与非 0 分支处理。

服务已经结束，为什么 ps 看不到它？

docker compose ps 默认主要列出运行中的容器。查看已停止服务时加上 --all；同时确认当前目录、-f 指定的 Compose 文件和项目名与启动时一致。

什么时候不应该使用 --down-project？

当失败任务需要保留容器、网络、卷或日志现场时不要立即清理。先读取退出码并完成排查，再决定是否执行 docker compose down；只有不需要现场的临时流水线才适合让 wait 自动清理。

最后确认

把 docker compose wait 当作“等待结束”的步骤，把 docker compose ps --all --format json 当作“判断结果”的步骤，再按调试和清理需求选择 --down-project。这样既能等待一次性服务自然退出，也不会把常驻服务、日志状态和任务成功混为一谈。