# gui_hclient

**Repository Path**: rich_mona/gui_hclient

## Basic Information

- **Project Name**: gui_hclient
- **Description**: GUI版本hclient工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-01
- **Last Updated**: 2026-03-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HClient GUI

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-Windows-blue.svg)]()
[![Python](https://img.shields.io/badge/python-3.6+-blue.svg)]()

基于 [hclient-cli](https://github.com/lazycatlabs/hclient-cli) 的 Windows 图形界面客户端，支持 TUN 模式代理，用于连接和管理懒猫微服（Heiyu Space）。

## ✨ 功能特性

- 🚀 **一键启动**：程序启动时自动启动 hclient-cli（TUN 模式）
- 🔐 **登录管理**：通过 GUI 界面添加/管理微服务节点
- 🚪 **退出登录**：支持删除微服务节点（退出登录）
- 🎯 **系统托盘**：关闭窗口后最小化到系统托盘，后台保持运行
- 📊 **状态监控**：实时显示客户端连接状态和微服务列表
- 🪟 **兼容性强**：支持 Windows 7/8/10/11（64 位）

## 📁 文件说明

| 文件 | 说明 |
|------|------|
| `HClientGUI.exe` | 主程序（打包后的可执行文件） |
| `hclient-cli-windows-amd64.exe` | hclient-cli 核心工具（必需） |
| `wintun.dll` | Windows TUN 驱动（必需） |
| `hclient_gui.py` | Python 源代码 |
| `build.py` | PyInstaller 打包脚本 |
| `requirements.txt` | Python 依赖列表 |

## 🚀 快速开始

### 方式一：使用预编译版本（推荐）

1. 下载最新发布的 `gui_hclient_v1.0.zip`
2. 解压到任意目录（建议路径不含中文和空格）
3. **右键 → 以管理员身份运行** `HClientGUI.exe`
4. 点击"登录"按钮，输入微服信息

### 方式二：从源码运行

**环境要求：**
- Python 3.6 或更高版本
- Windows 7/8/10/11 (64位)

**安装步骤：**

```bash
# 1. 克隆仓库
git clone https://gitee.com/rich_mona/gui_hclient.git
cd gui_hclient

# 2. 安装依赖
pip install -r requirements.txt

# 3. 运行程序
python hclient_gui.py
```

## 📦 自行打包

如需自行打包为可执行文件：

```bash
# 安装打包依赖
pip install pyinstaller

# 执行打包脚本
python build.py
# 或手动打包
pyinstaller --onefile --windowed --add-data "hclient-cli-windows-amd64.exe;." --add-data "wintun.dll;." hclient_gui.py
```

打包完成后，可执行文件位于 `dist/HClientGUI.exe`。

## ⚙️ 系统要求

- **操作系统**：Windows 7 / 8 / 10 / 11（64 位）
- **权限要求**：需要管理员权限（TUN 模式必需）
- **磁盘空间**：约 50MB
- **依赖组件**：
  - `hclient-cli-windows-amd64.exe` 必须位于程序同目录
  - `wintun.dll` 必须位于程序同目录

## 🔌 HTTP API 接口

程序启动后，提供本地 HTTP API 用于管理微服：

### 添加微服（登录）
```bash
curl -X POST 'http://127.0.0.1:7777/add_box?bname=微服名称&uid=用户名&password=密码'
```

### 设置两步验证（2FA）
```bash
curl -X POST 'http://127.0.0.1:7777/add_tfa?bname=微服名&tfa=验证码'
```

### 列出已添加的微服
```bash
curl http://127.0.0.1:7777/box_list
```

### 删除微服（退出）
```bash
curl -X DELETE 'http://127.0.0.1:7777/del_box?bname=%s'
```

### 查看客户端信息
```bash
curl http://127.0.0.1:7777/client_info
```

## 🌐 访问微服务

启动并登录后，可通过以下方式访问：

**使用 HTTP 代理（默认端口 61090）：**
```bash
curl -x http://127.0.0.1:61090 https://你的微服务名称.heiyu.space
```

**使用 TUN 模式（直接访问）：**
```bash
curl https://你的微服务名称.heiyu.space
```

## ⚠️ 注意事项

1. **管理员权限**：TUN 模式需要管理员权限才能创建虚拟网卡，请务必以管理员身份运行
2. **防火墙设置**：如遇连接问题，请检查 Windows Defender 防火墙是否拦截了程序
3. **文件完整性**：确保 `wintun.dll` 和 `hclient-cli-windows-amd64.exe` 与主程序在同一目录
4. **端口占用**：程序使用以下固定端口：
   - `7777`：HTTP API 服务端口
   - `61090`：HTTP 代理端口
   - 请确保这些端口未被其他程序占用

## ❓ 常见问题

### Q: 程序启动后提示"hclient-cli 启动失败"
**A:** 请检查：
- [ ] `hclient-cli-windows-amd64.exe` 是否存在于程序目录
- [ ] `wintun.dll` 是否存在于程序目录
- [ ] 是否以管理员身份运行

### Q: TUN 模式无法正常工作
**A:** 尝试以下步骤：
1. 确认以管理员身份运行程序
2. 检查 `wintun.dll` 是否存在且未损坏
3. 检查是否有其他 VPN 程序占用了 TUN 设备
4. 重启电脑后重试

### Q: 无法登录微服务
**A:** 请确认：
- 微服名称、用户名、密码输入正确
- 如开启了两步验证，需先输入主密码，再在弹窗中输入 TFA 验证码
- 网络连接正常，可访问 heiyu.space

### Q: 系统托盘图标不显示或程序无法最小化
**A:** 确保已安装必要的依赖：
```bash
pip install pystray Pillow
```

## 🛠️ 技术栈

- **开发语言**：Python 3.6+
- **GUI 框架**：tkinter（Python 标准库）
- **系统托盘**：pystray
- **HTTP 通信**：requests
- **打包工具**：PyInstaller

## 📄 许可证

本项目基于 [hclient-cli](https://github.com/lazycatlabs/hclient-cli) 开发，遵循原项目的许可证条款。

## 📝 更新日志

### v1.0.0 (2025-02-28)
- ✨ 初始版本发布
- ✅ 支持微服务登录/退出管理
- ✅ 支持系统托盘最小化运行
- ✅ 支持 TUN 模式自动启动
- ✅ 提供 HTTP API 管理接口

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

- 问题反馈：[Issues](https://gitee.com/rich_mona/gui_hclient/issues)
- 源码地址：https://gitee.com/rich_mona/gui_hclient

---

**免责声明**：本工具仅供学习交流使用，请遵守当地法律法规和服务提供商的使用条款。
```