wormhole-client/docs/gui.md

# Web GUI 使用指南

## 概述

Wormhole SOCKS5 Client 内置了现代化的 Web GUI 管理界面，提供直观的图形界面来管理和监控代理服务。

## 🌟 **主要功能**

### ✅ **实时监控**
- **连接统计**: 总连接数、活跃连接、成功率等
- **流量统计**: 上传下载流量、传输字节数
- **运行状态**: 服务运行时间、健康状态

### ✅ **代理控制**
- **一键开关**: 启用/禁用系统代理设置
- **状态显示**: 实时显示代理配置状态
- **错误提示**: 详细的操作反馈和错误信息

### ✅ **路由配置**
- **域名规则**: 显示绕过和强制代理域名数量
- **网络设置**: 本地网络和私有网络绕过设置
- **统计信息**: 路由规则匹配统计

### ✅ **系统信息**
- **系统代理**: 当前系统代理配置
- **服务配置**: SOCKS5 服务器地址、端口等
- **操作系统**: 运行环境信息

## 🚀 **快速开始**

### 1. 启动服务

```bash
# HTTP 代理模式（推荐测试）
./bin/wormhole-client -mode http

# 全局代理模式（推荐使用）
sudo ./bin/wormhole-client -mode global
```

### 2. 访问 GUI

打开浏览器访问：

- **主界面**: http://127.0.0.1:8080/gui
- **JSON API**: http://127.0.0.1:8080/stats
- **健康检查**: http://127.0.0.1:8080/health

### 3. 界面功能

启动后你将看到现代化的管理界面：

```
🌐 Wormhole SOCKS5 Client                    [●] 服务运行中

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│   代理控制      │ │   连接统计      │ │   路由配置      │
│                 │ │                 │ │                 │
│ 模式: global    │ │ 总连接: 42      │ │ 绕过域名: 15    │
│ 服务器: xxx:xxx │ │ 活跃连接: 3     │ │ 强制域名: 25    │
│ 端口: 8080      │ │ 成功率: 95.2%   │ │ 本地绕过: 是    │
│ 系统: darwin    │ │ 运行时间: 2h15m │ │ 私网绕过: 是    │
│                 │ │ 传输流量: 1.2GB │ │                 │
│ [禁用系统代理]  │ │ 失败请求: 2     │ │                 │
│ [刷新状态]      │ │                 │ │                 │
└─────────────────┘ └─────────────────┘ └─────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                     系统信息                                │
│                                                             │
│ 系统代理状态: [已启用]                                      │
│ 当前代理设置:                                               │
│   http: 127.0.0.1:8080                                     │
│   https: 127.0.0.1:8080                                    │
└─────────────────────────────────────────────────────────────┘
```

## ⚙️ **功能详解**

### 代理控制面板

**基本信息显示**：
- 运行模式（HTTP/Global/Transparent）
- SOCKS5 服务器地址和端口
- 本地代理端口
- 操作系统类型

**操作按钮**：
- **启用/禁用系统代理**: 一键切换系统代理设置
- **刷新状态**: 手动刷新所有数据

### 连接统计面板

**实时数据**：
- **总连接数**: 自启动以来的总连接数
- **活跃连接**: 当前正在处理的连接数
- **成功率**: 成功请求与总请求的比例
- **运行时间**: 服务运行的总时间
- **传输流量**: 上传下载的总字节数
- **失败请求**: 失败的请求数量

### 路由配置面板

**智能分流信息**：
- **绕过域名数量**: 配置的直连域名规则数
- **强制代理域名**: 配置的代理域名规则数
- **绕过本地网络**: 是否绕过本地网络设置
- **绕过私有网络**: 是否绕过私有网络设置

### 系统信息面板

**系统代理状态**：
- **启用/禁用状态**: 当前系统代理是否启用
- **代理设置详情**: 具体的 HTTP/HTTPS 代理配置

## 🔧 **高级配置**

### 自定义端口

如果需要在不同端口运行 GUI：

```yaml
# configs/client.yaml
proxy:
  localPort: 8888  # 修改端口

# GUI 将在 http://127.0.0.1:8888/gui 提供服务
```

### 外部访问

默认 GUI 只能从本地访问。如需外部访问：

```bash
# 使用端口转发（SSH隧道）
ssh -L 8080:127.0.0.1:8080 username@your-server

# 然后在本地访问: http://127.0.0.1:8080/gui
```

### API 集成

GUI 基于 RESTful API 构建，可以与其他工具集成：

```bash
# 获取状态信息
curl http://127.0.0.1:8080/api/status

# 切换代理状态
curl -X POST http://127.0.0.1:8080/api/proxy/toggle \
  -H "Content-Type: application/json" \
  -d '{"enable": true}'

# 获取路由统计
curl http://127.0.0.1:8080/api/routing/stats
```

## 📱 **响应式设计**

GUI 支持多种设备：

- **桌面端**: 全功能四面板布局
- **平板端**: 自适应两列布局
- **手机端**: 单列垂直布局

### 移动端优化

在手机上访问时，界面会自动调整：
- 简化的按钮和控件
- 更大的触摸目标
- 优化的字体大小

## 🔄 **实时更新**

### 自动刷新

GUI 每 5 秒自动更新数据，包括：
- 连接统计
- 代理状态
- 系统信息
- 路由统计

### 智能刷新

**页面可见性检测**：
- 当页面在后台时停止自动刷新
- 切换回前台时立即恢复更新
- 节省系统资源和网络带宽

### 手动刷新

点击 "刷新状态" 按钮立即更新所有数据。

## 🎨 **界面特性**

### 现代化设计

- **毛玻璃效果**: 半透明背景增强视觉层次
- **渐变背景**: 美观的紫色渐变背景
- **卡片布局**: 清晰的信息分组
- **图标支持**: 使用 Font Awesome 图标

### 交互反馈

- **悬停效果**: 按钮和卡片的悬停动画
- **加载状态**: 操作进行时的加载指示
- **状态指示**: 颜色编码的状态点
- **动画效果**: 平滑的过渡动画

### 状态显示

**连接状态指示器**：
- 🟢 **绿色**: 服务正常运行
- 🟡 **黄色**: 正在检查状态
- 🔴 **红色**: 服务异常或连接失败

## ⚠️ **注意事项**

### 安全考虑

1. **本地访问**: GUI 默认只绑定本地地址
2. **无认证**: 当前版本无需登录验证
3. **HTTPS**: 建议通过 HTTPS 代理访问

### 性能影响

1. **轻量级**: GUI 对系统资源占用很小
2. **异步更新**: 不影响代理性能
3. **缓存优化**: 静态资源缓存减少网络请求

### 浏览器兼容

**支持的浏览器**：
- ✅ Chrome/Chromium 70+
- ✅ Firefox 65+
- ✅ Safari 12+
- ✅ Edge 79+

**推荐浏览器**: Chrome 或 Firefox 最新版本

## 🔧 **故障排除**

### 常见问题

#### 1. 无法访问 GUI

```
问题: 浏览器显示"无法访问此网站"
解决: 检查服务是否启动，端口是否正确
```

```bash
# 检查服务状态
curl http://127.0.0.1:8080/health

# 检查端口占用
netstat -an | grep 8080
```

#### 2. 页面加载不完整

```
问题: 页面样式错乱或功能不正常
解决: 清除浏览器缓存，刷新页面
```

```bash
# 强制刷新页面: Ctrl+F5 (Windows) 或 Cmd+Shift+R (Mac)
```

#### 3. 代理切换失败

```
问题: 点击代理开关无效果
解决: 检查管理员权限，查看错误信息
```

```bash
# macOS/Linux: 使用 sudo 运行
sudo ./bin/wormhole-client -mode global

# Windows: 以管理员身份运行
```

#### 4. 数据不更新

```
问题: 统计数据停止更新
解决: 检查网络连接，手动刷新
```

### 调试模式

启用详细日志查看 GUI 相关信息：

```bash
# 设置日志级别为 debug
export LOG_LEVEL=debug
./bin/wormhole-client -mode global
```

查看 GUI 相关日志：

```
[DEBUG] GUI server initialized
[DEBUG] Serving GUI at /gui
[DEBUG] API request: GET /api/status
[DEBUG] GUI template rendered successfully
```

## 📚 **开发和定制**

### 模板系统

GUI 使用 Go 内置模板系统：

- **HTML 模板**: 存储在代码中，支持数据绑定
- **CSS 样式**: 响应式设计，支持深色主题
- **JavaScript**: 现代 ES6+ 语法，模块化设计

### API 端点

GUI 基于以下 API 端点：

```
GET  /api/status         - 获取服务状态
GET  /api/config         - 获取配置信息
POST /api/proxy/toggle   - 切换代理状态
GET  /api/routing/stats  - 获取路由统计
GET  /api/system/proxy   - 获取系统代理信息
```

### 自定义样式

如需修改界面样式，可以编辑 `internal/gui/templates.go` 中的 CSS：

```go
// 修改主题色彩
.panel-header {
    background: linear-gradient(135deg, #your-color1, #your-color2);
}
```

## 📖 **相关链接**

- 📊 [API 文档](api.md) - 详细的 API 接口说明
- 🌍 [全局代理指南](global-proxy.md) - 全局代理模式使用说明
- 📋 [配置参考](../configs/client.yaml) - 完整的配置文件示例
- 🏠 [项目主页](../README.md) - 项目总体介绍

---

**💡 提示**: GUI 界面会持续改进，欢迎提出建议和反馈！