wormhole-client/README.md

# Wormhole SOCKS5 Client

[![Go Version](https://img.shields.io/badge/Go-1.19+-blue.svg)](https://golang.org)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Build Status](https://img.shields.io/badge/Build-Passing-brightgreen.svg)](.github/workflows)

一个功能强大的 SOCKS5 代理客户端，支持 HTTP 代理转换、全局代理、智能分流和实时监控。

## ✨ **核心特性**

### 🌐 **多种代理模式**
- ✅ **HTTP 代理模式**: 将 SOCKS5 转换为 HTTP/HTTPS 代理，兼容浏览器和应用
- ✅ **全局代理模式**: 自动配置系统级代理，支持 macOS/Windows/Linux
- ⚠️ **透明代理模式**: 透明流量拦截（计划实现）

### 🛣️ **智能路由分流**
- 🎯 **精确匹配**: 支持域名通配符和正则表达式
- 🏠 **本地绕过**: 自动识别本地网络和私有网络
- 🌍 **国际访问**: 特定域名强制走代理（Google、GitHub、Twitter等）
- 🇨🇳 **国内直连**: 中国域名和服务直接访问

### 📊 **实时监控**
- 📈 **详细统计**: 连接数、成功率、流量统计、错误分类
- 💚 **健康检查**: RESTful API 端点，支持监控系统集成
- 🔍 **性能指标**: 响应时间、并发连接、字节传输统计
- 🖥️ **Web GUI**: 现代化图形界面，实时监控和管理

### 🔒 **安全特性**
- 🛡️ **认证支持**: 用户名密码认证和无认证模式
- 🌐 **协议完整**: 完整的 SOCKS5 协议实现，支持 IPv4/IPv6
- 🔐 **DNS 安全**: 防止 DNS 污染和泄露

## 🚀 **快速开始**

### 安装方式

```bash
# 方式 1: 从源码编译
git clone http://101.34.16.52:3000/huyinsong/wormhole-client.git
cd wormhole-client
make build

# 方式 2: 直接下载二进制文件
# (根据你的系统下载对应版本)
```

### 基本使用

#### 1. HTTP 代理模式 (推荐新手)

```bash
# 启动 HTTP 代理
./bin/wormhole-client -mode http

# 配置浏览器代理: 127.0.0.1:8080
# 访问 Web GUI: http://127.0.0.1:8080/gui
# 访问统计API: http://127.0.0.1:8080/stats
```

#### 2. 全局代理模式 (推荐进阶用户)

```bash
# macOS/Linux (需要 sudo)
sudo ./bin/wormhole-client -mode global

# Windows (以管理员身份运行)
./bin/wormhole-client.exe -mode global
```

**全局代理功能**：
- 🔧 **自动配置**: 自动设置系统 HTTP/HTTPS 代理
- 🌍 **全局生效**: 所有应用程序自动使用代理
- 🛣️ **智能分流**: 根据域名规则自动选择直连或代理
- 🔍 **DNS 代理**: 防止 DNS 污染，支持自定义 DNS 服务器
- 💻 **跨平台**: 支持 macOS、Windows、Linux 系统

#### 3. 配置文件示例

```yaml
# configs/client.yaml
server:
  address: your_socks5_server.com
  port: 1080
  username: your_username
  password: your_password

proxy:
  mode: global
  localPort: 8080

globalProxy:
  enabled: true
  dnsProxy: true
  dnsPort: 5353
  
  routing:
    bypassLocal: true
    bypassPrivate: true
    bypassDomains:
      - "*.cn"
      - "*.baidu.com"
      - "*.qq.com"
    forceDomains:
      - "*.google.com"
      - "*.github.com"
      - "*.youtube.com"
```

## 📋 **详细功能**

### HTTP 代理模式

将 SOCKS5 代理转换为标准的 HTTP 代理：

```bash
./bin/wormhole-client -mode http
```

- 📱 **浏览器兼容**: 支持所有主流浏览器
- 🔗 **HTTPS 支持**: 完整的 CONNECT 方法支持
- 📊 **实时监控**: 内置 Web 管理界面

**使用场景**：
- 浏览器科学上网
- 开发调试代理
- 应用程序代理配置

### 全局代理模式

自动配置系统级代理设置：

```bash
# 启动全局代理 (需要管理员权限)
sudo ./bin/wormhole-client -mode global
```

**核心优势**：
- 🌍 **系统级代理**: 自动配置系统代理设置
- 🚀 **零配置**: 启动即用，无需手动设置
- 🛣️ **智能分流**: 国内外流量自动分流
- 🔍 **DNS 代理**: 解决 DNS 污染问题
- 🔄 **优雅退出**: 程序退出时自动恢复原始设置

**系统支持**：
- 🍎 **macOS**: 通过 `networksetup` 配置网络偏好设置
- 🪟 **Windows**: 通过注册表配置 Internet 设置
- 🐧 **Linux**: 通过环境变量和系统文件配置

### 智能路由分流

高级流量分流功能：

```yaml
routing:
  # 直连规则
  bypassLocal: true      # 本地地址直连
  bypassPrivate: true    # 私有网络直连
  bypassDomains:         # 指定域名直连
    - "*.cn"             # 中国域名
    - "*.baidu.com"      # 百度服务
    
  # 代理规则  
  forceDomains:          # 强制代理域名
    - "*.google.com"     # Google 服务
    - "*.github.com"     # GitHub
    - "*.youtube.com"    # YouTube
```

**智能判断逻辑**：
1. 🎯 **强制代理**: 匹配 `forceDomains` 的域名强制走代理
2. 🏠 **直连绕过**: 匹配 `bypassDomains` 或本地网络直接访问
3. 🤖 **自动决策**: 其他流量根据配置自动选择

## 🔧 **命令行选项**

```bash
./bin/wormhole-client [选项]

选项:
  -config string
        配置文件路径 (默认 "configs/client.yaml")
  -mode string
        代理模式: http, global, transparent (默认 "http")
  -version
        显示版本信息
  -help
        显示帮助信息
```

## 📊 **监控和管理**

### Web 管理界面

启动后访问以下端点：

- 🖥️ **Web GUI**: `http://127.0.0.1:8080/gui` (图形管理界面)
- 📊 **统计信息**: `http://127.0.0.1:8080/stats`
- 💚 **健康检查**: `http://127.0.0.1:8080/health`
- 🌐 **代理服务**: `http://127.0.0.1:8080/` (HTTP 代理入口)

### API 示例

```bash
# 获取统计信息
curl http://127.0.0.1:8080/stats

# 健康检查
curl http://127.0.0.1:8080/health

# 实时监控
watch -n 5 'curl -s http://127.0.0.1:8080/health | jq .success_rate'
```

### 统计信息

```json
{
  "start_time": "2024-01-01T12:00:00Z",
  "uptime": "2h30m15s",
  "total_connections": 150,
  "active_connections": 5,
  "successful_requests": 145,
  "failed_requests": 5,
  "success_rate": 96.67,
  "bytes_sent": 1024000,
  "bytes_received": 2048000,
  "socks5_errors": {
    "connection_failed": 3,
    "auth_failed": 1
  }
}
```

## ⚙️ **配置说明**

### 完整配置示例

```yaml
# SOCKS5 服务器设置
server:
  address: 127.0.0.1
  port: 1080
  username: admin
  password: secure_password_123

# 代理模式设置
proxy:
  mode: global
  localPort: 8080

# 全局代理设置
globalProxy:
  enabled: true
  dnsProxy: true
  dnsPort: 5353
  
  # 智能分流路由规则
  routing:
    bypassLocal: true
    bypassPrivate: true
    bypassDomains:
      - "*.local"
      - "*.cn"
      - "*.baidu.com"
    forceDomains:
      - "*.google.com"
      - "*.github.com"

# 性能调优
performance:
  connectionPool:
    maxSize: 100
    maxIdleTime: "300s"
  timeouts:
    connect: "10s"
    read: "30s"

# 安全设置
security:
  verifySSL: true
  allowedProtocols:
    - "http"
    - "https"

# 日志设置
logLevel: info
timeout: 30s
```

## 🏗️ **项目结构**

```
wormhole-client/
├── cmd/wormhole-client/      # 主程序入口
├── internal/                 # 内部模块
│   ├── client/              # 客户端核心逻辑
│   ├── config/              # 配置解析模块
│   ├── proxy/               # SOCKS5 代理实现
│   ├── routing/             # 智能路由模块
│   └── system/              # 系统代理管理
├── pkg/                     # 公共模块
│   ├── dns/                # DNS 代理模块
│   └── logger/             # 日志模块
├── configs/                 # 配置文件
├── docs/                    # 文档
│   ├── api.md              # API 文档
│   ├── global-proxy.md     # 全局代理使用指南
│   └── usage.md            # 使用说明
├── scripts/                 # 构建脚本
└── bin/                     # 编译输出
```

## 🔧 **开发**

### 编译和测试

```bash
# 安装依赖
make deps

# 编译
make build

# 运行测试
make test

# 代码检查
make lint

# 生成覆盖率报告
make coverage

# 完整检查
make check
```

### 运行模式

```bash
# HTTP 代理模式
make run-http

# 全局代理模式 (需要 sudo)
make run-global

# 透明代理模式 (开发中)
make run-transparent
```

## 📖 **使用场景**

### 开发者场景

```yaml
# 适合开发者的全局代理配置
globalProxy:
  routing:
    forceDomains:
      - "*.github.com"
      - "*.stackoverflow.com"
      - "*.npmjs.com"
      - "*.docker.com"
    bypassDomains:
      - "*.local"
      - "localhost"
```

### 办公环境

```yaml
# 适合办公环境的配置
globalProxy:
  routing:
    bypassLocal: true
    bypassPrivate: true
    forceDomains:
      - "*.google.com"
      - "*.zoom.us"
      - "*.dropbox.com"
```

### 家庭使用

```yaml
# 适合家庭用户的配置
globalProxy:
  routing:
    forceDomains:
      - "*.youtube.com"
      - "*.netflix.com"
      - "*.twitter.com"
    bypassDomains:
      - "*.cn"
      - "*.baidu.com"
```

## 🔧 **故障排除**

### 常见问题

#### 1. 权限问题

```bash
❌ Failed to set system proxy: permission denied
```

**解决方案**:
- macOS/Linux: 使用 `sudo ./bin/wormhole-client -mode global`
- Windows: 以管理员身份运行程序

#### 2. 连接失败

```bash
❌ Failed to connect via SOCKS5: connection refused
```

**解决方案**:
- 检查 SOCKS5 服务器地址和端口
- 验证用户名和密码
- 确认网络连通性

#### 3. 端口占用

```bash
⚠️ Failed to start DNS proxy: bind: address already in use
```

**解决方案**:
- 更改端口: `localPort: 8081`
- 停止占用端口的其他程序

### 调试模式

```yaml
# 启用详细日志
logLevel: debug
```

或使用环境变量：

```bash
export LOG_LEVEL=debug
./bin/wormhole-client -mode global
```

## 🛡️ **安全注意事项**

1. **配置文件安全**: 
   - 使用强密码
   - 设置文件权限: `chmod 600 configs/client.yaml`
   - 避免在公开仓库提交密码

2. **系统安全**:
   - 仅在需要时使用管理员权限
   - 定期更新客户端版本
   - 使用可信的 SOCKS5 服务器

3. **网络安全**:
   - 启用 SSL 证书验证
   - 定期检查代理设置
   - 监控异常流量

## 📚 **文档链接**

- 🖥️ [Web GUI 使用指南](docs/gui.md) - 图形界面使用和功能介绍
- 📖 [全局代理使用指南](docs/global-proxy.md) - 详细的全局代理配置和使用说明
- 📊 [API 文档](docs/api.md) - RESTful API 接口说明
- 🔧 [配置参考](configs/client.yaml) - 完整的配置文件示例
- 📋 [使用说明](docs/usage.md) - 各种使用场景和技巧

## 🤝 **贡献**

欢迎提交 Issue 和 Pull Request！

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

## 📄 **许可证**

本项目采用 [MIT License](LICENSE) 许可证。

## 🙏 **致谢**

感谢所有贡献者和使用者的支持！

---

**⭐ 如果这个项目对你有帮助，请给个 Star！**