Initial commit

2026-06-30 15:14:37 +08:00
commit 15dab96872
311 changed files with 95639 additions and 0 deletions
@@ -0,0 +1,168 @@
+# 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 协议实现，被多处调用
+
+```go
+// 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 协议协商 + 建连，自包含
+
+```go
+// 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 握手 + 帧收发 + 身份标识，自包含
+
+```go
+// 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 行）*  
+*状态：⏳ 进行中*