1. 问题陈述：服务启动的依赖性

在 docker-compose.yml 文件中，虽然可以使用 depends_on 来控制容器的启动顺序，但 depends_on 仅能保证依赖容器的启动，而无法保证容器内部的服务（例如数据库进程）已经完成初始化并准备好接受外部连接。

这种时间差会导致竞态条件（Race Condition）：

db 服务的容器已启动，但其内部的数据库进程仍在初始化。
app 服务的容器已启动，并立即尝试连接数据库。
由于数据库尚未就绪，连接失败，导致 app 服务崩溃或进入不断重启的循环。

为了解决这一问题，我们需要一种机制来探测依赖服务的端口是否可用，从而精确控制主应用进程的启动时机。

2. 解决方案：`wait-for-it.sh` 脚本

wait-for-it.sh 是一个纯粹的 Bash 脚本，其核心功能是暂停后续命令的执行，直到一个指定的主机（Host）和端口（Port）建立起 TCP 连接为止。

它的工作原理简单而有效：

接收一个目标地址（host:port）作为参数。
循环尝试与该地址建立连接。
连接成功后，脚本退出，并执行在其后定义的所有命令。
如果超时（可配置），脚本将以非零状态码退出，以示失败。

通过在 Docker Compose 的 command 或 entrypoint 中集成此脚本，我们可以有效地延迟应用进程的启动，直至其所有依赖项都准备就绪。

3. 实施步骤

以下是在 Docker Compose 环境中集成 wait-for-it.sh 的标准流程。

第一步：获取脚本并设置执行权限

首先，需要将 wait-for-it.sh 脚本下载到项目的构建上下文中（通常是与 Dockerfile 和 docker-compose.yml 相同的目录）。

使用 curl 或 wget 从其官方 GitHub 仓库下载：

bash
# 使用 curl
curl -o wait-for-it.sh https://raw.githubusercontent.com/vishnubob/wait-for-it/master/wait-for-it.sh

# 或者使用 wget
wget -O wait-for-it.sh https://raw.githubusercontent.com/vishnubob/wait-for-it/master/wait-for-it.sh

下载后，必须为其添加可执行权限：

bash
chmod +x wait-for-it.sh

第二步：在 `docker-compose.yml` 中配置 `command`

接下来，修改 docker-compose.yml 文件，让需要等待的服务在启动时调用该脚本。假设我们有一个 my-app 服务依赖于一个名为 database 的 MySQL 服务。

示例 docker-compose.yml：

yaml
version: '3.8'

services:
  my-app:
    build: . # 确保 wait-for-it.sh 在构建上下文中
    ports:
      - "8080:8080"
    # 使用 command 字段来集成 wait-for-it.sh
    command: ["./wait-for-it.sh", "database:3306", "--", "npm", "start"]
    depends_on:
      - database

  database:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: your_strong_password
      MYSQL_DATABASE: my_db
    # 为便于演示，映射端口，实际生产中可能不需要
    ports:
      - "3306:3306"

command 字段解析：

command 字段被定义为一个数组，其各部分作用如下：

"./wait-for-it.sh": 要执行的脚本。由于它被复制到了工作目录，因此可以直接调用。
"database:3306": 等待的目标。database 是 Docker Compose 网络中定义的服务名，3306 是 MySQL 的默认端口。脚本将持续探测此地址。
"--": 参数分隔符。它告知 wait-for-it.sh 脚本自身的参数到此结束，之后的所有内容都是在等待成功后需要执行的命令。
"npm", "start": 实际的应用启动命令。您可以将其替换为任何命令，例如 ["/app/start-service.sh"] 或 ["java", "-jar", "app.jar"]。

第三步：启动并验证

配置完成后，使用标准命令启动服务：

bash
docker-compose up

在控制台日志中，将观察到 my-app 服务的输出首先会显示 wait-for-it.sh 的信息，表明它正在等待 database:3306 可用。一旦 database 容器内的 MySQL 服务完成初始化并开始监听端口，wait-for-it.sh 脚本就会成功退出，并立即执行 npm start 命令，从而确保应用在可靠的环境中启动。

4. 总结

wait-for-it.sh 提供了一个轻量级、可移植且与具体技术栈无关的解决方案，用于处理 Docker Compose 环境中的服务启动依赖问题。它通过简单的 TCP 端口探测，有效地弥补了 depends_on 无法保证服务就绪的不足。将此脚本集成到您的工作流中，可以显著提高多容器应用启动的稳定性和可靠性。

目录