# 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 文件。