ReachProbeApi 项目简介与使用指南

这篇文章围绕「ReachProbeApi 项目简介与使用指南」整理了可直接落地的步骤，适合按顺序操作并逐项验证结果。

项目是什么

---

主要特性

能力	说明
单文件运行	核心逻辑集中在 main.py，部署简单
配置灵活	支持 config.json，且可用环境变量覆盖
探活接口	POST /reachprobeapi/v1
健康检查	GET /healthz
可选鉴权	通过请求头 X-API-Key 启用 API Key
限流	进程内内存限流，减轻滥用
IP 策略	可限制私网、回环、组播、保留地址等
有界探测	通过时间预算等限制，避免单次请求拖很久

---

目录结构

.
├── main.py
├── config.json
├── requirements.txt
└── tests/

---

快速开始

1. 安装依赖

python3 -m venv .venv
source .venv/bin/activate   # Windows 可用 .venv\Scripts\activate
pip install -r requirements.txt

2. 启动服务

python3 main.py

3. 使用 PM2 守护（可选）

pm2 start main.py --interpreter python3 --name reachprobeapi

---

API 说明

POST /reachprobeapi/v1

{
  "target": "dns.google",
  "port": 443
}

{
  "target": "dns.google",
  "port": 443,
  "resolved_addresses": ["8.8.8.8", "8.8.4.4"],
  "reachable": true,
  "attempts": 3,
  "successful_connects": 2,
  "duration_ms": 137
}

GET /healthz

{
  "status": "ok"
}

---

使用示例（curl）

curl -sS -X POST "http://127.0.0.1:8899/reachprobeapi/v1" \
  -H "Content-Type: application/json" \
  -d '{"target":"dns.google","port":53}'

curl -sS -X POST "http://127.0.0.1:8899/reachprobeapi/v1" \
  -H "Content-Type: application/json" \
  -d '{"target":"example.com","port":443}'

curl -sS -X POST "http://127.0.0.1:8899/reachprobeapi/v1" \
  -H "Content-Type: application/json" \
  -d '{"target":"1.1.1.1","port":443}'

curl -sS -X POST "http://127.0.0.1:8899/reachprobeapi/v1" \
  -H "Content-Type: application/json" \
  -d '{"target":"2606:4700:4700::1111","port":443}'

curl -sS -X POST "http://127.0.0.1:8899/reachprobeapi/v1" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: change_me" \
  -d '{"target":"example.com","port":443}'

curl -sS -X POST "http://127.0.0.1:8899/reachprobeapi/v1" \
  -H "Content-Type: application/json" \
  -d '{"target":"dns.google","port":443}' | jq '{target, reachable, successful_connects, duration_ms}'

---

配置说明

export IPTOOLS_CONFIG_FILE=/path/to/config.json

常用配置项

config.json 键	环境变量	默认值	说明
telnet_count	TELNET_COUNT	3	探测轮数，范围 1..10
telnet_timeout_sec	TELNET_TIMEOUT_SEC	1	单次连接超时（秒），1..5
max_resolved_addresses	MAX_RESOLVED_ADDRESSES	4	最多使用几条 DNS 结果，1..16
probe_time_budget_sec	PROBE_TIME_BUDGET_SEC	10	单次请求总时间上限（秒），1..60
require_api_key	REQUIRE_API_KEY	false	是否要求 X-API-Key
api_key	API_KEY	null	API Key 明文
rate_limit_requests	RATE_LIMIT_REQUESTS	30	限流窗口内允许请求数
rate_limit_window_sec	RATE_LIMIT_WINDOW_SEC	60	限流窗口长度（秒）
allow_private_ip	ALLOW_PRIVATE_IP	false	是否允许探测私网 IP
allow_loopback_ip	ALLOW_LOOPBACK_IP	false	是否允许回环地址
allow_multicast_ip	ALLOW_MULTICAST_IP	false	是否允许多播地址
allow_reserved_ip	ALLOW_RESERVED_IP	false	是否允许保留地址
server_host	SERVER_HOST	0.0.0.0	监听地址
server_port	SERVER_PORT	8899	监听端口

生产环境环境变量示例

export REQUIRE_API_KEY=true
export API_KEY='replace_with_strong_key'
export RATE_LIMIT_REQUESTS=20
export RATE_LIMIT_WINDOW_SEC=60
export TELNET_COUNT=2
export TELNET_TIMEOUT_SEC=1
export MAX_RESOLVED_ADDRESSES=4
export PROBE_TIME_BUDGET_SEC=8

---

公网部署时的安全建议

• 除非完全信任调用方，否则保持 ALLOW_PRIVATE_IP=false、ALLOW_LOOPBACK_IP=false。
• 对外暴露前务必开启 API Key，并配合网关做 TLS、WAF、IP 白名单 等。
• 在网络层尽量限制出站访问范围，并对进程做 CPU、内存与日志监控。

---

小结