wait-for-it.sh通过tcp端口探测实现服务就绪等待，需挂载脚本、在command中调用，并配置--timeout、--strict等参数；配合healthcheck可提升可靠性，但不能替代业务级健康检查。

直接用 depends_on 只能保证容器启动先后，不能确保服务真正可用。wait-for-it.sh 是一个轻量级 shell 脚本，通过探测目标服务的 tcp 端口是否可连通，来实现“等它准备好再启动”的逻辑，从而补足 docker compose 原生依赖控制的短板。

怎么把 wait-for-it.sh 加进你的服务

核心是让应用容器在执行主命令前，先运行 wait-for-it.sh 并成功连上依赖服务。常见做法有三种：

• 把脚本文件挂载进容器，例如：volumes: - ./wait-for-it.sh:/wait-for-it.sh
• 在 command 中显式调用它，比如：command: ["./wait-for-it.sh", "db:5432", "--", "npm", "start"]
• 确保镜像里有 /bin/sh（绝大多数基础镜像都满足），不需要额外安装依赖

关键参数要配对用才可靠

wait-for-it.sh 默认只做一次连接尝试，实际生产中必须加超时和重试控制：

Docker Image Puller

使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。

下载

• --timeout=60：最多等 60 秒，超时后脚本失败退出，容器也会停止
• --strict：启用严格模式，端口不通就返回非零状态码，避免被忽略
• --host=db --port=5432 或简写为 db:5432：明确目标地址和端口
• 多个依赖可链式等待：./wait-for-it.sh db:5432 -- ./wait-for-it.sh redis:6379 -- npm start

它和 healthcheck 配合效果更好

wait-for-it.sh 只检查端口通不通，但有些服务端口开了、数据库还没初始化完（比如 PostgreSQL 的 pg_isready 检查）。这时候建议：

• 在依赖服务（如 db）中配置 healthcheck，用 pg_isready 或 mysqladmin ping 这类命令验证服务真正就绪
• 在上游服务中仍用 wait-for-it.sh 做第一层快速探测（端口级），再配合应用内重试或健康接口兜底
• 不要只靠 wait-for-it.sh 替代健康检查——它解决的是“网络可达”，不是“业务就绪”

注意几个容易踩的坑

脚本本身简单，但集成时细节决定成败：

• 脚本权限要可执行：chmod +x wait-for-it.sh，否则容器内运行报错 “Permission denied”
• 目标服务名必须和 docker-compose.yml 中定义的服务名完全一致（大小写、下划线）
• 如果用 Alpine 镜像，需确认系统支持 /dev/tcp；不支持时改用 nc 或换 dockerize 工具
• wait-for-it.sh 不会自动重试 DNS 解析失败，若依赖服务启动慢导致 DNS 缓存未生效，可能误判失败