zkcoi/Meshray-Manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Meshray-Manager/RETROSPECTIVE.md
T
zkcoi 15dab96872 Initial commit
2026-06-30 15:14:37 +08:00

10 KiB
Raw Permalink Blame History

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%）

  • 9 层传输策略完整实现（core/connect/）
  • WireGuard 用户态管理（core/plugins/wg/）
  • Ctr 控制中心：WG + Core Engine 编排（internal/ctr/）
  • REST API ~40 个端点（网络、设备、策略、DDNS、设置、Dashboard、通知、备份、更新）
  • MeshSeed 凭证系统（Ed25519 签名，次数/过期限制）
  • DDNS 自动更新（Cloudflare + 腾讯云 DNSPod）
  • JWT 认证 + bcrypt 密码
  • WebSocket 通知 + SQLite 持久化
  • 备份恢复（创建/列表/恢复/删除/下载）
  • 系统托盘（Windows getlantern/systray）
  • Windows 服务支持（kardianos/service）
  • Docker 部署（docker-compose.yml）
  • 版本更新检测（GitHub Releases API）

前端（~50%）

  • 登录页
  • 仪表盘（基础统计）
  • 组网管理（CRUD + MeshSeed 生成）
  • 设备管理页面
  • 服务管理页面
  • 系统设置页面

工程化

  • 单二进制部署（go:embed 嵌入前端）
  • 跨平台编译（Windows GUI 模式 + Linux 服务）
  • Viper 配置管理（YAML）
  • Zap 日志 + Lumberjack 轮转
  • 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 作为技术积累和作品展示。

Reference in New Issue View Git Blame Copy Permalink