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

12 KiB
Raw Blame History

MeshRay-Core 架构规范

Core 是通用的数据传输引擎，通过 ProtocolPlugin 接口适配不同协议。当前默认内置 WG 插件。

一、目录结构

core/
├── core.go                          # 进程入口
├── engine.go                        # 引擎实例
├── metrics.go                       # 监控指标
│
├── connect/                         # 建连层
│   ├── strategy.go                  # 策略调度
│   ├── stun.go                      # STUN 协议
│   ├── direct.go                    # Layer 1
│   ├── fake_tcp.go                  # Layer 2
│   ├── real_tcp.go                  # Layer 3
│   ├── turn.go                      # Layer 4/6/7
│   ├── turn_quic.go                 # Layer 5
│   ├── ice.go                       # Layer 8
│   └── ws.go                        # Layer 9
│
├── transport/                       # 传输层
│   ├── conn_manager.go              # 连接索引
│   ├── relay.go                     # 转发循环
│   └── plugin.go                    # Plugin 接口
│
└── plugins/                         # 协议插件
    └── wg/
        └── wgparse.go               # WG 插件实现

二、各文件职责

2.1 根目录（4 个文件）

文件 职责 持有什么 不做什么
core.go 进程入口，管理多个 Engine map[engineID]*Engine 不做建连、不转发数据
engine.go 一个组网的引擎实例 strategy、conn_manager、relay、plugin 不直接调用 connect，由 relay 调用
metrics.go 监控指标采集 原子计数器（连接数、字节数、切换次数） 不做业务逻辑

关键关系：

  • core.go 持有多个 engine.go
  • internal/ctr/ctr.go 直接调用 core.go 和 engine.go (进程内函数调用)
  • engine.go 持有 connect/、transport/、plugins/ 的实例

2.2 connect/（9 个文件）— 建连层

职责：通过各种网络方式建立连接，最终返回 net.Conn。

对外暴露的唯一入口：strategy.go 的 Connect() 方法。其他 connect 文件只被 strategy.go 调用。

文件 对应层级 职责 返回什么
strategy.go 全部 按优先级尝试各层，不通自动切换，定期探测恢复 net.Conn + 当前层级名
stun.go 被 direct/ice 调用 STUN 协议：发送 Binding Request，获取本机公网地址 *net.UDPAddr（地址，不是连接）
direct.go Layer 1 调用 stun 获取候选地址，然后 UDP 打洞 net.Conn
fake_tcp.go Layer 2 UDP 包外层封装 TCP 头部，欺骗防火墙 net.Conn
real_tcp.go Layer 3 真正的 TCP 直连打洞 net.Conn
turn.go Layer 4/6/7 TURN 协议协商（Allocate/Permission/ChannelBind），参数区分 UDP/TCP/TLS net.Conn
turn_quic.go Layer 5 TURN-QUIC 私有扩展（RFC 9000） net.Conn
ice.go Layer 8 ICE 协商 + WebRTC DataChannel，内部调用 stun 收集候选 net.Conn
ws.go Layer 9 WS/WSS 握手 + 帧收发 + 身份标识 net.Conn

9 层完整编号：

层级 链路名称 文件 传输方式 穿透力
1 Direct-UDP direct.go P2P 直连 弱（性能最好）
2 Direct-FakeTCP fake_tcp.go P2P 直连 弱
3 Direct-RealTCP real_tcp.go P2P 直连 中
4 TURN-UDP turn.go 中继 中
5 TURN-QUIC turn_quic.go 中继 中
6 TURN-TCP turn.go 中继 强
7 TURN-TLS turn.go 中继 强
8 WebRTC ice.go ICE/TURN 强
9 WS/WSS ws.go 隧道 最强（兜底）

strategy.go 的自动切换逻辑：

  • 单包超时 500ms → 切到下一层
  • 10s 滑动窗口丢包率 > 10% → 切到下一层
  • 当前在第 N 层时，每 30s 探测 Layer 1 → 连续 2 次成功直接切回 Layer 1（不逐层回退）

stun.go 的特殊地位：唯一被多处调用的 connect 文件（direct.go 和 ice.go 都需要它），所以独立存在。

2.3 transport/（3 个文件）— 传输层

职责：用 net.Conn 转发数据。不感知具体协议，通过 ProtocolPlugin 接口适配。

文件 职责 不做什么
conn_manager.go 连接索引：peer_key → net.Conn 的映射 不做建连、不转发数据
relay.go Read/Write 循环：从本地端口收包 → 查路由 → 通过 conn 发送；从 conn 收包 → 发到本地端口 不做建连
plugin.go 定义 ProtocolPlugin 接口 不实现任何协议

relay.go 的工作流程：

本地端口收到 WG 密文包
  → 调用 plugin.IsControlPacket() 判断包类型
    → true：控制包，按已建链路透传
  → 调用 plugin.IsDataPacket() 判断
    → true：调用 plugin.ExtractRouteID() 提取路由标识
      → 查路由标识映射表 → 发往对应本地端口
  → 都不是：丢弃

关键：relay.go 不知道 WireGuard，不知道 receiver index，只知道 route_id。

2.4 plugins/wg/（1 个文件）— 协议插件

职责：实现 ProtocolPlugin 接口，处理 WG 协议特有的包解析。

文件 职责 不做什么
wgparse.go 实现 IsDataPacket/ExtractRouteID/IsControlPacket 不做建连、不转发数据

WG 插件的具体实现：

方法 逻辑
IsControlPacket(packet) packet[0] ∈ {1, 2, 3} → true
IsDataPacket(packet) packet[0] == 4 → true
ExtractRouteID(packet) 读取 packet[4:8]，网络字节序解析为 uint32（即 WG receiver index）

2.5 plugins/wg/（1 个文件）

文件 职责
wgparse.go WireGuard 数据包解析和封装

三、分层架构图

┌─────────────────────────────────────────────────────────┐
│              internal/ctr/ctr.go                         │
│        直接调用 Core (进程内函数调用)                     │
└────────────────────────┬────────────────────────────────┘
                         │ 函数调用
┌────────────────────────▼────────────────────────────────┐
│                     core.go                              │
│              管理多个 Engine 实例                          │
└───┬─────────────────────────────────────────────────────┘
    │ 每个组网一个 Engine
    ▼
┌─────────────────────────────────────────────────────────┐
│                     engine.go                            │
│  持有：strategy + conn_manager + relay + plugin          │
│  协调 connect/ 和 transport/ 工作                         │
└───┬─────────────────────────────────────────────────────┘
    │
    ├──────────────────────────────────────────┐
    ▼                                          ▼
┌───────────────────────┐          ┌───────────────────────┐
│     connect/          │          │     transport/        │
│     建连层             │          │     传输层             │
│                       │          │                       │
│  strategy.go          │  返回    │  relay.go             │
│  ├─ direct.go   (L1)  │  net.Conn├─ plugin.go           │
│  ├─ fake_tcp.go (L2)  │────────►│  │  ProtocolPlugin    │
│  ├─ real_tcp.go (L3)  │         │  │                    │
│  ├─ turn.go     (L4/6/7)        │  │  插件调用           │
│  ├─ turn_quic.go(L5)  │         │  ▼                    │
│  ├─ ice.go      (L8)  │         │  plugins/wg/          │
│  └─ ws.go       (L9)  │         │  └─ wgparse.go        │
│                       │          │                       │
│  stun.go (被 direct/ice 调用)   │  conn_manager.go      │
└───────────────────────┘          └───────────────────────┘

四、调用关系

4.1 Engine 创建时

engine.go
  → 创建 WGPlugin（plugins/wg/wgparse.go）
  → 创建 Relay，传入 plugin（transport/relay.go）
  → 创建 Strategy（connect/strategy.go）
  → 创建 ConnManager（transport/conn_manager.go）

4.2 Bind 流程

ctr 直接调用：Bind()
  → engine.go 接收函数调用
  → engine.go 调用 strategy.Connect()
    → strategy 按优先级尝试各层
      → Layer 1: direct.go 调用 stun.go 获取候选，尝试 UDP 打洞
      → 不通？→ Layer 4: turn.go 调用 TURN 协商
      → 不通？→ Layer 9: ws.go 调用 WS 握手
    → 返回 net.Conn + 当前层级名
  → engine.go 把 net.Conn 注册到 conn_manager
  → engine.go 启动 relay 的 Read/Write 循环

4.3 数据转发流程

WG 发出密文包 → 本地端口
  → relay.go 收到
  → 调用 plugin.IsControlPacket()
    → true：按已建链路透传（conn_manager 查 conn）
  → 调用 plugin.IsDataPacket()
    → true：调用 plugin.ExtractRouteID() 获取 route_id
      → 查路由标识映射表 → 找到本地端口 → 发送
  → 都不是：丢弃

五、通用层与插件层的边界

层 知道什么 不知道什么
connect/ 网络协议（STUN/TURN/WS/WebRTC） WireGuard、route_id
transport/ net.Conn、route_id、ProtocolPlugin 接口 WireGuard、receiver index
plugins/wg/ WG 包格式、receiver index 网络连接、net.Conn
engine.go 协调 connect/ 和 transport/ WG 包格式细节

如果将来要支持其他协议：

  • 新建 plugins/xxx/xxxparse.go
  • 实现 ProtocolPlugin 接口的三个方法
  • engine.go 里换成 xxx.NewPlugin()
  • connect/、transport/、core.go 的代码完全不用改

六、Core 接口（直接被 ctr 调用）

方法 调用方 说明
CreateEngine ctr 创建一个 Engine 实例（直接函数调用）
Bind ctr 为每个 Peer 开启本地端口，开始建链
Unbind ctr 停止指定 Peer 的端口监听
Start ctr 启动转发主循环
Stop ctr 停止 Engine
GetStatus ctr 查询 Engine 状态
NotifyPeerInfo ctr 下发对端候选地址和 route_id

实现位置：

  • 所有方法都在 engine.go 中实现
  • core.go 提供 Engine 实例管理
  • ctr通过coreInst.CreateEngine(...)直接调用

七、文件清单汇总

目录 文件数 文件
根目录 3 core.go, engine.go, metrics.go
connect/ 9 strategy.go, stun.go, direct.go, fake_tcp.go, real_tcp.go, turn.go, turn_quic.go, ice.go, ws.go
transport/ 3 conn_manager.go, relay.go, plugin.go
plugins/wg/ 1 wgparse.go
总计 16

已删除的文件：

  • grpc_service.go - 不再需要（改为直接函数调用）
  • pool/connpool.go - 不再需要（无连接池）
  • proto/core.proto - 不再需要 gRPC
Reference in New Issue View Git Blame Copy Permalink