# 全局代理模式使用指南 ## 概述 全局代理模式是 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)