262 lines
5.6 KiB
Markdown
262 lines
5.6 KiB
Markdown
# 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 模块完全插件化 | ✅ 编译全部通过*
|