# EasyTunnel

**Repository Path**: jinguangyang/easy-tunnel

## Basic Information

- **Project Name**: EasyTunnel
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: bate2
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-18
- **Last Updated**: 2026-05-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EasyTunnel

> 内网穿透 + 虚拟组网融合工具，基于 Rust 构建，支持 TCP/UDP/HTTP 隧道与 P2P 直连。

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Rust](https://img.shields.io/badge/Rust-1.75%2B-orange.svg)](https://www.rust-lang.org/)

## 项目简介

EasyTunnel 是一款高性能内网穿透工具，同时具备虚拟组网能力。一套客户端可同时：
- 将本地服务暴露到公网（内网穿透）
- 与其他客户端组成私有虚拟网络（P2P 直连）

核心引擎采用 Rust 实现，单二进制部署，内存占用极低，适合长期运行在桌面、服务器、树莓派等设备。

## 架构

```
┌──────────────┐     WebSocket (控制)      ┌──────────────────┐
│   客户端      │◄─────────────────────────►│    服务端         │
│  easytunnel  │                            │  easytunnel     │
└──────┬───────┘     WebSocket (数据)       │  -server         │
       │           ◄─────────────────────────►│                  │
       │  TCP  │                             └────────┬─────────┘
       │◄──────┘                                      │
       │  TCP        TCP Listener                     │  外部访问
  ┌────▼─────┐                              ┌─────────▼────────┐
  │ 本地服务   │                              │   公网用户       │
  │ :8080     │                              │   curl / 浏览器   │
  └───────────┘                              └──────────────────┘
```

- **控制通道**：握手认证、心跳、隧道注册信令（JSON over WebSocket）
- **数据通道**：隧道流量转发（自定义二进制协议，bincode + 1字节标签，3-5x 于 JSON）
- **连接复用**：单 WebSocket 连接通过 `conn_id` 复用所有隧道流量

## 功能列表

### 已实现 ✅

#### 内网穿透（Phase 2）
| 功能 | 说明 |
|------|------|
| TCP 端口映射 | 本地 TCP 服务暴露到公网端口 |
| **UDP 端口映射** | DNS、游戏等 UDP 服务暴露到公网端口 |
| **HTTP 反向代理** | 基于 Host Header 路由到本地 HTTP 服务 |
| 控制/数据通道分离 | 独立 WebSocket，数据不阻塞控制信令 |
| 隧道自动重连 | 断线后指数退避重连，隧道自动重新注册 |
| 多隧道配置 | TOML 配置文件支持多个隧道同时注册 |
| 客户端 CLI | 交互式 TCP/UDP/HTTP 隧道创建与管理 |
| 数据二进制编码 | bincode 替代 JSON，降低协议开销 3-5x |
| 首次连接缓冲 | `TunnelConnOpen` 竞态场景下首包不丢失 |
| UDP 会话管理 | 外部对等端首次数据包建立 udp_conn_id |

#### 虚拟组网（Phase 3 - 信令层）
| 功能 | 说明 |
|------|------|
| 虚拟 IP 分配 | 服务端自动分配 10.26.x.x 网段 IP |
| 对端发现 | 客户端上线后通知其他节点 |
| NAT 类型检测 | 支持 FullCone/PortRestricted 等类型识别 |

#### Web 管理接口
| 功能 | 说明 |
|------|------|
| REST API | 隧道 CRUD、设备列表、统计数据 |
| WebSocket | 实时控制通道 |

### 未实现 🚧

| 功能 | 优先级 | 说明 |
|------|--------|------|
| ~~UDP 端口映射~~ | ✅ 已实现 | 支持 DNS、游戏等 UDP 服务 |
| ~~HTTP 反向代理~~ | ✅ 已实现 | 基于 Host Header 路由，支持子域名 |
| HTTPS + ACME | P0 | Let's Encrypt 自动证书 |
| STCP 安全隧道 | P1 | 密钥验证，保护隧道不被滥用 |
| 带宽限速 | P2 | 基于令牌桶的流量控制 |
| 连接白名单 | P2 | IP/域名访问控制 |
| XTCP P2P 直连 | P2 | 不依赖服务端的 UDP 打洞穿透 |
| TUN 虚拟网卡 | P0 | 全虚拟网络，替代端口映射 |
| 服务端中继转发 | P0 | NAT 无法穿透时的Fallback |
| Web 管理面板 (Vue3) | P1 | 仪表盘、流量监控、用户权限 |
| Flutter GUI | P0 | 系统托盘、可视化配置、自动更新 |

## 与同类产品对比

| 特性 | EasyTunnel | frp | ngrok | cpolar |
|------|-----------|-----|-------|---------|
| 语言 | Rust | Go | Go | Go |
| 二进制大小 | ~5MB | ~20MB | ~30MB | ~25MB |
| 控制/数据通道分离 | ✅ | ❌ | ✅ | ✅ |
| 二进制数据协议 | ✅ | ❌ | ❌ | ❌ |
| TCP 隧道 | ✅ | ✅ | ✅ | ✅ |
| UDP 隧道 | ✅ | ✅ | ✅ | ✅ |
| HTTP 反向代理 | ✅ | ❌ | ❌ | ❌ |
| P2P 虚拟组网 | 🚧 | ❌ | ❌ | ❌ |
| 多隧道配置文件 | ✅ | ✅ | ❌ | ✅ |
| 自动重连 | ✅ | ❌ | ✅ | ✅ |
| Web UI 管理 | 🚧 | ❌ | ✅ | ✅ |
| 开源 | ✅ | ✅ | ❌ | 部分开源 |
| License | MIT | MIT | proprietary | freemium |

**核心差异**：
- **vs frp**：EasyTunnel 采用独立数据通道 + 二进制协议，性能更高；frp 所有流量走同一连接
- **vs ngrok/cpolar**：完全开源（MIT），无厂商锁定，支持私有化部署
- **vs frp/cpolar**：内置虚拟组网能力，一套客户端同时支持穿透和 P2P 组网
- **Rust 实现**：极低内存占用（实测空闲 < 5MB），适合树莓派/嵌入式长期运行

## 快速开始

### 安装

**从源码构建（需要 Rust 1.75+）**

```bash
git clone https://gitee.com/jinguangyang/easy-tunnel.git
cd easy-tunnel
cargo build --release

# 二进制位于
./target/release/easytunnel-server   # 服务端
./target/release/easytunnel          # 客户端 CLI
```

### 启动服务端

```bash
./target/release/easytunnel-server
# 输出: EasyTunnel Server v0.1.0
#       Binding to 0.0.0.0:29872
#       Server listening on http://0.0.0.0:29872
```

### 创建 TCP 隧道

```bash
# 单次隧道
./target/release/easytunnel -s ws://127.0.0.1:29872 tcp 127.0.0.1:8080 -p 10000

# 或使用配置文件（见 USAGE.md）
./target/release/easytunnel connect -c ~/.easytunnel/config.toml
```

### 测试

```bash
# 外部访问（通过服务端 IP:10000）
curl http://<服务端IP>:10000/
```

详细说明请参阅 [USAGE.md](./USAGE.md)。

## 项目结构

```
easytunnel/
├── Cargo.toml              # Workspace 配置
├── easytunnel-core/        # 核心库：协议、配置、加密
│   └── src/
│       ├── protocol/        # 通信协议定义
│       └── config/         # 配置结构
├── easytunnel-server/       # 服务端
│   └── src/
│       ├── api/            # REST API 路由
│       ├── ws_handler.rs   # 控制通道 WebSocket
│       ├── data_handler.rs # 数据通道 WebSocket
│       ├── tunnel/         # TCP 监听器
│       └── state.rs        # 服务端状态
├── easytunnel-client/      # 客户端核心库
│   └── src/
│       ├── connection.rs    # 连接管理 + 重连
│       └── data_channel.rs # 数据通道
└── easytunnel-cli/         # CLI 工具
    └── src/main.rs
```

## 配置示例

```toml
# ~/.easytunnel/config.toml

server_addr = "ws://你的服务端地址:29872"
token = ""
device_name = "my-server"

[[tunnels]]
tunnel_id = "web"
tunnel_type = "Tcp"
local_addr = "127.0.0.1:8080"
remote_port = 0          # 0 = 自动分配端口
enabled = true

[[tunnels]]
tunnel_id = "ssh"
tunnel_type = "Tcp"
local_addr = "127.0.0.1:22"
remote_port = 10022      # 固定端口
enabled = true
```

## License

MIT License - 详见 [LICENSE](./LICENSE) 文件。