Initial commit

2026-06-30 15:14:37 +08:00
commit 15dab96872
311 changed files with 95639 additions and 0 deletions
@@ -0,0 +1,505 @@
+# MeshSeed 生成功能实现报告
+
+**完成时间**: 2026-03-24  
+**状态**: ✅ **框架已完成**  
+**优先级**: P1 - 高优先级
+
+---
+
+## 📋 **实现内容**
+
+### 1. MeshSeedService 服务层
+
+**文件**: [`internal/service/meshseed.go`](file://e:\Project\MeshRay\internal\service\meshseed.go) (新建，205 行)
+
+#### **核心功能**
+
+**GenerateMeshSeed - 生成组网凭证**
+```go
+func (s *MeshSeedService) GenerateMeshSeed(
+	networkID uint,      // 网络 ID
+	maxUses int,         // 最大使用次数
+	expiresAt time.Time, // 过期时间
+	ddnsEnabled bool     // DDNS 开关
+) (*model.MeshSeed, error)
+```
+
+**实现步骤**:
+1. ✅ 验证网络是否存在
+2. ✅ 生成 16 字节随机 SeedID（Base64 编码）
+3. ✅ 构建 JoinToken（包含网络信息的 JSON）
+4. ✅ Ed25519 数字签名
+5. ✅ 保存到数据库
+
+**数据结构**:
+```go
+// JoinToken = Base64(JSON({
+{
+  "seed_id":      "abc123...",
+  "network_id":   1,
+  "network_name": "MyNetwork",
+  "subnet_ipv4":  "10.0.0.0/24",
+  "mode":         "enhanced",
+  "ddns_enabled": true,
+  "expires_at":   1711234567,  // Unix 时间戳
+  "max_uses":     10
+}))
+```
+
+---
+
+**VerifyMeshSeed - 验证凭证**
+```go
+func (s *MeshSeedService) VerifyMeshSeed(
+	joinToken string,   // Base64 编码的 Token
+	signature string    // Base64 编码的签名
+) (*model.MeshSeed, error)
+```
+
+**验证步骤**:
+1. ✅ 解码 JoinToken 和签名
+2. ✅ Ed25519 签名验证
+3. ✅ 解析 Token 内容
+4. ✅ 查询 MeshSeed 记录
+5. ✅ 检查吊销状态
+6. ✅ 检查使用次数
+7. ✅ 检查过期时间
+
+**安全检查清单**:
+- ✅ 签名有效性（密码学保证）
+- ✅ 是否被吊销
+- ✅ 使用次数限制
+- ✅ 过期时间验证
+
+---
+
+**其他方法**:
+- `IncrementUseCount(seedID)` - 增加使用次数（事务）
+- `RevokeMeshSeed(seedID)` - 吊销凭证
+- `ListMeshSeeds(networkID)` - 获取网络的 MeshSeed 列表
+
+---
+
+### 2. API Handler 更新
+
+**文件**: [`internal/api/handler/network.go`](file://e:\Project\MeshRay\internal\api\handler\network.go#L315-L357)
+
+#### **POST /api/v1/networks/:id/meshseed**
+
+**请求参数**:
+```json
+{
+  "expires_in_hours": 24,      // 可选，默认 24 小时
+  "max_uses": 10,              // 可选，默认 10 次
+  "ddns_enabled": true         // 可选，默认 false
+}
+```
+
+**响应示例**（当前临时实现）:
+```json
+{
+  "message": "MeshSeed 生成成功（待实现完整逻辑）",
+  "data": {
+    "meshseed": "meshray://seed-1",
+    "expires_at": "2026-03-25T12:00:00Z",
+    "max_uses": 10,
+    "ddns_enabled": true
+  }
+}
+```
+
+**最终实现**（需要注入 service）:
+```go
+// 在 server.go 中初始化
+meshSeedService := service.NewMeshSeedService(s.store, s.logger, signingKey, issuerNodeID)
+
+// 在 handler 中调用
+meshSeed, err := h.meshSeedService.GenerateMeshSeed(
+	networkID, 
+	req.MaxUses, 
+	expiresAt, 
+	req.DDNSEnabled,
+)
+
+// 返回完整的 MeshSeed URL
+c.JSON(http.StatusOK, gin.H{
+	"data": gin.H{
+		"meshseed": "meshray://" + meshSeed.JoinToken,
+		"signature": meshSeed.Signature,
+		"expires_at": meshSeed.ExpiresAt.Format(time.RFC3339),
+		"max_uses": meshSeed.MaxUses,
+	},
+})
+```
+
+---
+
+## 🔐 **安全技术方案**
+
+### 1. Ed25519 数字签名
+
+**为什么选择 Ed25519?**
+- ✅ 高性能（比 RSA 快 100 倍）
+- ✅ 高安全性（256 位密钥）
+- ✅ 确定性签名（相同输入总是相同输出）
+- ✅ 抗侧信道攻击
+
+**签名流程**:
+```
+私钥 (Ed25519.PrivateKey)
+    ↓
+JoinToken → ed25519.Sign() → Signature
+    ↓
+Base64 编码 → "base64(signature_bytes)"
+```
+
+**验证流程**:
+```
+公钥 (Ed25519.PublicKey) + JoinToken + Signature
+    ↓
+ed25519.Verify() → true/false
+```
+
+---
+
+### 2. SeedID 生成
+
+**代码**:
+```go
+seedBytes := make([]byte, 16)
+crypto/rand.Read(seedBytes)  // 加密安全的随机数
+seedID := base64.RawURLEncoding.EncodeToString(seedBytes)
+```
+
+**特点**:
+- ✅ 16 字节（128 位）随机数
+- ✅ 使用 `crypto/rand`（不是`math/rand`）
+- ✅ Base64 URL 安全编码
+- ✅ 碰撞概率：2^128 ≈ 3.4×10^38
+
+---
+
+### 3. JoinToken 结构
+
+**JSON 格式**:
+```json
+{
+  "seed_id": "abc123...",
+  "network_id": 1,
+  "network_name": "测试网络",
+  "subnet_ipv4": "10.0.0.0/24",
+  "mode": "enhanced",
+  "ddns_enabled": true,
+  "expires_at": 1711234567,
+  "max_uses": 10
+}
+```
+
+**编码**:
+```
+JSON → Base64.StdEncoding → "eyJzZWVkX2lkIjoiYWJjMTIz..."
+```
+
+**URL 格式**:
+```
+meshray://eyJzZWVkX2lkIjoiYWJjMTIz...
+```
+
+---
+
+## 📊 **使用流程**
+
+### 场景 1：管理员生成 MeshSeed
+
+```
+1. 用户点击"生成 MeshSeed"
+   ↓
+2. 设置参数（有效期、使用次数）
+   ↓
+3. 调用 POST /api/v1/networks/:id/meshseed
+   ↓
+4. 后端生成并保存
+   ↓
+5. 前端显示二维码或分享链接
+```
+
+**二维码内容**:
+```
+meshray://eyJzZWVkX2lkIjoiYWJjMTIz...
+```
+
+---
+
+### 场景 2：新设备加入网络
+
+```
+1. 新设备扫描二维码/点击链接
+   ↓
+2. 客户端解析 meshray:// URL
+   ↓
+3. 提取 JoinToken 和 Signature
+   ↓
+4. 调用 POST /api/v1/join
+   {
+     "join_token": "...",
+     "signature": "..."
+   }
+   ↓
+5. 后端验证 MeshSeed
+   ↓
+6. 验证通过，创建设备
+   ↓
+7. 返回 WireGuard 配置
+```
+
+---
+
+## 🎯 **API 设计**
+
+### 完整 API 列表
+
+| 方法 | 路径 | 说明 | 状态 |
+|------|------|------|------|
+| **POST** | `/networks/:id/meshseed` | 生成 MeshSeed | ✅ 框架完成 |
+| **GET** | `/networks/:id/meshseeds` | 获取 MeshSeed 列表 | 🔲 待实现 |
+| **DELETE** | `/meshseeds/:seed_id` | 吊销 MeshSeed | 🔲 待实现 |
+| **POST** | `/join` | 使用 MeshSeed 加入 | 🔲 待实现 |
+| **POST** | `/meshseeds/:seed_id/use` | 增加使用次数 | 🔲 待实现 |
+
+---
+
+## 📝 **代码变更统计**
+
+| 文件 | 新增行 | 删除行 | 说明 |
+|------|--------|--------|------|
+| **service/meshseed.go** | 205 | 0 | 新建 Service 层 |
+| **handler/network.go** | 32 | 11 | 更新 Handler |
+| **合计** | 237 | 11 | 净增 226 行 |
+
+---
+
+## ⚠️ **TODO 事项**
+
+### 1. 初始化签名密钥
+
+**问题**: MeshSeedService 需要 Ed25519 私钥
+
+**解决方案**:
+```go
+// internal/service/meshseed.go
+type MeshSeedService struct {
+	store       *sqlite.Store
+	logger      *zap.Logger
+	signingKey  ed25519.PrivateKey  // ← 需要初始化
+	issuerNodeID string
+}
+```
+
+**初始化方式**:
+
+**方案 A: 启动时生成**
+```go
+// server.go
+_, signingKey, _ := ed25519.GenerateKey(rand.Reader)
+meshSeedService := service.NewMeshSeedService(s.store, s.logger, signingKey, "node-1")
+```
+
+**方案 B: 从配置文件读取**
+```go
+// config.yaml
+security:
+  meshseed_signing_key: "base64_encoded_private_key"
+
+// server.go
+keyBytes, _ := base64.StdEncoding.DecodeString(cfg.Security.SigningKey)
+signingKey := ed25519.PrivateKey(keyBytes)
+```
+
+**方案 C: 从数据库读取**
+```go
+// 首次启动时生成并保存
+var key model.SecurityKey
+db.First(&key, "meshseed_signing")
+if key.Value == "" {
+	_, newKey, _ := ed25519.GenerateKey(rand.Reader)
+	db.Create(&model.SecurityKey{
+		Name: "meshseed_signing",
+		Value: base64.StdEncoding.EncodeToString(newKey),
+	})
+}
+```
+
+**推荐**: **方案 C**（最安全，支持持久化）
+
+---
+
+### 2. 完善 Handler 注入
+
+**当前问题**:
+```go
+// network.go
+// TODO: 需要初始化 meshSeedService
+// meshSeed, err := h.meshSeedService.GenerateMeshSeed(...)
+```
+
+**解决**:
+```go
+// server.go
+// 1. 创建 MeshSeedService
+meshSeedService := service.NewMeshSeedService(s.store, s.logger, signingKey, "node-1")
+
+// 2. 创建 NetworkHandler 时注入
+networkHandler := handler.NewNetworkHandler(networkService, s.logger, meshSeedService)
+//                                                                ↑ 新增参数
+```
+
+---
+
+### 3. 前端对接
+
+**前端需要实现**:
+1. ✅ 生成 MeshSeed 的 UI（已调用 API）
+2. ✅ 显示二维码（qrcode 库）
+3. ✅ 分享功能（复制链接）
+4. ✅ MeshSeed 列表管理
+5. ✅ 吊销功能
+
+**二维码生成**:
+```vue
+<template>
+  <qrcode-vue :value="meshSeedUrl" :size="200"></qrcode-vue>
+</template>
+
+<script setup>
+const meshSeedUrl = computed(() => {
+  return `meshray://${meshSeedData.value.join_token}`
+})
+</script>
+```
+
+---
+
+## 🔍 **与其他功能的集成**
+
+### 1. DDNS 集成
+
+**当 DDNSEnabled=true 时**:
+```go
+// 自动生成 DDNS 记录
+if ddnsEnabled {
+	deviceName := "device-" + randomString(6)
+	ddnsDomain := setting.DDNSDomain  // 从 Settings 读取
+	fullDomain := deviceName + "." + ddnsDomain
+	
+	// 调用 DDNS 服务创建记录
+	ddnsService.CreateRecord(fullDomain, deviceIP)
+}
+```
+
+---
+
+### 2. 设备配置生成
+
+**使用 MeshSeed 加入后**:
+```go
+// 自动填充 Endpoint
+config += "Endpoint = " + setting.ServerIP + ":" + strconv.Itoa(setting.ServerPort) + "\n"
+
+// 如果使用 DDNS
+if ddnsEnabled {
+	config += "Endpoint = " + deviceDDNSDomain + ":51820\n"
+}
+```
+
+---
+
+### 3. 审计日志
+
+**记录所有 MeshSeed 操作**:
+```go
+logger.Info("MeshSeed 已生成",
+	zap.String("seed_id", seedID),
+	zap.Uint("network_id", networkID),
+	zap.Int("max_uses", maxUses),
+	zap.Time("expires_at", expiresAt))
+
+logger.Info("MeshSeed 已使用",
+	zap.String("seed_id", seedID),
+	zap.String("device_name", deviceName),
+	zap.String("request_ip", requestIP))
+```
+
+---
+
+## 🚀 **下一步计划**
+
+### 剩余工作（按优先级）
+
+| 任务 | 工作量 | 说明 |
+|------|--------|------|
+| **1. 初始化签名密钥** | 0.5 天 | 在 server.go 中生成/加载密钥 |
+| **2. 注入 MeshSeedService** | 0.5 天 | 更新 NetworkHandler 构造函数 |
+| **3. 完善 Handler 实现** | 0.5 天 | 调用真实 Service 方法 |
+| **4. 添加 MeshSeed 列表 API** | 0.5 天 | GET /networks/:id/meshseeds |
+| **5. 添加吊销 API** | 0.5 天 | DELETE /meshseeds/:seed_id |
+| **6. 实现 Join 接口** | 1 天 | POST /join 完整逻辑 |
+
+**总计**: 约 3.5 天完成全部功能
+
+---
+
+## ✅ **验证结果**
+
+### 编译测试
+```bash
+cd e:\Project\MeshRay
+go build -o meshray-test.exe ./cmd/meshray
+# ✅ 编译成功，无错误
+```
+
+### 代码质量
+- ✅ 使用加密安全的随机数
+- ✅ Ed25519 签名算法
+- ✅ 完整的安全检查
+- ✅ 事务保证数据一致性
+- ✅ 详细的日志记录
+
+---
+
+## 📚 **相关文档**
+
+- [Dashboard 统计功能实现报告.md](./Dashboard 统计功能实现报告.md)
+- [Settings 持久化功能实现报告.md](./Settings 持久化功能实现报告.md)
+- [前后端问题全面修复报告.md](./前后端问题全面修复报告.md)
+
+---
+
+## ✅ **总结**
+
+### 实现成果
+- ✅ 创建了完整的 MeshSeedService 服务层（205 行）
+- ✅ 实现了基于 Ed25519 的数字签名
+- ✅ 提供了完整的安全验证逻辑
+- ✅ 更新了 Handler 框架（待注入依赖）
+- ✅ 代码编译通过，无错误
+
+### 技术亮点
+- 🔐 **Ed25519 签名**: 密码学级别的安全性
+- 🎲 **加密随机数**: 使用 crypto/rand
+- ✅ **多重验证**: 签名 + 吊销 + 次数 + 过期
+- 💾 **事务支持**: 保证数据一致性
+- 📝 **详细日志**: 便于审计和调试
+
+### 用户体验提升（预期）
+- ⭐⭐⭐⭐⭐ 一键生成组网凭证
+- ⭐⭐⭐⭐⭐ 扫码快速加入网络
+- ⭐⭐⭐⭐⭐ 可视化的使用次数和过期时间
+- ⭐⭐⭐⭐⭐ 支持吊销，增强安全性
+
+---
+
+**状态**: ✅ **MeshSeed 框架已完成**  
+**下一项**: 注入签名密钥和完善实现（约 3.5 天）  
+**建议**: 继续实现设备密钥管理  
+
+*MeshRay - 安全便捷的组网凭证系统！* 🔐✨