wormhole-client/docs/global-proxy.md

# 全局代理模式使用指南

## 概述

全局代理模式是 Wormhole SOCKS5 Client 的核心功能之一，它可以自动配置系统级代理设置，让所有应用程序都通过 SOCKS5 代理访问网络。

## 🌟 **主要特性**

### ✅ **系统级代理配置**
- **macOS**: 自动配置网络偏好设置中的 HTTP/HTTPS 代理
- **Windows**: 通过注册表配置系统代理设置  
- **Linux**: 配置环境变量和系统代理文件

### ✅ **智能路由分流**
- **绕过规则**: 本地网络、私有网络、指定域名直连
- **强制代理**: 特定域名强制走代理（如 Google、GitHub 等）
- **自动决策**: 其他流量根据配置自动选择路由

### ✅ **DNS 代理支持**
- 防止 DNS 污染和泄露
- 支持自定义 DNS 服务器
- 提供 DNS 缓存功能

### ✅ **实时监控**
- Web 界面统计信息
- 健康状态检查
- 详细的连接和字节传输统计

## 🚀 **快速开始**

### 1. 基本配置

编辑配置文件 `configs/client.yaml`：

```yaml
# SOCKS5 服务器设置
server:
  address: your_socks5_server.com  # 替换为你的 SOCKS5 服务器
  port: 1080
  username: your_username          # 替换为用户名
  password: your_password          # 替换为密码

# 启用全局代理模式
proxy:
  mode: global
  localPort: 8080

# 全局代理配置  
globalProxy:
  enabled: true
  dnsProxy: true
  dnsPort: 5353
```

### 2. 启动全局代理

```bash
# macOS/Linux (需要管理员权限)
sudo ./bin/wormhole-client -mode global

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

### 3. 验证配置

启动后检查以下信息：

```
🌍 Starting global proxy mode...
✅ System proxy configured successfully  
✅ DNS proxy started
🛣️  Route matcher initialized
📊 Statistics: http://127.0.0.1:8080/stats
💚 Health check: http://127.0.0.1:8080/health
```

## ⚙️ **高级配置**

### 智能分流规则

```yaml
globalProxy:
  routing:
    # 基础规则
    bypassLocal: true      # 绕过本地地址
    bypassPrivate: true    # 绕过私有网络
    
    # 直连域名 (不走代理)
    bypassDomains:
      - "*.cn"             # 中国域名
      - "*.baidu.com"      # 百度系列
      - "*.taobao.com"     # 淘宝系列  
      - "*.qq.com"         # 腾讯系列
      - "*.local"          # 本地域名
      
    # 强制代理域名 (必须走代理)  
    forceDomains:
      - "*.google.com"     # Google 服务
      - "*.youtube.com"    # YouTube
      - "*.github.com"     # GitHub
      - "*.twitter.com"    # Twitter
      - "*.facebook.com"   # Facebook
```

### 性能优化

```yaml
# 性能调优配置
performance:
  connectionPool:
    maxSize: 100          # 连接池大小
    maxIdleTime: "300s"   # 最大空闲时间
    
  timeouts:
    connect: "10s"        # 连接超时
    handshake: "5s"       # 握手超时
    read: "30s"           # 读取超时
    write: "30s"          # 写入超时
    
  cache:
    dnsCache: true        # 启用 DNS 缓存
    dnsCacheSize: 1000    # 缓存大小
    dnsCacheTTL: "3600s"  # 缓存生存时间
```

## 🖥️ **系统特定配置**

### macOS 配置

macOS 系统会自动配置以下设置：

```bash
# 查看当前代理配置
networksetup -getwebproxy Wi-Fi
networksetup -getsecurewebproxy Wi-Fi

# 手动配置 (如果自动配置失败)
networksetup -setwebproxy Wi-Fi 127.0.0.1 8080
networksetup -setsecurewebproxy Wi-Fi 127.0.0.1 8080
```

### Windows 配置

Windows 系统通过注册表配置：

```powershell
# 查看当前代理设置
$regPath = "HKCU:\Software\Microsoft\Windows\CurrentVersion\Internet Settings"
Get-ItemProperty -Path $regPath -Name ProxyEnable
Get-ItemProperty -Path $regPath -Name ProxyServer

# 手动配置 (如果自动配置失败)
Set-ItemProperty -Path $regPath -Name ProxyEnable -Value 1
Set-ItemProperty -Path $regPath -Name ProxyServer -Value "127.0.0.1:8080"
```

### Linux 配置

Linux 系统通过环境变量配置：

```bash
# 查看当前代理设置
echo $http_proxy
echo $https_proxy

# 手动配置 (如果自动配置失败)
export http_proxy=http://127.0.0.1:8080
export https_proxy=http://127.0.0.1:8080
export HTTP_PROXY=http://127.0.0.1:8080
export HTTPS_PROXY=http://127.0.0.1:8080
```

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

### Web 管理界面

访问以下地址查看统计信息：

- **统计信息**: http://127.0.0.1:8080/stats
- **健康检查**: http://127.0.0.1:8080/health

### 统计信息示例

```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
  }
}
```

### 命令行监控

```bash
# 查看实时统计
curl -s http://127.0.0.1:8080/stats | jq

# 健康检查
curl -s http://127.0.0.1:8080/health | jq

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

## 🔧 **故障排除**

### 常见问题

#### 1. 权限不足

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

**解决方案**:
- macOS/Linux: 使用 `sudo` 运行
- Windows: 以管理员身份运行

#### 2. 代理设置失败

```
⚠️ You may need to run with administrator privileges
📋 Manual setup instructions:
   - Set HTTP proxy to: 127.0.0.1:8080
   - Set HTTPS proxy to: 127.0.0.1:8080
```

**解决方案**: 按照提示手动配置系统代理设置

#### 3. SOCKS5 连接失败

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

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

#### 4. DNS 解析问题

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

**解决方案**:
- 更改 DNS 代理端口: `dnsPort: 5354`
- 停止占用端口的其他服务

### 调试模式

启用详细日志进行调试：

```yaml
# 配置文件中设置
logLevel: debug

# 或使用环境变量
export LOG_LEVEL=debug
```

调试日志示例：

```
[DEBUG] Route matcher initialized with 15 bypass domains, 25 force domains
[DEBUG] Using network service: Wi-Fi
[DEBUG] Host www.google.com matches force domains - using proxy
[DEBUG] Host www.baidu.com matches bypass domains - using direct
[DEBUG] IP 192.168.1.1 is private - using direct
```

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

### 1. 配置文件安全
- 使用强密码
- 限制配置文件访问权限: `chmod 600 configs/client.yaml`
- 不要在公开仓库中提交包含密码的配置

### 2. 网络安全
- 使用可信的 SOCKS5 服务器
- 启用 SSL 证书验证: `verifySSL: true`
- 定期更新客户端版本

### 3. 系统安全
- 仅在需要时使用管理员权限
- 定期检查系统代理设置
- 程序退出时自动恢复原始设置

## 📖 **使用场景**

### 场景 1: 开发者环境

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

### 场景 2: 办公环境

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

### 场景 3: 家庭使用

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

## 🔄 **安全退出**

全局代理支持优雅停止，按 `Ctrl+C` 时会：

1. **停止 HTTP 服务器** (最多等待 5 秒)
2. **恢复系统代理设置** 
3. **停止 DNS 代理**
4. **显示最终统计信息**
5. **清理所有资源**

```
🛑 Received shutdown signal...
🔄 Shutting down gracefully...
✅ HTTP server stopped
🔄 Restoring system proxy settings...  
✅ System proxy restored successfully
🔄 Stopping DNS proxy...
✅ DNS proxy stopped
📊 Final statistics:
   - Total connections: 42
   - Success rate: 95.24%
   - Total bytes: 1048576
   - Uptime: 15m30s
✅ Cleanup completed
```

## 📚 **相关链接**

- [API 文档](api.md)
- [配置参考](../configs/client.yaml)
- [故障排除](../README.md#故障排除)
- [项目主页](../README.md)