wormhole-client/README.md

# Wormhole SOCKS5 Client

[![Go Version](https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go)](https://go.dev/)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Build Status](https://img.shields.io/badge/Build-Passing-brightgreen.svg)]()

一个功能强大的 SOCKS5 代理客户端，支持多种代理模式，包括 HTTP 代理转换、全局代理设置和透明代理。

## ✨ 功能特性

- 🚀 **HTTP 代理模式**: 将 SOCKS5 代理转换为 HTTP/HTTPS 代理
- 🌍 **全局代理模式**: 自动配置系统级代理设置
- 🔍 **DNS 代理**: 提供 DNS 请求代理和缓存功能
- 🖥️ **系统集成**: 支持 macOS 系统代理自动配置和恢复
- 📝 **灵活配置**: 支持 YAML 配置文件和命令行参数
- 🛡️ **安全认证**: 支持 SOCKS5 用户名密码认证
- ⚡ **高性能**: 异步处理和连接池优化

## 🚀 快速开始

### 安装

#### 从源码编译

```bash
git clone http://101.34.16.52:3000/huyinsong/wormhole-client.git
cd wormhole-client
make build
```

#### 使用预编译二进制

```bash
# 安装到系统路径
make install
```

### 基本使用

1. **配置 SOCKS5 服务器信息**

编辑 `configs/client.yaml`:

```yaml
server:
  address: your-socks5-server.com
  port: 1080
  username: your-username
  password: your-password
```

2. **启动 HTTP 代理模式**

```bash
./bin/wormhole-client -mode http
```

3. **配置浏览器代理**
   - HTTP 代理: `127.0.0.1:8080`
   - HTTPS 代理: `127.0.0.1:8080`

## 📖 使用模式

### HTTP 代理模式

最常用的模式，将 SOCKS5 代理转换为 HTTP 代理：

```bash
# 使用默认配置
./bin/wormhole-client -mode http

# 指定端口
./bin/wormhole-client -mode http -config configs/custom.yaml
```

### 全局代理模式

自动配置系统代理，适合需要全局科学上网的场景：

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

**特性:**
- 自动配置系统 HTTP/HTTPS 代理
- 可选的 DNS 代理功能
- 程序退出时自动恢复原始设置
- 支持 Ctrl+C 安全退出

### 透明代理模式 (开发中)

```bash
sudo ./bin/wormhole-client -mode transparent
```

## ⚙️ 配置说明

### 完整配置示例

```yaml
# SOCKS5 服务器设置
server:
  address: 127.0.0.1
  port: 1080
  username: admin
  password: secure_password_123

# 代理模式设置
proxy:
  mode: http
  localPort: 8080

# 全局代理设置
globalProxy:
  enabled: false
  dnsProxy: true
  dnsPort: 5353
  
  # 路由规则
  routing:
    bypassLocal: true      # 跳过本地地址
    bypassPrivate: true    # 跳过私有网络
    bypassDomains:         # 跳过的域名
      - "*.local"
      - "*.lan"
    forceDomains:          # 强制代理的域名
      - "*.google.com"
      - "*.github.com"

# 日志设置
logLevel: info    # debug, info, warn, error
timeout: 30s
```

### 命令行选项

```bash
./bin/wormhole-client [选项]

选项:
  -config string
        配置文件路径 (默认 "configs/client.yaml")
  -mode string
        代理模式: http, global, transparent (默认 "http")
  -version
        显示版本信息
```

## 🏗️ 项目结构

```
wormhole-client/
├── cmd/wormhole-client/      # 主程序入口
├── internal/                 # 内部模块
│   ├── client/              # 客户端核心逻辑
│   ├── config/              # 配置解析模块
│   ├── proxy/               # SOCKS5 代理实现
│   └── system/              # 系统代理管理
├── pkg/                     # 公共模块
│   ├── dns/                # DNS 代理模块
│   └── logger/             # 日志模块
├── configs/                 # 配置文件
├── docs/                    # 文档
├── scripts/                 # 构建脚本
└── bin/                     # 编译输出
```

## 🔧 开发

### 编译和测试

```bash
# 编译
make build

# 运行测试
make test

# 代码检查
make lint

# 清理
make clean

# 开发模式运行
make dev
```

### 添加新功能

1. Fork 本项目
2. 创建功能分支
3. 编写代码和测试
4. 提交 Pull Request

## 📚 文档

- [使用指南](docs/usage.md) - 详细的使用说明
- [配置参考](docs/configuration.md) - 配置参数说明
- [故障排除](docs/troubleshooting.md) - 常见问题解决

## 🐛 故障排除

### 常见问题

1. **连接失败**
   - 检查 SOCKS5 服务器地址和端口
   - 验证用户名和密码
   - 确认网络连通性

2. **权限问题** (macOS)
   ```bash
   sudo ./bin/wormhole-client -mode global
   ```

3. **端口占用**
   - 修改配置文件中的 `localPort`
   - 检查端口是否被其他程序占用

### 调试模式

```bash
# 启用详细日志
./bin/wormhole-client -mode http
```

在配置文件中设置 `logLevel: debug` 获取详细信息。

## 🛡️ 安全说明

- 保护好包含密码的配置文件
- 仅在需要时使用管理员权限
- 确保 SOCKS5 服务器的安全性
- 使用 DNS 代理防止 DNS 泄露

## 📄 许可证

本项目采用 [MIT 许可证](LICENSE)。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📞 联系

- 项目地址: http://101.34.16.52:3000/huyinsong/wormhole-client.git
- 问题反馈: 请使用 GitHub Issues

---

**⭐ 如果这个项目对你有帮助，请给一个 Star！**