234 lines
10 KiB
Markdown
234 lines
10 KiB
Markdown
# MeshRay 项目复盘
|
||
|
||
> 搁置日期：2026-05-27
|
||
> 项目版本：v2.0.2
|
||
> 后端完成度：~90% | 前端完成度：~50%
|
||
|
||
---
|
||
|
||
## 一、项目定位
|
||
|
||
MeshRay 是一个基于 WireGuard 的 Web 管理组网系统，目标是让非技术用户也能轻松搭建和管理 mesh VPN 网络。
|
||
|
||
**核心卖点**：9 层自适应传输策略，能在各种极端网络环境（校园网、企业防火墙、运营商 QoS、CGNAT）下保持连通性。
|
||
|
||
**目标场景**：
|
||
- 家庭组网（远程 NAS、私有云、IoT）
|
||
- 企业分支互联、远程办公
|
||
- 开发测试（本地环境暴露、多设备联调）
|
||
|
||
---
|
||
|
||
## 二、技术架构
|
||
|
||
### 整体设计
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ Web UI (Vue 3) │
|
||
│ go:embed 单文件嵌入 │
|
||
├─────────────────────────────────────────────┤
|
||
│ Gin HTTP API (~40 endpoints) │
|
||
├──────────┬──────────┬───────────────────────┤
|
||
│ Service │ Ctr │ Scheduler / DDNS │
|
||
│ 业务逻辑 │ 控制中心 │ 后台任务 │
|
||
├──────────┴──────────┴───────────────────────┤
|
||
│ Core Engine │
|
||
│ ┌─────────────────────────────────────┐ │
|
||
│ │ StrategyScheduler (9 层策略调度) │ │
|
||
│ │ ┌──────────────────────────────┐ │ │
|
||
│ │ │ FallbackController (降级控制) │ │ │
|
||
│ │ │ 滑动窗口 + 恢复探测 │ │ │
|
||
│ │ └──────────────────────────────┘ │ │
|
||
│ │ ConnManager / Relay │ │
|
||
│ └─────────────────────────────────────┘ │
|
||
├─────────────────────────────────────────────┤
|
||
│ WireGuard Plugin (用户态 wireguard-go) │
|
||
├─────────────────────────────────────────────┤
|
||
│ SQLite + GORM │
|
||
└─────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 关键技术选型
|
||
|
||
| 决策 | 选择 | 理由 |
|
||
|------|------|------|
|
||
| 语言 | Go | 单二进制部署，交叉编译，wireguard-go 生态 |
|
||
| Web 框架 | Gin | 轻量、成熟、中间件丰富 |
|
||
| 数据库 | SQLite | 单机部署场景，零依赖，GORM 纯 Go 驱动 |
|
||
| 前端方案 | Vue 3 CDN + go:embed | 无需 Node 构建链，单文件嵌入二进制 |
|
||
| 传输层 | Pion (WebRTC/TURN) + QUIC + WebSocket | 覆盖所有网络场景的协议栈 |
|
||
|
||
---
|
||
|
||
## 三、核心设计：9 层传输策略
|
||
|
||
这是 MeshRay 最有技术价值的部分，也是与其他 WireGuard 管理工具的最大差异。
|
||
|
||
### 层级设计
|
||
|
||
| 层级 | 传输方式 | 适用场景 | 性能 |
|
||
|------|---------|---------|------|
|
||
| 1 | Direct-UDP | 公网/锥型 NAT，标准 WireGuard | 最优 |
|
||
| 2 | Direct-FakeTCP | UDP 被 QoS 限速（校园网、酒店 WiFi） | 优 |
|
||
| 3 | Direct-RealTCP | 完全禁用 UDP，仅允许 TCP 出站 | 良 |
|
||
| 4 | TURN-UDP | 无 P2P 直连，但 UDP 可通 | 中 |
|
||
| 5 | TURN-QUIC | UDP 弱网（4G/5G 高丢包），私有扩展 | 中 |
|
||
| 6 | TURN-TCP | UDP 封禁，仅放行 TCP | 中 |
|
||
| 7 | TURN-TLS | 企业防火墙 DPI，仅放行 HTTPS | 中低 |
|
||
| 8 | WebRTC | 最严格隔离内网、代理环境 | 低 |
|
||
| 9 | WS/WSS | 仅放行 80/443 端口，终极兜底 | 最低 |
|
||
|
||
### 降级与恢复机制
|
||
|
||
```
|
||
正常运行 → 检测到丢包(滑动窗口 10s, 阈值 10%)
|
||
→ 自动降级到下一层
|
||
→ 每 30s 探测更高层级
|
||
→ 探测成功则自动恢复
|
||
```
|
||
|
||
**关键参数**：
|
||
- 滑动窗口：10 秒
|
||
- 丢包阈值：10%（或单次超时 500ms）
|
||
- 恢复探测间隔：30 秒
|
||
|
||
**设计要点**：
|
||
- 每个 Peer 独立的 FallbackController，互不干扰
|
||
- MonitoredConn 包装器透明拦截 Read/Write，自动采集延迟数据
|
||
- 降级回调异步触发重连，不阻塞数据通道
|
||
|
||
### 为什么是 9 层而不是更少
|
||
|
||
实际开发中发现，国内网络环境的多样性远超预期：
|
||
- 校园网/酒店 WiFi：UDP 不封但 QoS 限速到不可用 → 需要 FakeTCP
|
||
- 企业防火墙：深度包检测，只有 TLS 能过 → 需要 TURN-TLS
|
||
- 运营商封锁：UDP 全封，TCP 放行 → 需要 RealTCP/TURN-TCP
|
||
- 极端隔离：只有 HTTP 代理能出 → 需要 WebSocket 兜底
|
||
|
||
每一层都是为了解决一个真实存在的网络环境问题。
|
||
|
||
---
|
||
|
||
## 四、已完成功能
|
||
|
||
### 后端（~90%）
|
||
|
||
- [x] 9 层传输策略完整实现（`core/connect/`）
|
||
- [x] WireGuard 用户态管理（`core/plugins/wg/`）
|
||
- [x] Ctr 控制中心：WG + Core Engine 编排（`internal/ctr/`）
|
||
- [x] REST API ~40 个端点（网络、设备、策略、DDNS、设置、Dashboard、通知、备份、更新）
|
||
- [x] MeshSeed 凭证系统（Ed25519 签名，次数/过期限制）
|
||
- [x] DDNS 自动更新（Cloudflare + 腾讯云 DNSPod）
|
||
- [x] JWT 认证 + bcrypt 密码
|
||
- [x] WebSocket 通知 + SQLite 持久化
|
||
- [x] 备份恢复（创建/列表/恢复/删除/下载）
|
||
- [x] 系统托盘（Windows getlantern/systray）
|
||
- [x] Windows 服务支持（kardianos/service）
|
||
- [x] Docker 部署（docker-compose.yml）
|
||
- [x] 版本更新检测（GitHub Releases API）
|
||
|
||
### 前端（~50%）
|
||
|
||
- [x] 登录页
|
||
- [x] 仪表盘（基础统计）
|
||
- [x] 组网管理（CRUD + MeshSeed 生成）
|
||
- [ ] 设备管理页面
|
||
- [ ] 服务管理页面
|
||
- [ ] 系统设置页面
|
||
|
||
### 工程化
|
||
|
||
- [x] 单二进制部署（go:embed 嵌入前端）
|
||
- [x] 跨平台编译（Windows GUI 模式 + Linux 服务）
|
||
- [x] Viper 配置管理（YAML）
|
||
- [x] Zap 日志 + Lumberjack 轮转
|
||
- [x] Cobra CLI（主程序 + 密码重置 + 数据库检查）
|
||
|
||
---
|
||
|
||
## 五、未完成 / 已知问题
|
||
|
||
1. **前端三个页面未实现**：设备管理、服务管理、系统设置
|
||
2. **阿里云 DNS Provider**：开发期间网络不通，未集成 libdns/aliyun
|
||
3. **备份逻辑为占位**：真正的数据库导出 + 文件打包未实现
|
||
4. **WebSocket 中间件缺失**：当前为 30s 轮询，非真正实时推送
|
||
5. **UpdateCoreConfig 未实现**：返回 error stub
|
||
6. **无测试覆盖**：整个项目没有单元测试
|
||
|
||
---
|
||
|
||
## 六、搁置原因
|
||
|
||
### 市场判断
|
||
|
||
| 用户群体 | 竞品 | MeshRay 竞争力 |
|
||
|---------|------|---------------|
|
||
| 个人用户 | Tailscale（免费层）、WireGuard 原生 | 体验差距大，Tailscale 零配置 |
|
||
| 企业用户 | Tailscale/ZeroTier 企业版、大厂 SD-WAN | 缺少 SLA、售后、合规 |
|
||
| 技术爱好者 | Headscale、Netmaker、自建 WireGuard | 有一定差异化但用户基数小 |
|
||
|
||
### 核心矛盾
|
||
|
||
- **技术有亮点，但商业模式不成立**：9 层传输策略在国内网络环境下确实有价值，但愿意为此付费的用户极少
|
||
- **个人用户场景简单**：Tailscale 免费层已经够用
|
||
- **企业市场门槛高**：需要 SLA、合规、售后团队，不是独立开发者能做的
|
||
- **维护成本持续**：VPN 项目需要跟进安全更新、协议演进
|
||
|
||
### 结论
|
||
|
||
技术方向正确（国内网络穿透是真实痛点），但市场不买单。搁置是最理性的决定。
|
||
|
||
---
|
||
|
||
## 七、技术收获
|
||
|
||
### 值得保留的设计经验
|
||
|
||
1. **多层级降级策略模式**：滑动窗口检测 + 自动降级 + 定时恢复探测，这个模式适用于任何需要容错的连接场景
|
||
2. **MonitoredConn 透明包装**：用装饰器模式拦截 I/O 操作采集指标，对上层完全透明
|
||
3. **go:embed 前端嵌入**：单二进制分发的最简方案，省去了构建链和静态文件服务
|
||
4. **MeshSeed 凭证设计**：Ed25519 签名 + 次数/过期限制，比简单的 token 更安全
|
||
5. **Ctr 控制中心模式**：将 WireGuard 和传输引擎解耦，通过 localhost 重定向实现协议透明切换
|
||
|
||
### 可复用的代码模块
|
||
|
||
- `pkg/meshseed/` — Ed25519 签名凭证，可独立使用
|
||
- `core/connect/strategy.go` — 9 层策略调度器，可移植到其他网络项目
|
||
- `core/connect/` 下各传输层实现 — FakeTCP、TURN-QUIC 等小众传输方式的参考实现
|
||
|
||
### 踩过的坑
|
||
|
||
1. **wireguard-go 用户态性能**：相比内核态 WireGuard，用户态实现在高吞吐场景下有明显性能差距
|
||
2. **Pion TURN 服务端配置**：TURN 服务端的认证和分配策略比文档描述的复杂得多
|
||
3. **FakeTCP 的局限性**：部分防火墙会校验 TCP 头部完整性，简单的 UDP 封装 TCP 头会被识别
|
||
4. **CDN 方案的前端限制**：纯 CDN 加载 Vue 3 + Element Plus，在离线或弱网环境下无法使用
|
||
5. **go:embed 的构建顺序**：前端必须先构建再编译 Go，否则嵌入的是旧文件
|
||
|
||
---
|
||
|
||
## 八、如果重来会怎么做
|
||
|
||
1. **先做最小可用产品**：只做 Direct-UDP + TURN-TLS 两层，验证需求后再扩展
|
||
2. **前端用更轻的方案**：纯 HTML + htmx 或 Preact，减少 CDN 依赖
|
||
3. **从第一天写测试**：90% 后端代码无测试，重构信心不足
|
||
4. **先找 10 个种子用户**：在写代码之前验证需求，而不是写完再问"有没有人需要"
|
||
5. **考虑作为开源工具而非商业产品**：如果定位是开源社区工具，竞争压力小很多
|
||
|
||
---
|
||
|
||
## 九、项目资产清单
|
||
|
||
| 资产 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| 后端源码 | `cmd/`, `internal/`, `core/`, `pkg/` | Go 1.26，可编译 |
|
||
| 前端源码 | `web/static/` | Vue 3 SPA，CDN 方式 |
|
||
| 项目报告 | `PROJECT_REPORT.md` | 完整的功能分析 |
|
||
| 开发总览 | `README_开发完成总览.md` | 开发过程记录 |
|
||
| 部署配置 | `deploy/docker/`, `configs/` | Docker + YAML 配置 |
|
||
| 快速入门 | `QUICKSTART.md` | 部署指南 |
|
||
|
||
---
|
||
|
||
*项目已搁置。代码保留在 GitHub 作为技术积累和作品展示。*
|