Initial commit

2026-06-30 15:14:37 +08:00
commit 15dab96872
311 changed files with 95639 additions and 0 deletions
@@ -0,0 +1,233 @@
+# 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 作为技术积累和作品展示。*