You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
231 lines
4.9 KiB
231 lines
4.9 KiB
# Wormhole SOCKS5 Client API
|
|
|
|
## 概述
|
|
|
|
Wormhole SOCKS5 Client 在HTTP代理模式下提供了内置的API端点，用于监控和管理代理服务。
|
|
|
|
## 端点
|
|
|
|
### 代理功能
|
|
|
|
所有非API请求都会通过SOCKS5代理转发：
|
|
|
|
- **HTTP 代理**: 处理普通HTTP请求
|
|
- **HTTPS 代理**: 处理CONNECT方法的HTTPS隧道
|
|
|
|
### 监控API
|
|
|
|
#### GET /stats
|
|
|
|
获取详细的代理统计信息。
|
|
|
|
**响应示例:**
|
|
```json
|
|
{
|
|
"start_time": "2024-01-01T12:00:00Z",
|
|
"uptime": "2h30m15s",
|
|
"total_connections": 150,
|
|
"active_connections": 5,
|
|
"successful_requests": 145,
|
|
"failed_requests": 5,
|
|
"bytes_sent": 1024000,
|
|
"bytes_received": 2048000,
|
|
"socks5_errors": {
|
|
"connection_failed": 3,
|
|
"auth_failed": 1,
|
|
"timeout": 1
|
|
}
|
|
}
|
|
```
|
|
|
|
**字段说明:**
|
|
- `start_time`: 代理启动时间
|
|
- `uptime`: 运行时间
|
|
- `total_connections`: 总连接数
|
|
- `active_connections`: 当前活跃连接数
|
|
- `successful_requests`: 成功请求数
|
|
- `failed_requests`: 失败请求数
|
|
- `bytes_sent`: 发送字节数
|
|
- `bytes_received`: 接收字节数
|
|
- `socks5_errors`: SOCKS5错误分类统计
|
|
|
|
#### GET /health
|
|
|
|
获取代理健康状态信息。
|
|
|
|
**响应示例:**
|
|
```json
|
|
{
|
|
"status": "healthy",
|
|
"uptime": "2h30m15s",
|
|
"active_connections": 5,
|
|
"success_rate": 96.67
|
|
}
|
|
```
|
|
|
|
**字段说明:**
|
|
- `status`: 健康状态 ("healthy")
|
|
- `uptime`: 运行时间
|
|
- `active_connections`: 当前活跃连接数
|
|
- `success_rate`: 成功率百分比
|
|
|
|
## 使用示例
|
|
|
|
### 基本用法
|
|
|
|
1. **启动HTTP代理模式:**
|
|
```bash
|
|
./bin/wormhole-client -mode http -config configs/client.yaml
|
|
```
|
|
|
|
2. **配置浏览器代理:**
|
|
- HTTP代理: `127.0.0.1:8080`
|
|
- HTTPS代理: `127.0.0.1:8080`
|
|
|
|
3. **访问统计信息:**
|
|
```bash
|
|
curl http://127.0.0.1:8080/stats
|
|
```
|
|
|
|
4. **检查健康状态:**
|
|
```bash
|
|
curl http://127.0.0.1:8080/health
|
|
```
|
|
|
|
### 监控脚本示例
|
|
|
|
#### Bash监控脚本
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
|
|
PROXY_URL="http://127.0.0.1:8080"
|
|
|
|
echo "=== Wormhole SOCKS5 Client Status ==="
|
|
|
|
# 健康检查
|
|
health=$(curl -s "$PROXY_URL/health")
|
|
echo "Health: $health"
|
|
|
|
# 统计信息
|
|
stats=$(curl -s "$PROXY_URL/stats")
|
|
echo "Stats: $stats"
|
|
|
|
# 提取关键指标
|
|
success_rate=$(echo "$health" | jq -r '.success_rate')
|
|
active_conn=$(echo "$health" | jq -r '.active_connections')
|
|
|
|
echo "Success Rate: ${success_rate}%"
|
|
echo "Active Connections: $active_conn"
|
|
```
|
|
|
|
#### Python监控脚本
|
|
|
|
```python
|
|
import requests
|
|
import json
|
|
import time
|
|
|
|
def get_proxy_stats():
|
|
try:
|
|
response = requests.get('http://127.0.0.1:8080/stats')
|
|
return response.json()
|
|
except Exception as e:
|
|
print(f"Error getting stats: {e}")
|
|
return None
|
|
|
|
def get_proxy_health():
|
|
try:
|
|
response = requests.get('http://127.0.0.1:8080/health')
|
|
return response.json()
|
|
except Exception as e:
|
|
print(f"Error getting health: {e}")
|
|
return None
|
|
|
|
def monitor_proxy():
|
|
while True:
|
|
health = get_proxy_health()
|
|
if health:
|
|
print(f"Status: {health['status']}")
|
|
print(f"Success Rate: {health['success_rate']:.2f}%")
|
|
print(f"Active Connections: {health['active_connections']}")
|
|
print(f"Uptime: {health['uptime']}")
|
|
|
|
print("-" * 40)
|
|
time.sleep(30) # 每30秒检查一次
|
|
|
|
if __name__ == "__main__":
|
|
monitor_proxy()
|
|
```
|
|
|
|
## SOCKS5协议支持
|
|
|
|
### 地址类型支持
|
|
|
|
- ✅ **IPv4地址** (0x01): `192.168.1.1:80`
|
|
- ✅ **域名** (0x03): `example.com:80`
|
|
- ✅ **IPv6地址** (0x04): `[2001:db8::1]:80`
|
|
|
|
### 认证方法支持
|
|
|
|
- ✅ **无认证** (0x00)
|
|
- ✅ **用户名密码认证** (0x02)
|
|
|
|
### 错误处理
|
|
|
|
代理能够处理并报告以下SOCKS5错误：
|
|
|
|
| 错误码 | 含义 | 统计字段 |
|
|
|--------|------|----------|
|
|
| 0x01 | 一般SOCKS服务器故障 | `general_failure` |
|
|
| 0x02 | 连接不被规则集允许 | `not_allowed` |
|
|
| 0x03 | 网络不可达 | `network_unreachable` |
|
|
| 0x04 | 主机不可达 | `host_unreachable` |
|
|
| 0x05 | 连接被拒绝 | `connection_refused` |
|
|
| 0x06 | TTL过期 | `ttl_expired` |
|
|
| 0x07 | 不支持的命令 | `command_not_supported` |
|
|
| 0x08 | 不支持的地址类型 | `address_not_supported` |
|
|
|
|
## 性能特性
|
|
|
|
### 连接管理
|
|
- 异步处理多个并发连接
|
|
- 自动资源清理
|
|
- 超时管理
|
|
|
|
### 统计精度
|
|
- 原子操作保证并发安全
|
|
- 实时字节传输统计
|
|
- 详细的错误分类
|
|
|
|
### HTTP服务器配置
|
|
- 读取超时: 30秒
|
|
- 写入超时: 30秒
|
|
- 空闲超时: 120秒
|
|
- 最大头部大小: 1MB
|
|
|
|
## 故障排除
|
|
|
|
### 常见问题
|
|
|
|
1. **无法访问统计API**
|
|
- 确认代理运行在HTTP模式
|
|
- 检查端口是否正确
|
|
- 确认防火墙设置
|
|
|
|
2. **统计数据不准确**
|
|
- 重启代理服务
|
|
- 检查并发连接情况
|
|
|
|
3. **高错误率**
|
|
- 检查SOCKS5服务器状态
|
|
- 验证认证信息
|
|
- 查看网络连接质量
|
|
|
|
### 日志级别
|
|
|
|
设置 `logLevel: debug` 可以获得详细的调试信息：
|
|
|
|
```yaml
|
|
logLevel: debug # debug, info, warn, error
|
|
``` |