# 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 作为技术积累和作品展示。*