# MeshRay 项目问题修复计划

**创建时间**: 2026-03-24  
**优先级**: P0 > P1 > P2  
**预计周期**: 2-3 周

---

## 📊 问题总览

| 优先级 | 数量 | 修复周期 | 风险等级 |
|--------|------|----------|----------|
| **P0 - 必须立即修复** | 5 | 2-3 天 | 🔴 极高 |
| **P1 - 本迭代修复** | 6 | 3-4 天 | 🟠 高 |
| **P2 - 下迭代修复** | 50+ | 1-2 周 | 🟡 中低 |

---

## 🔴 P0 - 必须立即修复（2-3 天）

### **问题 1: 使用 math/rand 生成密码**

**文件**: `internal/service/user.go:18`  
**风险**: 密码可预测，严重安全漏洞  
**修复方案**:

```go
// ❌ 错误代码
import "math/rand"
password := string(rand.Intn(1000))

// ✅ 正确代码
import "crypto/rand"
b := make([]byte, 32)
rand.Read(b)
password := base64.StdEncoding.EncodeToString(b)
```

**修复步骤**:
1. 替换 import
2. 使用 crypto/rand 生成随机字节
3. Base64 编码为密码字符串
4. 添加单元测试验证随机性

**预计时间**: 2 小时

---

### **问题 2: 固定模式生成加密密钥**

**文件**: `internal/config/config.go:153`  
**风险**: 所有实例使用相同密钥，完全无安全性  
**修复方案**:

```go
// ❌ 错误代码
key := []byte("meshray-secret-key-12345678") // 固定密钥

// ✅ 正确代码
// 首次启动时生成随机密钥
key := make([]byte, 32)
if _, err := rand.Read(key); err != nil {
    return err
}
// 保存到配置文件或环境变量
config.EncryptKey = base64.StdEncoding.EncodeToString(key)
```

**修复步骤**:
1. 检查配置文件中是否已有密钥
2. 如无，则生成随机密钥并保存
3. 如有，则读取使用
4. 添加密钥轮换机制（可选）

**预计时间**: 4 小时

---

### **问题 3: Linux 特定命令跨平台不兼容**

**文件**: `internal/ctr/wg.go:378,464`  
**风险**: Windows/macOS 无法运行  
**修复方案**:

```go
// ❌ 错误代码
exec.Command("ip", "link", "add", name, "type", "wireguard")

// ✅ 正确代码（条件编译）
// wg_linux.go
// +build linux
func createDevice(name string) error {
    exec.Command("ip", "link", "add", name, "type", "wireguard")
}

// wg_windows.go
// +build windows
func createDevice(name string) error {
    // Windows 使用 wireguard.exe
    exec.Command("wireguard.exe", "/installtunnelservice", configPath)
}

// wg_darwin.go
// +build darwin
func createDevice(name string) error {
    // macOS 使用 wg-go-tool
    exec.Command("wg-go-tool", "-c", configPath)
}
```

**修复步骤**:
1. 创建 3 个平台特定文件
2. 使用 build tag 区分
3. 提取公共接口
4. 测试各平台编译

**预计时间**: 1 天

---

### **问题 4: TUN 设备资源泄漏**

**文件**: `internal/ctr/wg.go:414-418`  
**风险**: 长时间运行后资源耗尽  
**修复方案**:

```go
// ❌ 错误代码
func (w *WGManager) createTUN() error {
    tun, err := tun.CreateTUN("wg0", mtu)
    // 未保存引用，后续无法关闭
    return nil
}

// ✅ 正确代码
type WGManager struct {
    tunDevices map[string]device.Device // 保存引用
}

func (w *WGManager) createTUN() error {
    tun, err := tun.CreateTUN("wg0", mtu)
    if err != nil {
        return err
    }
    
    // 保存引用
    w.tunDevices["wg0"] = tun
    
    return nil
}

func (w *WGManager) Stop() error {
    // 关闭所有 TUN 设备
    for _, tun := range w.tunDevices {
        tun.Close()
    }
    return nil
}
```

**修复步骤**:
1. 在 WGManager 中添加 tunDevices 字段
2. 创建 TUN 后保存引用
3. Stop() 方法中关闭所有设备
4. 添加延迟测试验证无泄漏

**预计时间**: 4 小时

---

### **问题 5: wgDevice 未保存引用**

**文件**: `internal/ctr/wg.go:433`  
**风险**: 无法管理/关闭 WG 设备  
**修复方案**:

```go
// ❌ 错误代码
wgDevice, err := wgctrl.New()
// 未保存，后续无法访问

// ✅ 正确代码
type WGManager struct {
    wgClients map[string]*wgctrl.Client
}

func (w *WGManager) initWG(deviceName string) error {
    client, err := wgctrl.New()
    if err != nil {
        return err
    }
    
    // 保存引用
    w.wgClients[deviceName] = client
    
    return nil
}

func (w *WGManager) Close() error {
    // 关闭所有 WG 客户端
    for _, client := range w.wgClients {
        client.Close()
    }
    return nil
}
```

**修复步骤**:
1. 在 WGManager 中添加 wgClients 字段
2. 创建 WG 客户端后保存引用
3. Close() 方法统一关闭
4. 添加单元测试验证

**预计时间**: 3 小时

---

## 🟠 P1 - 本迭代修复（3-4 天）

### **问题 6: ctr 初始化错误未返回**

**文件**: `internal/api/server.go:168`  
**风险**: ctrClient 为 nil 导致 panic  
**修复方案**:

```go
// ❌ 错误代码
ctrClient, err := ctr.NewClient(config)
// 未检查 err

// ✅ 正确代码
ctrClient, err := ctr.NewClient(config)
if err != nil {
    log.Error("初始化 ctr 失败", zap.Error(err))
    return err // ← 返回错误，阻止启动
}
```

**预计时间**: 1 小时

---

### **问题 7: CreateNetwork 失败不回滚数据库**

**文件**: `internal/service/network.go:85-92`  
**风险**: 数据不一致  
**修复方案**:

```go
// ❌ 错误代码
func (s *NetworkService) CreateNetwork(req) error {
    network := &model.Network{...}
    s.store.DB().Create(network) // ← 保存
    
    err = s.ctrClient.CreateNetwork(...)
    if err != nil {
        return err // ← 失败但未回滚！
    }
}

// ✅ 正确代码
func (s *NetworkService) CreateNetwork(req) error {
    tx := s.store.DB().Begin()
    defer func() {
        if r := recover(); r != nil {
            tx.Rollback()
        }
    }()
    
    network := &model.Network{...}
    if err := tx.Create(network).Error; err != nil {
        tx.Rollback()
        return err
    }
    
    err = s.ctrClient.CreateNetwork(...)
    if err != nil {
        tx.Rollback() // ← 回滚
        return fmt.Errorf("调用 ctr 失败：%w", err)
    }
    
    return tx.Commit().Error
}
```

**预计时间**: 4 小时

---

### **问题 8: AddPeer 错误只记录不处理**

**文件**: `internal/service/device.go:115`  
**风险**: Peer 添加失败但用户以为成功  
**修复方案**:

```go
// ❌ 错误代码
err = s.ctrClient.AddPeer(...)
if err != nil {
    log.Error("添加 Peer 失败", zap.Error(err))
    // 未返回错误！
}

// ✅ 正确代码
err = s.ctrClient.AddPeer(...)
if err != nil {
    log.Error("添加 Peer 失败", zap.Error(err))
    return fmt.Errorf("添加设备失败：%w", err) // ← 返回错误
}
```

**预计时间**: 30 分钟

---

### **问题 9: 类型断言无检查**

**文件**: `internal/service/ddns.go:187`  
**风险**: 可能 panic  
**修复方案**:

```go
// ❌ 错误代码
provider := config.Provider.(DDNSProvider) // 可能 panic

// ✅ 正确代码
provider, ok := config.Provider.(DDNSProvider)
if !ok {
    return errors.New("无效的 DDNS Provider 类型")
}
```

**预计时间**: 30 分钟

---

### **问题 10: CORS 允许所有来源**

**文件**: `internal/api/middleware/auth.go:288`  
**风险**: CSRF 攻击  
**修复方案**:

```go
// ❌ 错误代码
middleware.AllowOrigin("*") // 允许所有来源

// ✅ 正确代码
// 从配置读取允许的来源
allowedOrigins := config.CORS.AllowedOrigins
if len(allowedOrigins) == 0 {
    allowedOrigins = []string{"http://localhost:5173"}
}

middleware.AllowOrigin(allowedOrigins...)
```

**预计时间**: 2 小时

---

### **问题 11: Go 版本不存在**

**文件**: `go.mod`  
**风险**: 无法编译  
**修复方案**:

```diff
- go 1.25.0
+ go 1.21.0  # 使用最新稳定版
```

**预计时间**: 10 分钟

---

## 🟡 P2 - 下迭代修复（1-2 周）

### **分类 1: 前端 API 未对接（30+ 处）**

**涉及文件**:
- `web/src/views/Settings/*`
- `web/src/views/Monitor/*`
- `web/src/views/Networks/*`

**修复计划**:
1. 第 1 周：完成 Settings 页面 API 对接
2. 第 2 周：完成 Monitor 页面 API 对接
3. 第 3 周：完成 Networks 页面 API 对接

**预计时间**: 1 周

---

### **分类 2: 后端功能未完成**

**待实现功能**:
- [ ] DDNS 同步完整实现
- [ ] MeshSeed 生成和解析
- [ ] Watchdog 监控机制
- [ ] 告警规则引擎
- [ ] 审计日志导出

**预计时间**: 3-4 天

---

### **分类 3: 并发安全问题**

**涉及文件**:
- `core/connect/strategy.go` - channel 锁保护
- `internal/ctr/wg.go` - 并发访问保护

**修复方案**:
```go
type StrategyScheduler struct {
    mu sync.RWMutex
    // ...
}
```

**预计时间**: 1 天

---

### **分类 4: 依赖清理**

**未使用的依赖**:
```diff
- github.com/some/unused-package v1.0.0
- github.com/another/unused v2.0.0
```

**修复步骤**:
1. 使用 `go mod why` 确认是否使用
2. 删除未使用的依赖
3. 运行 `go mod tidy`

**预计时间**: 2 小时

---

## 📋 详细时间表

### **第 1 周：P0 修复**

| 时间 | 任务 | 负责人 |
|------|------|--------|
| Day 1 AM | 问题 1: 随机数生成修复 | Dev A |
| Day 1 PM | 问题 2: 加密密钥修复 | Dev A |
| Day 2 AM | 问题 3: 跨平台兼容 | Dev B |
| Day 2 PM | 问题 4: TUN 设备引用 | Dev B |
| Day 3 AM | 问题 5: wgDevice 引用 | Dev B |
| Day 3 PM | 测试验证 | QA |

### **第 2 周：P1 修复**

| 时间 | 任务 | 负责人 |
|------|------|--------|
| Day 1 | 问题 6-8: 错误处理 | Dev A |
| Day 2 | 问题 9-10: 类型安全和 CORS | Dev B |
| Day 3 | 问题 11: Go 版本 + 回归测试 | Dev A + QA |

### **第 3-4 周：P2 修复**

| 时间 | 任务 | 负责人 |
|------|------|--------|
| Week 3 | 前端 API 对接（Settings） | Frontend |
| Week 4 | 前端 API 对接（Monitor） | Frontend |
| Week 4 | 后端功能完善 | Backend |

---

## ✅ 验收标准

### **P0 修复验收**
- [ ] 密码生成通过 NIST 随机性测试
- [ ] 加密密钥每个实例唯一
- [ ] Windows/macOS/Linux 均能编译运行
- [ ] 72 小时运行无资源泄漏
- [ ] WG 设备正常启停

### **P1 修复验收**
- [ ] 所有错误都有返回和日志
- [ ] 数据库事务回滚测试通过
- [ ] CORS 配置化且默认安全
- [ ] 编译无警告

### **P2 修复验收**
- [ ] 前端 API 对接率 > 90%
- [ ] 核心功能完整可用
- [ ] 并发测试无 race condition
- [ ] 依赖列表精简

---

## 🎯 风险控制

### **高风险项**
1. **跨平台兼容性** - 需要实际测试环境
   - 缓解：使用 GitHub Actions CI/CD

2. **资源泄漏** - 难以复现
   - 缓解：压力测试 + 内存分析

3. **数据库回滚** - 影响现有逻辑
   - 缓解：充分的单元测试

---

## 📊 进度跟踪

使用 GitHub Projects 跟踪：
- P0 Issues: 5 个
- P1 Issues: 6 个
- P2 Issues: 50+ 个

**每日站会**同步进度，**每周五**演示修复成果。

---

*创建时间：2026-03-24*  
*版本：v1.0*  
*下次更新：完成 P0 修复后*