# 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. 系统设置页面