donkeyx/tcp-wait

tcp-wait

概述

tcp-wait是一个Go语言包，用于测试和等待TCP主机与端口的可用性。主要用作依赖其他服务的容器的启动前脚本，可在启动主服务前先运行该工具，按设定间隔检查依赖服务，若指定的主机:端口在超时时间内未可用则退出。

项目地址：https://github.com/donkeyx/tcp-wait

核心功能

• 支持检查单个或多个TCP服务（主机:端口）的可用性
• 可设置超时时间（默认20秒）
• 提供JSON和文本两种输出格式（默认JSON）
• 轻量且易于集成到容器启动流程中
• 支持版本信息查询

使用场景

• 容器化应用中，确保数据库、缓存、API服务等依赖组件就绪后再启动主应用
• 微服务架构中，服务间依赖的启动顺序控制
• 自动化部署流程中，验证服务是否成功启动

快速开始

使用Docker

bash
# 查看版本信息
$ docker run -it donkeyx/tcp-wait -version
Unable to find image 'donkeyx/tcp-wait:latest' locally
...
Version '0.9.9'
Git_Hash 'a4f4d51'

使用Go安装

bash
# 获取包
go get github.com/donkeyx/tcp-wait

# 将Go二进制路径添加到shell启动文件（以bash为例）
echo 'export PATH="~/go/bin:$PATH"' >> ~/.bashrc

# 快速运行（若检查失败将返回错误码和信息）
tcp-wait -hp localhost:8080,localhost:9090 -t 5

# 查看帮助（无参数运行）
tcp-wait -h
Usage of /Users/dbinney/go/bin/tcp-wait:
  -hp value
    	<host:port> [host2:port,...] 逗号分隔的主机:端口列表
  -o string
    	输出格式，可选json/text（默认"json"）
  -t int
    	超时时间（秒，默认20）
  -version
    	版本信息
...

使用方法

基本参数说明

使用示例

简单检查（成功案例）

bash
$ ./bin/tcp-wait -hp github.com:80
{"level":"info","msg":"services are ready!","services":["github.com:80"],"time":"2020-03-12T17:18:30+10:30"}

多主机检查（超时1秒，文本输出）

bash
$ ./bin/tcp-wait -hp github.com:443,google.com:443 -t 1 -o text
INFO[2020-03-12T17:20:15+10:30] services are ready!  services="[github.com:443 google.com:443]"

多主机检查（超时2秒，部分服务不可用）

bash
$ ./bin/tcp-wait -hp github.com:443,localhost:10000 -t 2
{"level":"warning","msg":"tcp ping failed","tcp-host":"localhost:10000","time":"2020-03-12T17:26:16+10:30"}
{"level":"warning","msg":"tcp ping failed","tcp-host":"localhost:10000","time":"2020-03-12T17:26:17+10:30"}
{"level":"error","msg":"services did not respond","time":"2020-03-12T17:26:18+10:30"}

本地构建

可克隆仓库后使用Makefile构建二进制文件，生成的文件将位于本地bin目录，包含Linux、macOS和本地环境版本。

bash
# 构建并运行所有版本
$ make all
go get
go test -v ./...
=== RUN   TestSuccessSingle
--- PASS: TestSuccessSingle (0.01s)
=== RUN   TestFailureDouble
{"level":"warning","msg":"tcp ping failed","tcp-host":"nowhere:50","time":"2020-03-13T11:38:45+10:30"}
{"level":"warning","msg":"tcp ping failed","tcp-host":"nowhere:51","time":"2020-03-13T11:38:45+10:30"}
--- PASS: TestFailureDouble (0.50s)
PASS
ok      tcp-wait        (cached)
go build -o ./bin/tcp-wait -v
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o bin/linux/tcp-wait -v
tcp-wait
CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -o bin/mac/tcp-wait -v
tcp-wait

# 生成的目录结构（二进制文件位于bin目录）
$ tree
├── Dockerfile
├── LICENSE
├── Makefile
├── README.md
├── bin
│   ├── tcp-wait
│   ├── tcp-wait.darwin.amd64
│   ├── tcp-wait.linux.amd64
│   └── tcp-wait.windows.amd64
├── go.mod
├── go.sum
├── main.go
├── main_test.go
└── tmp
    └── test-coverage
        ├── coverage.html
        └── coverage.out.

# 直接执行二进制文件
$ ./bin/tcp-wait
Usage of ./bin/tcp-wait:
  -hp value
        <host:port> [host2:port,...] 逗号分隔的服务列表
  -o string
        输出格式，可选json/text（默认"json"）
  -t int
        超时时间（默认20）