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：

# 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. 启动全局代理

# 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

⚙️ 高级配置

智能分流规则

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

性能优化

# 性能调优配置
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 系统会自动配置以下设置：

# 查看当前代理配置
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 系统通过注册表配置：

# 查看当前代理设置
$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 系统通过环境变量配置：

# 查看当前代理设置
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

统计信息示例

{
  "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
  }
}

命令行监控

# 查看实时统计
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
• 停止占用端口的其他服务

调试模式

启用详细日志进行调试：

# 配置文件中设置
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: 开发者环境

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

场景 2: 办公环境

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

场景 3: 家庭使用

# 适合家庭用户的配置
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 文档
• 配置参考
• 故障排除
• 项目主页