先从一个我踩过不少回的场景说起：你用docker compose up -d把一整套多服务应用拉起来，数据库、缓存、消息队列、业务后端依次创建容器。结果后端日志刷出来一堆Connection refused，然后进程直接退出，Compose 只能重启，反复几次之后干脆进入Restarting状态。很多人第一反应是“服务启动太慢了”，于是给depends_on加个condition，再写个healthcheck，好像问题就解决了。但如果你真正去拆解依赖、测试依赖、验证依赖，会发现这件事远没有想象中那么简单。
这篇文章我想从 Docker Compose 多服务依赖测试的角度，把我实际项目里用到的思路、踩过的坑、写过的脚本和验证方法整理出来。标题里说的“构建可靠容器化应用”，本质上就是让你的服务编排不再是靠运气启动，而是靠机制保证：谁先就绪、谁等待谁、等待多久、等不到怎么办。无论你是刚接触 Compose 的新手，还是已经在生产环境维护多套 Compose 栈的开发者，这些实践应该都能直接落进你的日常工作中。
1. depends_on 的真相：它保证的是顺序，不是可用性
1.1 一个复现率极高的失败现场
先看我用过的一个“有代表性”的docker-compose.yml，版本不算新，但很常见：
services: db: image: postgres:16-alpine environment: POSTGRES_DB: demo POSTGRES_USER: demo POSTGRES_PASSWORD: demo ports: - "5432:5432" api: build: . depends_on: - db ports: - "8080:8080"在 Compose 的世界里，这个配置看起来没什么问题：api依赖db，先启动数据库，再启动后端。可实际情况是，db容器的进程一启动，Compose 就会认为“这个依赖已经满足了”，然后立刻去启动api。PostgreSQL 的容器进程起来之后，还要经历初始化数据目录、创建用户、监听端口这一系列流程，整个过程可能持续几秒甚至十几秒。后端代码在这个窗口期尝试连接数据库，自然只有Connection refused。如果后端没有重试机制，直接抛异常退出，api就会进入无限重启循环，你甚至来不及登录进容器里去排查问题。
这个现象的核心在于：depends_on控制的只是容器启动的先后顺序，不是服务真正可用的时间点。它可以保证数据库容器在 API 容器之前创建、之前启动，但保证不了 API 启动时 PostgreSQL 已经能接受连接。很多项目把这层依赖关系想得太简单，才导致各种启动时序问题。
1.2 depends_on 三种形态的演进：短语法、长语法与 condition
Docker Compose 的depends_on有两种写法。一种是短语法，就是我们上面看到的那种，只列服务名。短语法在 Compose V1 时代还附带一个隐藏效果：会先等待容器启动，但不会做任何健康判断。Compose V2 之后，短语法的语义更纯粹，就是“先启动，再启动依赖者”。
长语法则多了一些可控选项：
services: api: build: . depends_on: db: condition: service_startedservice_started表示等待db容器启动完成，这跟短语法差不多。更有价值的是service_healthy，它要求依赖的服务先通过健康检查，才会继续启动当前服务。也就是说，Compose 会持续观察db的健康状态，直到变成healthy，再去启动api。这才是从“顺序保证”走向“可用性保证”的关键一步。
services: api: build: . depends_on: db: condition: service_healthy注意，condition这个配置需要依赖服务本身定义了healthcheck。如果db服务没有健康检查，Compose 就永远等不到healthy状态，api会一直卡在启动阶段。这是初用长语法时特别容易踩的坑：condition写了，但被依赖的服务没有healthcheck，一启动就卡住，日志也没输出，表现像是“部署超时”。
1.3 为什么只靠 depends_on 不靠谱
就算你用了condition: service_healthy，也仍然有一个隐含假设：健康检查通过的那一刻，服务就能服务于真实请求。实际上，健康检查的命令本身是你自己定义的。如果你把健康检查写成pg_isready -U demo，它只能说明 PostgreSQL 接受了本地连接请求，不代表业务库表已经完成迁移，更不代表新增的初始化脚本已经执行完。更现实的情况是，一个服务依赖的不是“数据库进程活着”，而是“某个表存在”“某个缓存键可以写入”“某个下游接口返回 200”。
用一个生活化的类比：depends_on相当于你叫了外卖，系统提示“骑手已取餐”，但这和“餐已经送到你手上”是两码事。骑手可能还在路上堵着，可能送错楼，可能找不到你。容器编排里的依赖关系也一样，仅仅“容器启动了”和“外部调用方真正可以开始干活”之间，隔着一大段状态同步的时间差和逻辑鸿沟。
所以，真正可靠的多服务依赖测试，需要把以下三个层面一起打通：容器启动顺序、健康检查状态、业务就绪探测。我在后面的章节里会逐一展开。
2. healthcheck：把“容器起来了”变成“服务能用了”
2.1 healthcheck 的配置最容易被忽略的两个参数
如果只想做最小改造，让 Compose 能感知“服务是否可用”，你就应该从healthcheck写起。下面是一个我常用的 PostgreSQL 健康检查配置：
services: db: image: postgres:16-alpine environment: POSTGRES_DB: demo POSTGRES_USER: demo POSTGRES_PASSWORD: demo healthcheck: test: ["CMD-SHELL", "pg_isready -U demo -d demo"] interval: 2s timeout: 3s retries: 5 start_period: 10s这里最容易被人忽略的参数是start_period。它表示在容器启动后的一段时间内，健康检查如果失败不会被计入重试次数。很多刚接触 healthcheck 的人不知道这个参数，结果数据库要初始化 15 秒，健康检查每 2 秒跑一次，第 3 次失败后容器就被标记为unhealthy，即使后面数据库真正起来了，状态也可能不会自动恢复，或者恢复得很慢。合理设置start_period，相当于告诉 Compose：“给它一点热身时间，热身期的失败别急着算账。”
另一个容易被忽略的是interval和retries的组合。如果检测间隔太短，健康检查命令本身占用资源不说，还可能在你的应用还没准备好时频繁报错刷日志；如果间隔太长，依赖方排队等待的时间也会变长。一般来说，我会把interval设置在 5~10 秒之间，retries设置在 3~5 次之间。既要快速感知就绪，也要容忍短暂抖动。
2.2 自定义命令的坑：nc、wget、curl 可能不存在
给容器写健康检查命令，最常见的问题就是“镜像里没有我想要的工具”。很多 Alpine 镜像为了控制体积，默认不带bash、curl、wget，甚至连nc都没有。你如果用curl -f http://localhost:8080/healthz做健康检查，启动的时候会直接报curl: not found，容器一直被判定为 healthcheck 失败。
针对不同服务，我一般优先使用官方提供的健康探测命令：
- PostgreSQL：使用
pg_isready，镜像自带，不用额外装东西。 - Redis：使用
redis-cli ping，镜像自带，返回PONG。 - MySQL：使用
mysqladmin ping -h 127.0.0.1 -u root -pxxx，或者mysql -e "SELECT 1"。 - Nginx/Web 服务：如果镜像里有
curl就用curl -f http://127.0.0.1/healthz，否则可以检测进程是否存活，但检测进程存活的意义有限，最好还是能做 HTTP 探测。
如果是自定义 Java 或 Node.js 应用，比较推荐在镜像内直接调用运行时自带的探活方式。比如 Node.js 可以写一个node -e脚本来发 HTTP 请求，或者用wget如果镜像装了就很好。实在没有这些工具，还有一个“硬核”技巧：使用 Bash 的/dev/tcp。
healthcheck: test: ["CMD-SHELL", "exec 3<>/dev/tcp/127.0.0.1/8080 && echo open >&3 && exec 3<>&- || exit 1"]但要注意，/dev/tcp是 Bash 的语法，Alpine 镜像默认的 shell 是ash，不一定支持。如果镜像没有bash，这个命令会失败。所以在写健康检查脚本之前，先确认docker compose exec 服务名 sh -c "command -v bash; command -v nc; command -v curl"，再做决定。
2.3 健康状态如何被 Compose 感知
一旦服务定义了healthcheck，docker compose ps里就会多出一列STATUS，显示容器当前的健康状态。初始是starting，通过检查后变为healthy，超过重试次数变为unhealthy。这个状态不仅人可读，Compose 编排时也会读取。
当你在depends_on里写了condition: service_healthy，Compose 会持续观察被依赖服务的健康状态，直到出现healthy才会启动依赖服务。这一点我可以给你看一个实际例子：
services: db: image: postgres:16-alpine healthcheck: test: ["CMD-SHELL", "pg_isready -U demo -d demo"] interval: 2s timeout: 3s retries: 5 start_period: 10s api: build: . depends_on: db: condition: service_healthy command: ["npm", "start"]这样配置之后，执行docker compose up，你会看到 Compose 先启动db，然后db的状态从starting到healthy，接着 Compose 才启动api。日志里的时间戳会非常清楚地展示这条链路。这是多服务依赖测试中“第一关”。
不过我还是想提醒一句：健康检查的状态是编排器的判断，不一定等于业务可用。所以下一章，我再聊聊在业务容器内部，如何做更贴近请求路径的等待逻辑。
3. 依赖就绪的等待策略：脚本、工具与 Compose 内置命令的组合
3.1 最朴素的方案：在入口命令里串一个等待脚本
很多项目不能保证所有依赖服务都写了healthcheck，或者业务方不想改动上游服务的 compose 定义。这种情况下，你需要在当前服务的启动命令里加上“等待依赖就绪”的逻辑。最常见的做法是写一个wait-for-it.sh或者wait-for.sh，然后在command里用sh -c串起来。
示例：
services: api: build: . depends_on: - db - redis command: > sh -c "./wait-for-it.sh db:5432 -- ./wait-for-it.sh redis:6379 -- npm start"这里的思路很简单：在真正启动业务进程之前，先让脚本去探测指定主机和端口通不通。通了，才继续执行后面的命令。不通，脚本内部循环重试，直到超时或成功。好处是逻辑显式，你一眼就能看出这个服务依赖哪几个地址。
但这里有一个容易被忽略的细节：depends_on列表中虽然列出了db和redis，但如果没有condition，它并不能保证数据库和缓存已经就绪。等待脚本承担的才是“探测就绪”的职责。所以这是一个双保险结构：Compose 保证容器顺序，脚本保证连接可用。
3.2 如何自己写一个干净的 wait-for 脚本
网上有很多现成的wait-for-it.sh，但如果你不想引入额外的文件，也可以自己写一个精简版本。我常用的这类脚本基于nc命令，核心逻辑如下：
#!/bin/sh set -e HOST="$1" PORT="$2" shift 2 TIMEOUT="${TIMEOUT:-30}" START_TS=$(date +%s) until nc -z "$HOST" "$PORT"; do if [ $(( $(date +%s) - START_TS )) -gt "$TIMEOUT" ]; then echo "Timeout waiting for $HOST:$PORT" exit 1 fi echo "Waiting for $HOST:$PORT..." sleep 2 done exec "$@"使用方式：
./wait-for.sh db 5432 -- npm start这个脚本有几点我特别想强调：一是exec "$@"一定要用exec，这样脚本进程会被实际的业务进程替换掉，保证 PID 1 是业务进程，信号能正确传递，而不是脚本作为父进程产生孤儿进程。二是超时机制必须有。如果不设置超时，某个依赖服务永远起不来，容器就会一直卡在等待中，从外面看毫无反应，很难排查。
如果镜像里没有nc，也可以换一种纯 shell 的实现，利用 Bash 的/dev/tcp：
#!/bin/bash host="$1" port="$2" shift 2 while ! (echo >/dev/tcp/"$host"/"$port") 2>/dev/null; do echo "Waiting for $host:$port..." sleep 2 done exec "$@"但就像前面说的，这个方案强依赖 Bash。如果你的镜像只有ash或sh，它就不好使。所以最稳妥的方法是在 Dockerfile 里安装netcat-openbsd或者postgresql-client这类工具，用官方网络工具去探测。
3.3 重试 vs 重试+健康检查：选择哪种策略
等待端口只是最低限度的探测。端口通，不代表服务真正可用。举个例子，一个 Java 应用可能已经绑定了 8080 端口，但还在 Spring 容器初始化阶段；另一个微服务调用它时，HTTP 请求会得到 503 而不是 200。如果业务代码只做“连接是否成功”的判断，就会误判为依赖已就绪。
应对这种问题，我的建议是分层设计：
- 对于基础设施类（数据库、Redis、消息队列），等待端口足够，因为它们监听端口后基本就能对外提供服务。
- 对于应用类服务（自己的 API、第三方 HTTP 服务），最好等待一个“就绪端点”，比如
/healthz或/actuator/health。你可以用curl --fail --silent去探测，直到返回 200 再继续。 - 如果服务之间是通过 SDK 调用（比如 gRPC），那么端口探测配合应用自身的重试机制会更好，因为 SDK 连接池的建立有时比 TCP 握手复杂得多。
我常用的一种组合是：容器内先跑一个端口探测脚本，端口通了之后再调用业务初始化脚本，最后启动主进程。同时，应用代码里保留一定的连接重试逻辑，作为最后一道防线。这样即使编排层判断有误，应用也能自己恢复。
3.4 为什么不要把无限重试写死在应用里
有的团队喜欢在应用启动时对依赖服务做无限重试，比如“连不上数据库就每 5 秒重试一次，永不退出”。这样做在本地开发时确实省心，但在生产环境会带来排查困难。一旦数据库故障，应用进程不会失败退出，也不会触发 Kubernetes 或 Compose 的restart策略，日志只会反复打印连接错误，而编排系统认为容器还活着，就不会做出任何自愈动作。最终结果就是你接到一堆业务超时告警，登录服务器去看，发现应用容器一直在做无意义的空转。
所以我的经验是：**应用本身要设置重试次数上限和失败退出机制，编排层负责等待和重启，两者分工明确。**无限重试不是一个好策略，它会掩盖系统真正的故障状态。依赖测试里，你应该验证的是“依赖不可用时应用能快速失败”，而不是“应用无限重试到天荒地老”。这一点等会儿讲故障演练时还会提到。
4. 多服务依赖测试：把“运气”变成“确定性”
4.1 用 docker compose config 静态校验编排结构
依赖测试的第一步，不是把服务跑起来，而是静态检查编排文件本身有没有问题。docker compose config是一个非常实用的指令，它会把我们的 YAML 文件解析成一份展开后的完整配置，并输出到标准输出。这样一眼就能看出 Compose 实际解析了哪些服务、哪些依赖、哪些环境变量。
docker compose config如果只关心配置是否有语法错误，可以使用：
docker compose config -q没有输出就表示配置解析通过。想查看服务列表以及它们的依赖关系，可以试试：
docker compose config --services docker compose config --volumes docker compose config --profiles在 CI 环境或 pre-commit 钩子里，我会加一步docker compose config -q，防止有人提交了depends_on指向不存在的服务名。这种事看着低级，但多人协作时真的会发生。比如有人删除了cache服务，但api的depends_on还留着cache，Compose 只有在启动时才会报错。加上静态校验之后，错误可以被提前拦截。
另外一个可以观察的命令是docker compose config --images，它会列出所有服务的镜像名。结合docker compose pull使用，可以提前检查网络问题和镜像是否存在。
4.2 实战演练一：人为制造依赖故障
依赖测试不只是写一个能用的 Compose 文件，更要在异常场景下验证行为。我第二次强烈建议你在本地做一次“故意搞坏”的实验，否则你根本不知道系统在多服务故障时是什么表现。
实验目标：验证当数据库服务不可用时，api服务会不会因为依赖注入而卡死，或者是否会快速失败重启。
操作步骤：
- 先正常启动整套服务：
docker compose up -d docker compose ps- 确认所有服务状态正常后，把数据库停掉：
docker compose stop db- 观察
api容器的表现：
docker compose logs -f api docker compose ps如果应用本身配置为连接失败后退出，你会看到api容器状态变成exited，而且短时间内会反复重启（取决于restart策略）。如果应用内部有连接重试，你可能看到Restarting或者一直处于running但日志刷错误。
这一步的意义在于：你可以根据观察结果决定要不要调整depends_on和healthcheck。如果api在数据库停止后仍然继续运行但无法工作，说明编排层面没有感知到下游故障；如果api退出后 Compose 反复重启，但数据库始终没恢复，你就会看到重启风暴。这些都是线上出问题时最怕看到的场景。
4.3 实战演练二：延迟启动依赖观察等待效果
依赖测试还要验证“慢启动”场景。有些容器镜像首次初始化时需要下载资源、做数据迁移，启动时间可能长达一分钟。这时候你需要确认api会等这么久，而不是等个几秒就超时退出。
你可以在db服务上临时加一个延迟命令来模拟：
services: db: image: postgres:16-alpine command: > sh -c "sleep 20 && docker-entrypoint.sh postgres" healthcheck: test: ["CMD-SHELL", "pg_isready -U demo -d demo"] interval: 2s timeout: 3s retries: 10 start_period: 30s注意，sleep 20只模拟容器启动前的睡眠，真正的 PostgreSQL 初始化仍然在docker-entrypoint.sh里。接着启动整套服务：
docker compose up -d docker compose ps你会看到db状态先是starting，20 秒后才真正初始化并进入healthy。如果api配置了condition: service_healthy，它会一直等到db变healthy后才启动。这就是我们想要的效果。如果没有等待，api就会在数据库还没起来的时候尝试连接，导致启动失败。
在实际项目中，我不会真的在生产镜像里加sleep，只是在验证依赖顺序时用来模拟“坏情况”。你也可以直接使用docker compose up -d --wait这种带等待机制的命令来做日常冒烟测试，后面会专门讲到。
4.4 检查时序日志：用时间戳还原启动过程
依赖测试一个容易被忽视的收尾动作，是检查日志里面的时间戳顺序。很多人只看容器是否最终启动成功，却忽略了“谁先谁后”。docker compose logs默认显示相对时间，你最好加上-t参数：
docker compose logs -t -f api db redis输出里每一行都会带有 RFC3339 格式的时间戳。我们可以据此还原启动过程：
db容器被创建并开始初始化；db的 healthcheck 从starting变成healthy；api容器启动；api内部执行等待脚本，探测到db:5432可连接；api主进程启动。
如果看到api的时间戳早于db的 healthy 时间戳，说明等待逻辑没有生效。如果api启动后立刻报连接错误，说明依赖探测失败或超时设置太短。时序日志是做这种判断最直观的依据。
另外，如果 Compose 服务内部还有多个进程，可以在自己的应用日志里也加上启动阶段标记。例如：
echo "[$(date -Iseconds)] waiting for db..." ./wait-for.sh db 5432 echo "[$(date -Iseconds)] db is ready, starting app..." exec npm start这样日志自带关键节点，一眼就能看出卡在哪一段。
4.5 自动化冒烟测试的整合
在本地手动跑依赖测试是一回事，在 CI 里自动跑又是另一回事。Docker Compose V2 提供了一个很关键的特性：--wait。使用它可以让docker compose up在服务启动后等待所有服务进入健康状态才返回，特别适合在 CI 脚本里做“环境就绪检查”。
docker compose up -d --wait这条命令会等待所有定义了healthcheck的服务变为healthy。如果某个服务在超时时间内没有变成 healthy，命令会返回非零退出码。配合--wait-timeout可以设置超时时间：
docker compose up -d --wait --wait-timeout 120在 GitHub Actions 或 GitLab CI 里，我惯用的流程是：
docker compose up -d --wait sleep 5 docker compose exec api npm run test:integration docker compose down -vdocker compose down -v里的-v会删除服务挂载的匿名卷，确保下一次测试环境是全新的。如果不清卷，数据库里的脏数据可能导致测试结果不稳定，到时候你很难判定是依赖问题还是数据问题。
对于没有定义healthcheck的服务，--wait会退而求其次，等待容器启动完成。所以为了让 CI 里的--wait真正有意义，我强烈建议所有核心服务都定义健康检查。
5. 把这些实践固化到项目里的三个文件
5.1 Dockerfile 里的健康检查声明
健康检查不一定要写在 compose 文件里，也可以写进 Dockerfile。用HEALTHCHECK指令是一个很不错的做法，因为只要镜像构建出来，运行这个镜像的任何编排器（Compose、Kubernetes、Swarm、Nomad）都能感知到健康状态，不需要每家编排系统都单独配置。示例：
FROM node:20-alpine WORKDIR /app COPY package*.json ./ RUN npm ci --omit=dev COPY . . HEALTHCHECK --interval=5s --timeout=3s --start-period=15s --retries=3 \ CMD wget -qO- http://127.0.0.1:8080/healthz || exit 1 CMD ["node", "server.js"]注意，这里我假设镜像里装了wget。如果连wget都没有，就用 Node.js 本身发起自请求，或者装一个curl。写进 Dockerfile 的好处是，即使有人忘了在 compose 里写healthcheck，容器启动后也会有一个默认健康状态，配合depends_on: condition: service_healthy时不容易踩空。
5.2 docker-compose.yml 里的依赖关系模板
一个成熟项目的 compose 文件，应该长成下面这样，而不是一眼望过去全是depends_on短语法。
services: db: image: postgres:16-alpine environment: POSTGRES_DB: demo POSTGRES_USER: demo POSTGRES_PASSWORD: demo healthcheck: test: ["CMD-SHELL", "pg_isready -U demo -d demo"] interval: 5s timeout: 3s retries: 5 start_period: 10s networks: - backend redis: image: redis:7-alpine healthcheck: test: ["CMD", "redis-cli", "ping"] interval: 5s timeout: 3s retries: 5 start_period: 5s networks: - backend api: build: . environment: DATABASE_URL: postgres://demo:demo@db:5432/demo REDIS_URL: redis://redis:6379 depends_on: db: condition: service_healthy redis: condition: service_healthy healthcheck: test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8080/healthz || exit 1"] interval: 5s timeout: 3s retries: 5 start_period: 15s networks: - backend - frontend networks: backend: frontend:这里的关键点是：depends_on和healthcheck是配套的。depends_on里使用service_healthy，被依赖服务就必须有健康检查。此外，我还会把服务放进不同的自定义网络里，避免所有服务都在同一个扁平网络里互相乱连，至少可以防止前端容器直接访问数据库容器这种不必要的暴露。
5.3 Makefile 里的 up、test、down 指令
把常用命令封装到Makefile里，是我觉得提升团队协作效率最立竿见影的做法。开发者和 CI 只需要运行make up、make test、make down，不需要每个人都背一长串 docker compose 命令。
```makefile .PHONY: up down test logs up: docker compose up -d --wait down: docker compose down -v test: docker compose up -d --wait sleep 5 docker compose exec api npm run test:integration docker compose down -v logs: docker compose logs -t -f写进 Makefile 之后，make test这个目标成为“多服务依赖测试”的入口：它会启动所有服务并等待健康检查通过，等待几秒让应用完全初始化，然后运行集成测试，最后拆除环境。这样不管是新同事入职还是 CI 跑流水线，都能用同一套命令验证配置。
我还会在 Makefile 里加一个make validate目标，用来做静态检查和故障演练的快速入口，避免每次手动敲一堆命令。整个依赖测试的过程就变得更像工程流程，而不是凭感觉。
最后再分享一个小细节
如果你正在做一个会被长期维护的 Compose 项目，我建议你把“依赖测试”写进你的文档或 README，至少说明两点：每个服务依赖哪些其他服务；如果被依赖服务启动失败，当前服务会有什么表现。我在实际项目中见过太多次这样的情况：人走了，服务编排文件在，但没人知道为什么api一定要等redis健康之后才能起来，于是新来的人为了“加快启动速度”把等待逻辑删了，结果线上随机出现缓存连接异常。
我自己做了多年容器化应用之后，最大的体会是：多服务依赖测试不是为了“测”而测，而是为了把一团模糊的启动时序变得可视、可验证、可预期。你把depends_on、healthcheck、等待脚本、故障演练这四个环节串起来，你手上的 Compose 应用才算真正“可靠”了。希望这篇分享能帮你少踩几个坑。
