Meshray-Manager/docs/core 架构重构_v2.2.md

Core 模块架构重构 - 按新版 README（1-91 行）

🎯 核心原则

被多处调用才独立文件，只被一处调用就合并。不制造不必要的目录层级。

---

📁 新的目录结构

core/
├── core.go
├── engine.go
├── bind.go
├── metrics.go
│
├── connect/                      # ✅ 建连层：所有和"怎么连"有关的代码
│   ├── strategy.go               # ✅ 9 层策略调度 + 自动切换 + 恢复探测
│   ├── stun.go                   # ⏳ STUN 协议：候选地址采集（被 direct.go 和 ice.go 调用）
│   ├── direct.go                 # ✅ Layer 1: Direct-UDP（调用 stun.go 获取候选，然后打洞）
│   ├── fake_tcp.go               # ✅ Layer 2: FakeTCP
│   ├── real_tcp.go               # ✅ Layer 3: RealTCP
│   ├── turn.go                   # ⏳ Layer 4-6: TURN-UDP/TCP/TLS（TURN 协议协商 + 建连，自包含）
│   ├── turn_quic.go              # ✅ Layer 5: TURN-QUIC（独立文件，私有扩展）
│   ├── ice.go                    # ✅ Layer 7: ICE + WebRTC（调用 stun.go 收集候选）
│   └── ws.go                     # ⏳ Layer 8: WS/WSS（握手 + 帧收发 + 身份标识，自包含）
│
├── transport/                    # ✅ 传输层：用连接转发数据
│   ├── bind_port.go              # ✅ 本地端口 Bind + 路由标识映射表
│   ├── relay.go                  # ✅ Read/Write 循环 + 链路生命周期
│   └── wgparse.go                # ✅ WG 包解析
│
├── pool/                         # ✅ 连接池
│   └── connpool.go               # ✅ 连接池
│
└── proto/                        # ⏳ gRPC 接口定义
    └── core.proto                # ⏳ 待创建

---

✅ 已完成的重构

Step 1: 删除 client/ 目录 ✅

理由：不制造不必要的目录层级

❌ 旧架构：
   connect/ → 调用 → client/stun_client.go
   connect/ → 调用 → client/turn_client.go
   connect/ → 调用 → client/ws_client.go

✅ 新架构：
   connect/stun.go    ← 被 direct.go 和 ice.go 调用
   connect/turn.go    ← 自包含，不需要拆分
   connect/ws.go      ← 自包含，不需要拆分

---

⏳ 待完成的工作

1. 创建 connect/stun.go

职责：STUN 协议实现，被多处调用

// connect/stun.go
package connect

// DiscoverAddress 发现外部地址
func DiscoverAddress(stunServer string) (*net.UDPAddr, error)

// CollectCandidates 收集候选地址
func CollectCandidates(servers []string) []string

调用关系：

• direct.go 调用 → 获取候选地址用于打洞
• ice.go 调用 → 收集 ICE 候选

---

2. 完善 connect/turn.go

职责：TURN 协议协商 + 建连，自包含

// connect/turn.go
package connect

// DialTURN TURN 中继连接建立
func DialTURN(server, username, password, network string, peerAddr string) (net.Conn, error) {
    // 内部实现：
    // 1. Allocate Request（申请中继地址）
    // 2. CreatePermission（允许对端发数据）
    // 3. ChannelBind（绑定高效通道）
    // 4. 返回 net.Conn
}

调用关系：

• 只被 strategy.go 调用 → 不需要拆分

---

3. 完善 connect/ws.go

职责：WS 握手 + 帧收发 + 身份标识，自包含

// connect/ws.go
package connect

// DialWS WebSocket 连接建立
func DialWS(server, path string, useTLS bool, engineID, peerKey string) (net.Conn, error) {
    // 内部实现：
    // 1. Handshake（HTTP Upgrade）
    // 2. Identify（身份标识）
    // 3. Frame Encode/Decode
    // 4. 返回 net.Conn
}

调用关系：

• 只被 strategy.go 调用 → 不需要拆分

---

📊 对比两版架构

维度	旧架构（第 50-79 行）	新架构（第 1-91 行）	改进
目录层级	connect/ + client/	只有 connect/	⭐⭐⭐ 更简洁
文件组织	按"是否返回连接"分离	按"是否被多处调用"分离	⭐⭐⭐ 更合理
stun 实现	client/stun_client.go	connect/stun.go	⭐⭐⭐ 更直接
turn 实现	client/turn_client.go + connect/turn.go	只有 connect/turn.go	⭐⭐⭐ 避免分裂
ws 实现	client/ws_client.go + connect/ws.go	只有 connect/ws.go	⭐⭐⭐ 避免分裂

---

🎯 下一步行动

P0 - 立即执行

1. 从备份恢复或重写 stun.go

   • 原来的 client/stun_client.go 已删除
   • 需要创建 connect/stun.go

2. 更新 direct.go

   • 改为调用新的 stun.go

3. 更新 ice.go

   • 改为调用新的 stun.go

P1 - 后续完善

4. 完善 turn.go - 添加完整的 TURN 协议实现
5. 完善 ws.go - 添加完整的 WS 协议实现
6. 创建 proto/core.proto - gRPC 接口定义

---

创建时间：2026-03-24 02:00
版本：v2.2.0（基于新版 README 1-91 行）
状态：⏳ 进行中