# 小米球客户端node版

**Repository Path**: ciqiu/xiaomiqiu_client_node

## Basic Information

- **Project Name**: 小米球客户端node版
- **Description**: 小米球客户端node版
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-14
- **Last Updated**: 2025-12-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<img alt="xmq" height="120" src="doc/xmq.png" width="120"/> 

### 小米球内网穿透工具

> 一个可用于内网穿透的工具，将局域网个人电脑、服务器映射到公网。

> 支持任何TCP上层协议，可用于远程桌面、访问内网网站、SSH访问、远程连接打印机、本地支付接口调试、微信小程序调试...

> 支持HTTP端口复用，可用于内网反向代理，共用服务端80/443端口。支持HTTP请求升级为WebSocket，HTTP2。

> SSL双端验证，数据加密传输。

> 支持UDP协议。

> 部署简单，提供多个版本客户端。


# Xiaomiqiu Client Node 版本

相较于 `xiaomiqiu-client`（Go）与 `xiaomiqiu-netty（Java）的实现，此版本使用 Node.js 提供跨平台客户端能力。核心特性：

- 复用双向 TLS 长连接，完全遵循 `Message` 报文格式
- 与服务端保持心跳、自动重连
- 支持 TCP/HTTP/HTTPS（统一视为 TCP）与 UDP 穿透
- 针对每个穿透会话建立单独的代理通道，遵循「控制连接 + 数据连接」架构
- 自动处理粘包/拆包：4 字节长度帧 + 消息头 + Meta(JSON) + Data

## 运行前准备

1. **拷贝证书**
   - 将最新证书 `cert/ca.crt`、`cert/cert.crt`、`cert/private.key`
     复制到本目录 `cert/` 下（当前已是最新证书）。

2. **配置文件**
   - 默认 `config.yaml` 提供示例，可根据需要调整：
     ```yaml
     serverAddr: "服务器IP:端口"
     authToken: "你的令牌"
     logLevel: "info"
     logTo: "stdout" # 或 "file"
     ```
   - 支持 JSON/YAML

3. **安装依赖**
   ```bash
   npm install
   ```

## 启动

```bash
npm start -- --config ./config.yaml
```

常用参数：

| 参数 | 说明 |
|------|------|
| `-c, --config` | 指定配置文件路径（可使用 JSON/YAML） |

## 协议要点

- **消息头结构**：`messageLength(4) | messageType(4) | serializerType(4) | metaLength(4) | meta(json) | data`
- **消息类型**：`REGISTER / AUTH / CONNECTED / DISCONNECTED / DISCONNECTED404 / KEEPALIVE / DATA`
- **Meta**：保持与 Java/Go 定义一致，包含 `clientKey/channelId/serverId/remoteConfigList/...`
- **通讯策略**：
  - 控制连接负责注册、心跳、会话分配
  - 数据连接（代理通道）按需复用/创建，承载 DATA/CONNECTED/DISCONNECTED
  - 心跳间隔默认 30s，可在配置中调整

## 目录结构

```
src/
  config.js            # 配置加载与规范化
  logger.js            # 轻量日志器
  message.js           # 报文编码/解码
  frame-buffer.js      # TCP 粘包处理
  connections/         # 控制连接、代理连接封装
  sessions/            # TCP/UDP 会话管理
  session-manager.js   # 控制连接收到消息后的调度逻辑
  connection-pool.js   # 代理连接池
  index.js             # 程序入口
```

## 后续拓展

- 接入自动升级、状态监控
- 增加日志轮转、详细链路追踪
- 引入集成测试验证不同协议链路

## 调试

- 如需调试，可先开启 `logLevel: debug` 

## 反馈帮助

- 小米球交流群： ①群:150134730(已满) ②群:150134648(已满) ③群:745317268(未满)

## 小米球官方网站：

- https://www.xiaomiqiu.cn/
- https://manager.xiaomiqiu.com/