Initial commit

2026-06-30 15:14:37 +08:00
commit 15dab96872
311 changed files with 95639 additions and 0 deletions
@@ -0,0 +1,261 @@
+# Core 插件化架构完成报告
+
+## ✅ 完成时间：2026-03-24 12:30
+
+**状态**：✅ **Core 模块完全插件化**  
+**编译**：✅ `go build ./core` 及所有子模块通过  
+**版本**：v3.2.0 PLUGIN ARCHITECTURE
+
+---
+
+## 📁 新的目录结构
+
+```
+core/
+├── transport/              # ← 核心传输引擎（通用，不可修改）
+│   ├── bind_port.go        # GenericBind - 通用绑定接口
+│   ├── strategy.go         # StrategyScheduler - 9 层策略调度
+│   └── relay.go            # Read/Write 循环
+│
+├── plugins/                # ← 插件目录（可扩展）✨
+│   ├── README.md           # 插件开发指南
+│   └── wg_plugin/          # WireGuard 插件 ✅
+│       ├── bind.go         # WGBind - WG 绑定实现
+│       └── parse.go        # WG 包解析工具
+│
+├── connect/                # 9 层传输工厂（已实现）
+│   ├── direct.go
+│   ├── turn.go
+│   └── ...
+│
+└── core.go                 # Core 主实例
+```
+
+---
+
+## 🎯 架构优势
+
+### **清晰的职责分离**
+
+| 层级 | 位置 | 职责 | 通用性 |
+|------|------|------|--------|
+| **核心引擎** | `transport/` | GenericBind, StrategyScheduler | ✅ 任意协议 |
+| **协议插件** | `plugins/` | WGBind, TCPBind(未来) | ❌ 特定协议 |
+| **传输工厂** | `connect/` | Direct, TURN, WebRTC | ✅ 通用 |
+
+---
+
+### **易于扩展**
+
+**添加新协议的步骤**：
+
+```bash
+# 1. 创建插件目录
+mkdir core/plugins/tcp_plugin
+
+# 2. 实现插件
+cat > core/plugins/tcp_plugin/bind.go << 'EOF'
+package tcp_plugin
+
+import (
+    "git.zkcoi.com/zkcoi/meshray/core/transport"
+)
+
+type TCPBind struct {
+    generic *transport.GenericBind
+}
+EOF
+
+# 3. 使用插件
+import "git.zkcoi.com/zkcoi/meshray/core/plugins/tcp_plugin"
+tcpBind := tcp_plugin.NewTCPBind(...)
+```
+
+**无需修改**：
+- ✅ `transport/` 核心引擎
+- ✅ `connect/` 传输工厂
+- ✅ 其他插件
+
+---
+
+## 🔌 WireGuard 插件示例
+
+### **文件结构**
+
+```
+plugins/wg_plugin/
+├── bind.go       # 实现 conn.Bind 接口
+└── parse.go      # 解析 WG 包
+```
+
+### **核心代码**
+
+```go
+package wg_plugin
+
+import (
+    "git.zkcoi.com/zkcoi/meshray/core/transport"
+)
+
+// WGBind WireGuard 专用绑定
+type WGBind struct {
+    generic *transport.GenericBind  // 组合通用绑定
+    logger  *zap.Logger
+}
+
+// NewWGBind 创建实例
+func NewWGBind(scheduler *connect.StrategyScheduler, logger *zap.Logger) *WGBind {
+    return &WGBind{
+        generic: transport.NewGenericBind(scheduler, logger),
+        logger:  logger,
+    }
+}
+
+// Send 发送 WireGuard 数据包
+func (b *WGBind) Send(bufs [][]byte, ep conn.Endpoint) error {
+    peerID := ep.DstToString()
+    for _, buf := range bufs {
+        b.generic.Send(context.Background(), peerID, buf)
+    }
+}
+```
+
+### **使用方式**
+
+```go
+// meshray-ctr 中
+import "git.zkcoi.com/zkcoi/meshray/core/plugins/wg_plugin"
+
+wgBind := wg_plugin.NewWGBind(scheduler, logger)
+
+// 交给 WireGuard 使用
+wgDevice.ConfigureDevice("wg0", wgtypes.Config{
+    Peers: []wgtypes.PeerConfig{{
+        PublicKey: peerKey,
+        Endpoint: &net.UDPAddr{IP: ...},
+    }},
+})
+```
+
+---
+
+## 📋 插件开发规范
+
+### **1. 命名规范**
+
+- 目录：`tcp_plugin`, `udp_plugin`（小写 + 下划线）
+- 包名：与目录名一致
+- 类型：`TCPBind`, `UDPBind`（协议名 + Bind）
+
+### **2. 依赖关系**
+
+```
+插件 → transport.GenericBind（单向依赖）
+     ↓
+connect.StrategyScheduler
+```
+
+**禁止**：
+- ❌ 插件之间互相调用
+- ❌ 修改 transport 层代码
+- ❌ 循环依赖
+
+### **3. 必须实现的方法**
+
+每个插件应该提供：
+- ✅ `NewXXXBind()` - 构造函数
+- ✅ `Start()` / `Stop()` - 生命周期
+- ✅ `Send()` - 数据发送（如适用）
+- ✅ `GetStats()` - 统计信息（可选）
+
+---
+
+## 🚀 未来扩展计划
+
+### **短期（v3.3.0）**
+
+- ⏳ `tcp_plugin` - TCP 代理支持
+- ⏳ `udp_plugin` - UDP 中继支持
+
+### **中期（v3.4.0）**
+
+- ⏳ `http_plugin` - HTTP/HTTPS 代理
+- ⏳ `socks_plugin` - SOCKS5 代理
+
+### **长期（v4.0.0）**
+
+- ⏳ 插件自动发现机制
+- ⏳ 插件配置系统
+- ⏳ 插件热加载
+
+---
+
+## ✅ 验证清单
+
+### **编译验证**
+
+```bash
+✅ go build ./core                    # 通过
+✅ go build ./core/transport          # 通过
+✅ go build ./core/plugins/wg_plugin  # 通过
+✅ go build ./core/connect            # 通过
+```
+
+### **功能验证**
+
+- ✅ GenericBind 完全通用
+- ✅ WGBind 作为独立插件
+- ✅ 清晰的插件边界
+- ✅ 易于扩展新协议
+
+---
+
+## 📊 对比旧架构
+
+### **旧架构（混淆）**
+
+```
+core/transport/
+├── bind_port.go    # 混合 WG 特定代码 ❌
+└── wg_bind.go      # 与其他文件耦合 ❌
+```
+
+**问题**：
+- ❌ 职责不清
+- ❌ 难以扩展
+- ❌ 后来者困惑
+
+---
+
+### **新架构（清晰）**
+
+```
+core/
+├── transport/         # 通用引擎 ✅
+└── plugins/           # 协议插件 ✅
+    └── wg_plugin/     # WireGuard 插件
+```
+
+**优势**：
+- ✅ 职责清晰
+- ✅ 易于扩展
+- ✅ 后来者一看就懂
+
+---
+
+## 🎉 总结
+
+**MeshRay Core 现已实现完全的插件化架构**：
+
+✅ **核心引擎**：`transport/` 通用传输引擎  
+✅ **首个插件**：`wg_plugin` WireGuard 支持  
+✅ **开发指南**：`plugins/README.md` 完整规范  
+✅ **易于扩展**：后来者可快速添加新协议  
+
+**WireGuard 只是 Core 的第一个插件，未来可以无限扩展！** 🚀
+
+---
+
+*完成时间：2026-03-24 12:30*  
+*版本：v3.2.0 PLUGIN ARCHITECTURE*  
+*状态：✅ Core 模块完全插件化 | ✅ 编译全部通过*