atkrad/wait4x

Wait4X Docker 镜像文档

📑 目录

• 📋 概述
• ✨ 特性
• 📦 镜像信息
• 🐳 Docker 部署方案
• 🚀 快速开始
• 📖 详细使用方法
• ⚙️ 高级特性
• 📝 配置参数说明
• 💡 使用场景示例

📋 概述

Wait4X 是一个功能强大、零依赖的工具，用于在继续执行前等待服务就绪。它支持多种协议和服务，使其成为以下场景的重要组件：

• CI/CD 流水线 - 确保测试运行前依赖项可用
• 容器编排 - 应用启动前健康检查服务状态
• 部署流程 - 部署前验证系统就绪状态
• 应用初始化 - 验证外部服务可用性
• 本地开发 - 简化本地服务就绪检查

✨ 特性

📦 镜像信息

• 镜像名称: atkrad/wait4x
• 支持架构: amd64, arm64
• 最新版本标签: latest
• Docker Hub 地址: https://hub.docker.com/r/atkrad/wait4x

🐳 Docker 部署方案

基本用法

bash
# 拉取镜像
docker pull atkrad/wait4x:latest

# 查看帮助信息
docker run --rm atkrad/wait4x:latest --help

等待 TCP 服务就绪

bash
# 等待本地 MySQL 服务就绪
docker run --rm --network host atkrad/wait4x:latest tcp localhost:3306

# 等待其他容器服务就绪（使用 Docker 网络）
docker run --rm --network my-network atkrad/wait4x:latest tcp mysql:3306

等待 HTTP 服务就绪

bash
# 等待健康检查端点返回 200 状态码
docker run --rm atkrad/wait4x:latest http https://example.com/health --expect-status-code 200

# 等待响应体包含特定内容
docker run --rm atkrad/wait4x:latest http https://example.com/status --expect-body-regex '"status":"UP"'

Docker Compose 集成示例

yaml
version: '3.8'

services:
  app:
    build: .
    depends_on:
      - db
      - redis
    command: ["dockerize", "-wait", "tcp://db:3306", "-wait", "tcp://redis:6379", "-timeout", "60s", "npm", "start"]
    
  wait4x:
    image: atkrad/wait4x:latest
    command: tcp db:3306 redis:6379
    
  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: password
      MYSQL_DATABASE: appdb
      
  redis:
    image: redis:alpine

结合 Docker Compose 健康检查

yaml
version: '3.8'

services:
  api:
    build: ./api
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "8080:8080"

  db:
    image: postgres:14
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
      POSTGRES_DB: appdb
    healthcheck:
      test: ["CMD", "docker run --rm --network=container:$HOSTNAME atkrad/wait4x:latest postgresql 'postgres://user:password@localhost:5432/appdb?sslmode=disable'"]
      interval: 5s
      timeout: 5s
      retries: 5

🚀 快速开始

基本 TCP 检查

等待端口可用：

bash
docker run --rm --network host atkrad/wait4x:latest tcp localhost:3306

HTTP 健康检查

等待 Web 服务器返回特定响应：

bash
docker run --rm atkrad/wait4x:latest http https://example.com/health \
  --expect-status-code 200 \
  --expect-body-regex '"status":"UP"'

多服务并行检查

同时等待多个服务就绪：

bash
docker run --rm --network host atkrad/wait4x:latest tcp 127.0.0.1:5432 127.0.0.1:6379 127.0.0.1:27017

数据库就绪检查

等待 PostgreSQL 就绪：

bash
docker run --rm --network host atkrad/wait4x:latest postgresql \
  'postgres://user:pass@localhost:5432/mydb?sslmode=disable'

检查成功后执行命令

服务就绪后运行命令：

bash
docker run --rm --network host atkrad/wait4x:latest tcp localhost:8080 -- echo "服务已就绪！"

📖 详细使用方法

🌐 HTTP 检查

检查状态码

等待 HTTP 端点返回特定状态码：

bash
docker run --rm atkrad/wait4x:latest http https://api.example.com/health --expect-status-code 200

使用正则表达式检查响应体

等待 HTTP 端点返回匹配正则表达式模式的响应：

bash
docker run --rm atkrad/wait4x:latest http https://api.example.com/status \
  --expect-body-regex '"status":\s*"healthy"'

使用 JSON Path 检查响应体

等待特定 JSON 字段存在或具有特定值：

bash
docker run --rm atkrad/wait4x:latest http https://api.example.com/status \
  --expect-body-json "services.database.status"

这使用 https://github.com/tidwall/gjson#path-syntax 进行强大的 JSON 查询。

自定义请求头

发送带有特定头的 HTTP 请求：

bash
docker run --rm atkrad/wait4x:latest http https://api.example.com \
  --request-header "Authorization: Bearer token123" \
  --request-header "Content-Type: application/json"

🔍 DNS 检查

检查 A 记录

bash
# 基本存在性检查
docker run --rm atkrad/wait4x:latest dns A example.com

# 带预期 IP 的检查
docker run --rm atkrad/wait4x:latest dns A example.com --expected-ip 93.184.216.34

# 使用特定名称服务器
docker run --rm atkrad/wait4x:latest dns A example.com --expected-ip 93.184.216.34 -n 8.8.8.8

💾 数据库检查

MySQL

bash
# TCP 连接
docker run --rm --network host atkrad/wait4x:latest mysql 'user:password@tcp(localhost:3306)/mydb'

# 通过 Docker 网络连接
docker run --rm --network my-network atkrad/wait4x:latest mysql 'user:password@tcp(mysql:3306)/mydb'

PostgreSQL

bash
docker run --rm --network my-network atkrad/wait4x:latest postgresql \
  'postgres://user:password@postgres:5432/mydb?sslmode=disable'

Redis

bash
# 基本连接检查
docker run --rm --network my-network atkrad/wait4x:latest redis redis://redis:6379

# 带认证和数据库选择
docker run --rm --network my-network atkrad/wait4x:latest redis redis://user:password@redis:6379/0

# 检查键是否存在
docker run --rm --network my-network atkrad/wait4x:latest redis redis://redis:6379 --expect-key "session:active"

🚌 消息队列检查

RabbitMQ

bash
docker run --rm --network my-network atkrad/wait4x:latest rabbitmq \
  'amqp://guest:guest@rabbitmq:5672/myvhost'

⚙️ 高级特性

⏱️ 超时和重试控制

设置超时时间

限制 Wait4X 的总等待时间：

bash
docker run --rm atkrad/wait4x:latest tcp localhost:8080 --timeout 30s

设置检查间隔

控制 Wait4X 重试频率：

bash
docker run --rm atkrad/wait4x:latest tcp localhost:8080 --interval 2s

指数退避

使用指数退避进行更高效的重试：

bash
docker run --rm atkrad/wait4x:latest http https://api.example.com \
  --backoff-policy exponential \
  --backoff-exponential-coefficient 2.0 \
  --backoff-exponential-max-interval 30s

↔️ 反向检查

等待端口变为空闲：

bash
docker run --rm atkrad/wait4x:latest tcp localhost:8080 --invert-check

等待服务停止：

bash
docker run --rm atkrad/wait4x:latest http https://service.local/health \
  --expect-status-code 200 --invert-check

⚡ 命令执行

检查成功后执行命令：

bash
docker run --rm --network my-network --volume $(pwd):/app atkrad/wait4x:latest \
  tcp db:3306 -- /app/deploy.sh

🔄 并行检查

同时等待多个服务：

bash
docker run --rm --network my-network atkrad/wait4x:latest tcp db:3306 redis:6379 rabbitmq:5672

📝 配置参数说明

全局参数

协议特定参数

HTTP 检查参数

DNS 检查参数

💡 使用场景示例

示例 1: Docker Compose 服务依赖检查

yaml
version: '3.8'

services:
  web:
    build: ./web
    depends_on:
      wait-for-dependencies:
        condition: service_completed_successfully
    command: ["npm", "start"]
    
  wait-for-dependencies:
    image: atkrad/wait4x:latest
    command:
      - tcp
      - db:3306
      - redis:6379
      - --timeout
      - 60s
    networks:
      - app-network
      
  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: password
      MYSQL_DATABASE: appdb
    networks:
      - app-network
      
  redis:
    image: redis:alpine
    networks:
      - app-network

networks:
  app-network:

示例 2: CI/CD 管道中的使用

在 GitLab CI 中：

yaml
deploy:
  stage: deploy
  image: docker:latest
  services:
    - docker:dind
  before_script:
    - docker pull atkrad/wait4x:latest
    - docker network create app-network
    - docker run -d --name db --network app-network -e POSTGRES_PASSWORD=pass postgres:14
    - docker run --rm --network app-network atkrad/wait4x:latest postgresql 'postgres://postgres:pass@db:5432/postgres?sslmode=disable' --timeout 60s
  script:
    - docker run --name app --network app-network -d my-app-image

示例 3: 数据库迁移前等待数据库就绪

bash
#!/bin/bash
set -e

# 启动数据库容器
docker run -d --name db -e POSTGRES_PASSWORD=pass postgres:14

# 等待数据库就绪
docker run --rm --network host atkrad/wait4x:latest postgresql \
  'postgres://postgres:pass@localhost:5432/postgres?sslmode=disable' \
  --timeout 120s

# 运行数据库迁移
docker run --rm --network host my-migration-tool migrate

# 启动应用
docker run -d --name app --network host my-app