|
|
# Wormhole SOCKS5 Client 使用指南
|
|
|
|
|
|
## 概述
|
|
|
|
|
|
Wormhole SOCKS5 Client 是一个功能强大的代理客户端，支持多种代理模式，可以将 SOCKS5 代理转换为 HTTP 代理，并提供全局代理和透明代理功能。
|
|
|
|
|
|
## 功能特性
|
|
|
|
|
|
- ✅ **HTTP 代理模式**: 将 SOCKS5 代理转换为 HTTP/HTTPS 代理
|
|
|
- ✅ **全局代理模式**: 自动配置系统级代理设置
|
|
|
- ✅ **DNS 代理**: 提供 DNS 请求代理和缓存
|
|
|
- ✅ **系统集成**: 支持 macOS 系统代理自动配置
|
|
|
- ⚠️ **透明代理模式**: 计划实现（需要 root 权限）
|
|
|
|
|
|
## 安装
|
|
|
|
|
|
### 从源码编译
|
|
|
|
|
|
```bash
|
|
|
git clone http://101.34.16.52:3000/huyinsong/wormhole-client.git
|
|
|
cd wormhole-client
|
|
|
make build
|
|
|
```
|
|
|
|
|
|
### 使用预编译二进制
|
|
|
|
|
|
```bash
|
|
|
# 下载并安装到 /usr/local/bin
|
|
|
make install
|
|
|
```
|
|
|
|
|
|
## 配置文件
|
|
|
|
|
|
配置文件位于 `configs/client.yaml`，包含以下主要配置：
|
|
|
|
|
|
```yaml
|
|
|
# SOCKS5 服务器设置
|
|
|
server:
|
|
|
address: 127.0.0.1
|
|
|
port: 1080
|
|
|
username: admin
|
|
|
password: secure_password_123
|
|
|
|
|
|
# 代理模式设置
|
|
|
proxy:
|
|
|
mode: http # http, global, transparent
|
|
|
localPort: 8080
|
|
|
|
|
|
# 全局代理设置
|
|
|
globalProxy:
|
|
|
enabled: false
|
|
|
dnsProxy: true
|
|
|
dnsPort: 5353
|
|
|
|
|
|
# 分流规则
|
|
|
routing:
|
|
|
bypassLocal: true
|
|
|
bypassPrivate: true
|
|
|
bypassDomains:
|
|
|
- "*.local"
|
|
|
- "*.lan"
|
|
|
forceDomains:
|
|
|
- "*.google.com"
|
|
|
- "*.github.com"
|
|
|
|
|
|
# 日志级别
|
|
|
logLevel: info
|
|
|
timeout: 30s
|
|
|
```
|
|
|
|
|
|
## 使用方法
|
|
|
|
|
|
### 1. HTTP 代理模式
|
|
|
|
|
|
最简单的使用方式，将 SOCKS5 代理转换为 HTTP 代理：
|
|
|
|
|
|
```bash
|
|
|
# 使用默认配置
|
|
|
./bin/wormhole-client -mode http
|
|
|
|
|
|
# 指定配置文件
|
|
|
./bin/wormhole-client -mode http -config /path/to/config.yaml
|
|
|
```
|
|
|
|
|
|
启动后，在浏览器中配置 HTTP 代理：
|
|
|
- 代理地址: `127.0.0.1`
|
|
|
- 代理端口: `8080` (或配置文件中指定的端口)
|
|
|
|
|
|
### 2. 全局代理模式
|
|
|
|
|
|
自动配置系统级代理，所有应用程序都将通过代理访问网络：
|
|
|
|
|
|
```bash
|
|
|
# 需要管理员权限 (macOS)
|
|
|
sudo ./bin/wormhole-client -mode global
|
|
|
```
|
|
|
|
|
|
**注意**:
|
|
|
- macOS 系统需要管理员权限
|
|
|
- 程序退出时会自动恢复原始代理设置
|
|
|
- 可以使用 Ctrl+C 安全退出
|
|
|
|
|
|
### 3. 透明代理模式 (计划实现)
|
|
|
|
|
|
```bash
|
|
|
# 需要 root 权限
|
|
|
sudo ./bin/wormhole-client -mode transparent
|
|
|
```
|
|
|
|
|
|
## 命令行选项
|
|
|
|
|
|
```bash
|
|
|
./bin/wormhole-client [选项]
|
|
|
|
|
|
选项:
|
|
|
-config string
|
|
|
配置文件路径 (默认 "configs/client.yaml")
|
|
|
-mode string
|
|
|
客户端模式: http, global, transparent (默认 "http")
|
|
|
-version
|
|
|
显示版本信息
|
|
|
```
|
|
|
|
|
|
## 使用场景
|
|
|
|
|
|
### 场景 1: 浏览器代理
|
|
|
|
|
|
1. 启动 HTTP 代理模式
|
|
|
2. 在浏览器中配置 HTTP 代理为 `127.0.0.1:8080`
|
|
|
3. 访问被墙网站
|
|
|
|
|
|
### 场景 2: 全局科学上网
|
|
|
|
|
|
1. 以管理员权限启动全局代理模式
|
|
|
2. 系统所有网络请求自动通过代理
|
|
|
3. 支持 DNS 代理，解决 DNS 污染问题
|
|
|
|
|
|
### 场景 3: 开发调试
|
|
|
|
|
|
1. 使用 HTTP 代理模式
|
|
|
2. 配置开发工具使用代理
|
|
|
3. 调试网络请求和响应
|
|
|
|
|
|
## 故障排除
|
|
|
|
|
|
### 连接失败
|
|
|
|
|
|
1. 检查 SOCKS5 服务器地址和端口
|
|
|
2. 验证用户名和密码
|
|
|
3. 确认网络连通性
|
|
|
|
|
|
### 权限问题
|
|
|
|
|
|
```bash
|
|
|
# macOS 全局代理需要管理员权限
|
|
|
sudo ./bin/wormhole-client -mode global
|
|
|
|
|
|
# 检查系统代理设置
|
|
|
networksetup -getwebproxy Wi-Fi
|
|
|
```
|
|
|
|
|
|
### 日志调试
|
|
|
|
|
|
```bash
|
|
|
# 启用详细日志
|
|
|
./bin/wormhole-client -mode http -config configs/debug.yaml
|
|
|
```
|
|
|
|
|
|
在配置文件中设置 `logLevel: debug` 获取详细日志信息。
|
|
|
|
|
|
## 安全注意事项
|
|
|
|
|
|
1. **配置文件安全**: 保护好包含密码的配置文件
|
|
|
2. **管理员权限**: 仅在需要时使用管理员权限
|
|
|
3. **网络安全**: 确保 SOCKS5 服务器的安全性
|
|
|
4. **DNS 泄露**: 使用 DNS 代理防止 DNS 泄露
|
|
|
|
|
|
## 开发和贡献
|
|
|
|
|
|
### 编译和测试
|
|
|
|
|
|
```bash
|
|
|
# 编译
|
|
|
make build
|
|
|
|
|
|
# 运行测试
|
|
|
make test
|
|
|
|
|
|
# 检查代码质量
|
|
|
make lint
|
|
|
|
|
|
# 清理构建文件
|
|
|
make clean
|
|
|
```
|
|
|
|
|
|
### 代码结构
|
|
|
|
|
|
```
|
|
|
├── cmd/wormhole-client/ # 主程序入口
|
|
|
├── internal/ # 内部模块
|
|
|
│ ├── client/ # 客户端核心逻辑
|
|
|
│ ├── config/ # 配置解析
|
|
|
│ ├── proxy/ # SOCKS5 代理实现
|
|
|
│ └── system/ # 系统代理管理
|
|
|
├── pkg/ # 公共模块
|
|
|
│ ├── dns/ # DNS 代理
|
|
|
│ └── logger/ # 日志模块
|
|
|
└── configs/ # 配置文件
|
|
|
```
|
|
|
|
|
|
## 许可证
|
|
|
|
|
|
本项目采用 MIT 许可证，详情请参见 LICENSE 文件。 |
