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 缓存未生效，可能误判失败
