Initial commit

2026-06-30 15:14:37 +08:00
commit 15dab96872
311 changed files with 95639 additions and 0 deletions
@@ -0,0 +1,238 @@
+# MeshRay 项目完整分析报告
+
+> 生成时间：2026-04-01
+> 基于代码实际分析，非文档推测
+
+---
+
+## 一、项目概述
+
+### 项目是什么
+
+**MeshRay** 是一个基于 Web 管理的 WireGuard 组网系统（去中心化 VPN）。
+
+**核心功能**：
+- 通过浏览器管理 WireGuard 虚拟专网
+- 支持 9 层传输策略（适应各种网络环境）
+- 提供 MeshSeed 邀请凭证（Ed25519 签名）
+- 支持 DDNS 动态域名（Cloudflare、腾讯云）
+- 增强模式：流量通过 Core Engine 智能调度
+
+### 技术栈
+
+| 组件 | 技术 |
+|------|------|
+| 后端 | Go 1.21+ / Gin / GORM |
+| 数据库 | SQLite（纯 Go 实现）|
+| VPN | WireGuard（用户态 wireguard-go）|
+| 前端 | Vue 3 + Element Plus + Tailwind CSS（CDN 方式）|
+| 实时通信 | WebSocket |
+| 传输协议 | STUN/TURN (pion)、WebRTC (pion)、QUIC |
+
+---
+
+## 二、项目结构
+
+```
+MeshRay/
+├── cmd/meshray/           # 主程序入口
+├── internal/
+│   ├── api/              # HTTP API 层
+│   │   ├── server.go     # Gin 服务器
+│   │   ├── handler/      # HTTP Handler
+│   │   │   ├── network.go    # 网络 CRUD
+│   │   │   ├── device.go    # 设备 CRUD
+│   │   │   ├── dashboard.go  # 统计
+│   │   │   ├── ddns.go      # DDNS
+│   │   │   ├── policy.go    # 策略
+│   │   │   ├── service.go   # 服务
+│   │   │   ├── ws.go        # WebSocket
+│   │   │   └── ...
+│   │   ├── dto/          # 数据传输对象
+│   │   └── middleware/   # 中间件 (JWT/CORS)
+│   ├── ctr/              # 控制中心（调度 Core + WG）
+│   │   ├── ctr.go       # 主调度逻辑
+│   │   └── wg.go        # WGManager
+│   ├── service/         # 业务服务层
+│   │   ├── network.go
+│   │   ├── device.go
+│   │   ├── meshseed.go
+│   │   ├── ddns.go
+│   │   └── ...
+│   ├── store/sqlite/     # SQLite 存储
+│   ├── model/           # 数据模型
+│   └── config/          # 配置管理
+├── core/                # 核心引擎
+│   ├── core.go          # Core 主入口
+│   ├── engine.go        # Engine 实例
+│   └── connect/         # 9 层传输策略
+│       ├── direct.go    # Direct-UDP
+│       ├── fake_tcp.go  # Direct-FakeTCP
+│       ├── real_tcp.go  # Direct-RealTCP
+│       ├── turn.go      # TURN 系列
+│       ├── turn_quic.go
+│       ├── ws.go        # WS/WSS
+│       ├── stun.go
+│       ├── ice.go
+│       └── strategy.go  # 策略调度器
+├── pkg/
+│   └── meshseed/        # MeshSeed 凭证
+└── web/
+    ├── embed.go         # Go embed 打包
+    └── static/          # 静态文件
+        ├── index.html   # SPA 入口
+        └── js/app.js    # Vue3 应用
+```
+
+---
+
+## 三、核心功能分析
+
+### 1. 9 层传输策略
+
+| 层级 | 类型 | 用途 |
+|------|------|------|
+| 1 | Direct-UDP | 公网/锥型 NAT首选 |
+| 2 | Direct-FakeTCP | UDP 被 QoS 限速 |
+| 3 | Direct-RealTCP | 仅允许 TCP 出站 |
+| 4 | TURN-UDP | 无 P2P 直连，UDP 可通 |
+| 5 | TURN-QUIC | UDP 弱网 (4G/5G) |
+| 6 | TURN-TCP | UDP 封禁，仅放行 TCP |
+| 7 | TURN-TLS | 企业防火墙 DPI |
+| 8 | WebRTC | 最严格隔离内网 |
+| 9 | WS/WSS | 仅放行 80/443 端口 |
+
+### 2. Ctr (Control) 调度中心
+
+职责：
+- 网络生命周期管理
+- Peer 管理
+- 模式切换 (native ↔ enhanced)
+- Core Engine 集成
+
+### 3. MeshSeed 凭证
+
+基于 Ed25519 签名的组网邀请凭证，支持：
+- 使用次数限制
+- 过期时间控制
+- DDNS 同步
+
+### 4. DDNS 动态域名
+
+已支持：
+- Cloudflare
+- 腾讯云 DNSPod
+
+待支持：
+- 阿里云
+
+---
+
+## 四、完成情况
+
+### 后端 ✅ 90%
+
+| 功能 | 状态 |
+|------|------|
+| 9 层传输策略 | ✅ 完成 |
+| WireGuard 用户态管理 | ✅ 完成 |
+| Ctr 调度中心 | ✅ 完成 |
+| SwitchMode | ✅ 完成 |
+| MeshSeed 凭证 | ✅ 完成 |
+| DDNS (Cloudflare/腾讯云) | ✅ 完成 |
+| JWT 认证 | ✅ 完成 |
+| WebSocket 通知 | ✅ 完成 |
+| 备份恢复 | ✅ 完成 |
+| 系统托盘 | ✅ 完成 |
+| UpdateCoreConfig | 🔧 已定义（返回 error）|
+
+### 前端 ⚠️ 50%
+
+| 页面 | 状态 |
+|------|------|
+| 登录页 | ✅ 完成 |
+| 仪表盘 | ✅ 基本完成 |
+| 组网管理 | ✅ 完成 |
+| 设备管理 | ❌ 待完成 |
+| 服务管理 | ❌ 待完成 |
+| 系统设置 | ❌ 待完成 |
+
+---
+
+## 五、API 清单
+
+### 网络 API
+- `GET /api/v1/networks` - 列表
+- `POST /api/v1/networks` - 创建
+- `GET /api/v1/networks/:id` - 详情
+- `PUT /api/v1/networks/:id` - 更新
+- `DELETE /api/v1/networks/:id` - 删除
+- `POST /api/v1/networks/:id/mesh-seed` - 生成 MeshSeed
+
+### 设备 API
+- `GET /api/v1/devices` - 列表
+- `POST /api/v1/devices` - 创建
+- `GET /api/v1/devices/:id` - 详情
+- `PUT /api/v1/devices/:id` - 更新
+- `DELETE /api/v1/devices/:id` - 删除
+- `GET /api/v1/devices/:id/config` - 生成 WireGuard 配置
+
+### 服务 API
+- `GET /api/v1/services` - 列表
+- `POST /api/v1/services` - 创建
+- `PUT /api/v1/services/:id` - 更新
+- `DELETE /api/v1/services/:id` - 删除
+
+### DDNS API
+- `GET /api/v1/ddns/config` - 获取配置
+- `PUT /api/v1/ddns/config` - 更新配置
+- `POST /api/v1/ddns/sync` - 手动同步
+- `GET /api/v1/ddns/stats` - 统计
+
+### 策略 API
+- `GET /api/v1/policies` - 列表
+- `PUT /api/v1/policies/:id` - 更新
+
+### 其他 API
+- `GET /api/v1/dashboard/stats` - 统计
+- `GET /api/v1/settings` - 设置
+- `PUT /api/v1/settings` - 更新设置
+
+---
+
+## 六、配置文件
+
+```yaml
+server:
+  port: 9531
+  mode: release
+
+database:
+  type: sqlite
+  path: ./data/meshray.db
+
+jwt:
+  secret: (自动生成)
+  access_token_duration: 2h
+  refresh_token_duration: 7d
+
+stun:
+  default_servers:
+    - stun:stun.qq.com:3478
+    - stun:stun.l.google.com:19302
+
+turn:
+  default_servers: []
+```
+
+---
+
+## 七、结论
+
+MeshRay 是一个**功能架构完整**的项目，核心功能都已实现。前端采用纯静态 CDN 方式，无需 npm/vite，工程简洁。
+
+**待完成**：
+1. 设备管理页面
+2. 服务管理页面
+3. 系统设置页面
+