# 小米球客户端dotnet **Repository Path**: ciqiu/xiaomiqiu-client-dotnet ## Basic Information - **Project Name**: 小米球客户端dotnet - **Description**: 小米球客户端dotnet版本 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2026-07-24 - **Last Updated**: 2026-08-03 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 小米球客户端 dotnet > .NET 内网穿透客户端 — 将本地服务安全地暴露到公网，支持多版本服务器和隧道分组管理。 [![.NET](https://img.shields.io/badge/.NET-8.0%2B-512BD4?logo=.net)](https://dotnet.microsoft.com/) [![Avalonia](https://img.shields.io/badge/UI-Avalonia-8B5CF6)](https://avaloniaui.net/) [![Platform](https://img.shields.io/badge/platform-Windows%20x64-blue)](#) --- ## 目录 - [项目简介](#项目简介) - [核心功能](#核心功能) - [软件架构](#软件架构) - [快速开始](#快速开始) - [环境要求](#环境要求) - [安装](#安装) - [GUI 模式](#gui-模式) - [命令行 / 无头模式](#命令行--无头模式) - [配置说明](#配置说明) - [构建与打包](#构建与打包) - [参与贡献](#参与贡献) - [许可证](#许可证) --- ## 项目简介 **小米球客户端**是小米球内网穿透的 .NET 版本客户端，通过代理服务器将你本地运行的服务（TCP / UDP / HTTP / HTTPS）映射到公网，方便远程访问、联调测试和演示。 支持**多版本套餐**（注册版 / VIP1 / VIP2 / VIP3）：一个 Token 即可发现并管理账号下所有可用隧道组，按版本分组显示，支持独立连接和断开。提供两种运行形态： | 形态 | 入口 | 适用场景 | |------|------|----------| | **GUI 桌面客户端** | `XiaomiqiuClient.UI` | 日常使用，可视化操作 | | **命令行/无头模式** | `XiaomiqiuClient.Console` | 服务器部署、后台静默运行 | ## 核心功能 ### 连接与穿透 - **多版本套餐**：一个 Token 覆盖注册版 / VIP1 / VIP2 / VIP3 四个等级 - **协议支持**：TCP、UDP、HTTP、HTTPS 隧道 - **连接池**：10 条预建代理连接，低延迟转发 - **自动重连**：掉线自动重连，智能退避策略（快速重试 → 30 分钟 → 1 小时 → 放弃） - **被踢下线保护**：服务端主动踢下线后不再反复重连 - **开机自联**：记忆上次手动连接的隧道组，启动时自动恢复 ### 安全 - **黑名单**：IP 拉黑后访客无法访问映射内容（向服务端发送拦截标识，不建立内网连接） - **TLS 加密**：客户端与代理服务器之间通过 TLS 加密通信 - **访客日志**：记录每次访客接入的 IP 信息 ### 桌面客户端 (Avalonia UI) - **仪表盘**：全局连接状态、流量统计、在线时长、连接池使用率 - **隧道管理**：查看全部隧道、复制公网地址、按版本分组 - **日志查看**：实时日志输出，按服务器地址分类 - **统计页面**：流量趋势、访客统计（独立 IP 数、接入次数） - **黑名单管理**：添加/移除黑名单 IP - **设置**：Token 配置、日志模式、自动重连、开机启动、最小化到托盘 - **换肤**：深蓝 / 暗紫 / 墨绿 三套底色 × 白 / 深 / 橙金 / 玫瑰红 / 天青 五套强调色 - **自动更新**：定时检测新版本，手动/静默自动更新 --- ## 软件架构 ``` XiaomiqiuClient.sln ├── src/ │ ├── XiaomiqiuClient.Core/ # 核心逻辑层 │ │ ├── Config/ # JSON 配置加载/保存、开机启动管理 │ │ ├── Connection/ # TCP/TLS 连接、代理消息处理、连接池 │ │ ├── Models/ # Tunnel、Message、RemoteConfig 数据模型 │ │ ├── Monitoring/ # 状态聚合、事件总线、黑名单、更新检测 │ │ ├── Protocol/ # 消息编解码（与代理服务器通信协议） │ │ └── Tls/ # TLS 证书加载 │ ├── XiaomiqiuClient.UI/ # 桌面 GUI（Avalonia MVVM） │ │ ├── Views/ # XAML 视图 │ │ ├── ViewModels/ # MVVM 视图模型 │ │ ├── Services/ # 主题、更新检测 │ │ └── Converters/ # 值转换器 │ └── XiaomiqiuClient.Console/ # 命令行入口（无头模式） ├── installer/ # Inno Setup 打包脚本 └── tools/ # 辅助工具 ``` ### 技术栈 | 组件 | 技术 | |------|------| | 运行时 | .NET 8.0+ | | UI 框架 | Avalonia UI (跨平台) | | 日志 | Serilog | | JSON | Newtonsoft.Json | | 打包 | Inno Setup 6 + `dotnet publish` 单文件 | ### 连接模型 ``` 本地服务 (127.0.0.1:8080) ↑ TCP [小米球客户端] ←── TLS ──→ [代理服务器] ←── 公网访客 │ │ └── 连接池 (10条) └── 多版本接入点 预建、复用 注册版/VIP1/VIP2/VIP3 ``` --- ## 快速开始 ### 环境要求 - **操作系统**：Windows 10+ (x64) - **运行时**：[.NET 8.0 Desktop Runtime](https://dotnet.microsoft.com/download/dotnet/8.0)（若使用安装包则自带） - **网络**：能够访问代理服务器地址（见下方服务器版本地址表） ### 安装 1. 下载最新安装包： - 从 [Releases]() 页面获取 `XiaomiqiuClientSetup-.exe` - 或访问 2. 双击运行安装向导，按提示完成安装 3. 首次启动后，在 **设置** 页面填入你的 **Token**（Token 只能通过[小米球控制台](https://manager.xiaomiqiu.com)获取） 4. 返回仪表盘，点击 **立即连接** ### GUI 模式 启动后进入主界面，包含 **6 个功能页**： | 页面 | 功能 | |------|------| | **仪表盘** `◉` | 连接状态、流量、连接池、隧道概况、按版本分组卡片 | | **隧道** `⇄` | 所有隧道详情，复制公网地址 | | **日志** `≣` | 实时日志，按服务器地址筛选 | | **统计** `∑` | 流量趋势图、访客统计 | | **黑名单** `⊘` | IP 黑名单管理 | | **设置** `⚙` | Token、日志、重连、开机启动、换肤等配置 | ### 命令行 / 无头模式 ```bash # 下载后进入目录，通过命令行参数运行： XiaomiqiuClient.Console.exe \ --config config.json \ --client-key YOUR_TOKEN \ --server-addr ngrok.xiaomiqiu123.top:5432 \ --log stdout \ --log-level info # 查看帮助 XiaomiqiuClient.Console.exe --help ``` 支持的参数： | 参数 | 说明 | 默认值 | |------|------|--------| | `--config`, `-c` | 配置文件路径 | `config.json` | | `--client-key` | 客户端 Token（覆盖配置文件） | — | | `--server-addr` | 服务器地址 `host:port` | — | | `--log` | 日志输出方式 `stdout` / `file` | `stdout` | | `--log-level` | 日志级别 `debug` / `info` / `warn` / `error` | `info` | --- ## 配置说明 配置文件位于用户目录 `%APPDATA%\Xiaomiqiu\config.json`，完整字段： ```jsonc { // 默认代理服务器地址（注册版入口，GUI 模式下按套餐自动切换） "serverAddr": "ngrok.xiaomiqiu123.top:5432", // 客户端 Token（必填，从小米球控制台 https://manager.xiaomiqiu.com 获取） "clientKey": "", // 自动更新检测接口地址 "updateEndpoint": "", // 日志输出方式："stdout"（控制台）或 "file"（写入文件） "logTo": "stdout", // 日志级别："debug" / "info" / "warn" / "error" "logLevel": "info", // 断线后是否自动重连（默认 true） "autoReconnect": true, // 是否开机自动启动（写入 Windows 启动注册表） "autostart": false, // 关闭窗口时最小化到托盘而非退出 "minimizeToTray": true, // 连接断开时在托盘弹出提醒 "notifyOnDisconnect": true, // 皮肤主题：0=深蓝, 1=暗紫, 2=墨绿 "theme": 0, // 自动保持连接的隧道组（版本名列表），由程序自动维护 "autoConnectVersions": [] } ``` ### 服务器版本地址 | 版本 | 地址 | |------|------| | 注册版 | `ngrok.xiaomiqiu123.top:5432` | | VIP1 | `vip.guyubao.com:5432` | | VIP2 | `vipvip.xiaomiqiu.com:5432` | | VIP3 | `vip3.xiaomiqiu123.top:5432` | --- ## 构建与打包 ### 开发构建 ```bash # 还原依赖 dotnet restore # 构建 GUI 客户端 dotnet build src/XiaomiqiuClient.UI -c Release # 构建控制台版本 dotnet build src/XiaomiqiuClient.Console -c Release ``` ### 发布单文件可执行程序 ```bash dotnet publish src/XiaomiqiuClient.UI \ -c Release \ -r win-x64 \ --self-contained true \ -p:PublishSingleFile=true \ -o ./dist ``` ### 一键打包安装包 使用项目自带的打包脚本，生成 Inno Setup 安装程序 + 更新包： ```batch :: 指定版本号打包 installer\build.bat 4.0.1 :: 不指定版本号则从 .csproj 读取 installer\build.bat ``` 输出产物： | 产物 | 路径 | 用途 | |------|------|------| | 安装程序 | `installer\Output\XiaomiqiuClientSetup-.exe` | 用户全新安装 / 升级 | | 更新包 | `D:\dist\xiaomiqiu-\xiaomiqiu-dotnet.exe` | 上传至 `pkgUrl`，供自动更新下载 | > 依赖 [Inno Setup 6](https://jrsoftware.org/isinfo.php) 并安装到 `D:\EXE\Inno Setup 6\ISCC.exe`，或通过 `ISCC` 环境变量自定义路径。 --- ## 参与贡献 欢迎提交 Issue 和 Pull Request！ 1. Fork 本仓库 2. 从 `longge` 分支创建功能分支：`git checkout -b Feat_xxx` 3. 提交你的更改：`git commit -m "feat: 功能描述"` 4. 推送到远程：`git push origin Feat_xxx` 5. 提交 Pull Request 到 `longge` 分支 ### 分支说明 | 分支 | 说明 | |------|------| | `master` | 初始版本基线（仅包含项目骨架和基础连接） | | `longge` | 当前活跃开发分支（GUI + 全部功能） | --- ## 许可证 > 待补充