352 lines
6.9 KiB
Markdown
352 lines
6.9 KiB
Markdown
# MeshRay 全功能遍历与问题排查计划
|
||
|
||
## 📋 遍历方法论
|
||
|
||
### 用户视角遍历
|
||
- **起点**: 用户第一个触点（登录/注册）
|
||
- **路径**: 按照实际使用流程
|
||
- **覆盖**: 前端页面 → API 接口 → 业务逻辑 → 数据库
|
||
- **深度**: 每个功能的完整实现链路
|
||
|
||
### 技术栈遍历
|
||
- **前端**: Vue 组件、路由、状态管理、API 调用
|
||
- **后端**: Handler → Service → Model/Store
|
||
- **核心**: Ctr → Core → WireGuard
|
||
- **数据**: SQLite 表结构、关系、完整性
|
||
|
||
---
|
||
|
||
## 🗺️ 功能模块地图
|
||
|
||
### 1. 用户认证与系统入口
|
||
- [ ] 登录页面 (`/login`)
|
||
- [ ] 注册页面 (`/register`)
|
||
- [ ] 首页/Dashboard (`/`)
|
||
- [ ] 系统配置
|
||
|
||
### 2. 网络管理（核心功能）
|
||
- [ ] 网络列表页面 (`/networks`)
|
||
- [ ] 创建网络
|
||
- [ ] 网络详情
|
||
- [ ] 网络配置
|
||
- [ ] Peer 管理
|
||
- [ ] IP 地址分配
|
||
|
||
### 3. STUN/TURN 服务
|
||
- [ ] STUN 服务器配置
|
||
- [ ] TURN 服务器配置
|
||
- [ ] 服务可用性检测
|
||
- [ ] 自动打洞配置
|
||
|
||
### 4. DDNS 服务
|
||
- [ ] DDNS Provider 配置
|
||
- [ ] DDNS Usage 管理
|
||
- [ ] 域名绑定
|
||
- [ ] 自动更新
|
||
|
||
### 5. 系统管理
|
||
- [ ] 备份恢复
|
||
- [ ] 通知中心
|
||
- [ ] 系统更新检查
|
||
- [ ] 日志查看
|
||
|
||
### 6. Core 协议层
|
||
- [ ] Core 客户端连接
|
||
- [ ] 设备发现
|
||
- [ ] NAT 类型检测
|
||
- [ ] 打洞策略
|
||
- [ ] 中继 fallback
|
||
|
||
---
|
||
|
||
## 🔍 详细遍历路径
|
||
|
||
### 路径 1: 用户首次使用 - 创建网络
|
||
|
||
**前端**:
|
||
1. 登录 → Dashboard
|
||
2. 点击"创建网络"
|
||
3. 填写网络配置（名称、IP 段、MTU 等）
|
||
4. 提交创建
|
||
5. 跳转到网络详情
|
||
|
||
**后端**:
|
||
1. `POST /api/v1/networks`
|
||
2. `handler.NetworkHandler.CreateNetwork`
|
||
3. `service.NetworkService.CreateNetwork`
|
||
4. 验证配置
|
||
5. 生成雪花 ID
|
||
6. 分配子网
|
||
7. 创建管理员 Peer
|
||
8. 保存到数据库
|
||
|
||
**Core 层**:
|
||
1. Ctr 监听网络创建事件
|
||
2. 配置 WG 设备
|
||
3. 生成密钥对
|
||
4. 设置监听端口
|
||
|
||
**排查点**:
|
||
- ✅ 雪花 ID 生成是否正确（uint64 处理）
|
||
- ✅ 子网分配算法
|
||
- ✅ Peer 配置生成
|
||
- ✅ WG 设备创建成功
|
||
- ✅ 数据库事务完整性
|
||
|
||
---
|
||
|
||
### 路径 2: 添加 Peer（用户态模式）
|
||
|
||
**前端**:
|
||
1. 网络详情页 → "添加 Peer"
|
||
2. 选择"用户态模式"
|
||
3. 填写 Peer 信息（名称、IP）
|
||
4. 下载配置文件
|
||
5. 启动 Peer
|
||
|
||
**后端**:
|
||
1. `POST /api/v1/networks/{id}/peers`
|
||
2. `handler.PeerHandler.CreatePeer`
|
||
3. `service.PeerService.CreatePeer`
|
||
4. 验证 IP 可用性
|
||
5. 生成 Peer 配置
|
||
6. 返回 WireGuard 配置
|
||
|
||
**Core 层**:
|
||
1. Ctr 收到 Peer 创建事件
|
||
2. 调用 `wg.AddPeer`
|
||
3. 配置用户态 WG 设备
|
||
4. 设置代理规则
|
||
|
||
**排查点**:
|
||
- ✅ Peer IP 冲突检测
|
||
- ✅ 配置文件格式正确
|
||
- ✅ WG 设备添加成功
|
||
- ✅ 路由表更新
|
||
- ✅ 连通性测试
|
||
|
||
---
|
||
|
||
### 路径 3: STUN 自动配置
|
||
|
||
**前端**:
|
||
1. 网络详情 → STUN 配置
|
||
2. 启用 STUN 穿透
|
||
3. 选择 STUN 服务器
|
||
4. 保存配置
|
||
|
||
**后端**:
|
||
1. `PUT /api/v1/networks/{id}/stun`
|
||
2. `handler.NetworkHandler.UpdateSTUNConfig`
|
||
3. `service.STUNService.Configure`
|
||
4. 验证 STUN 服务器可用性
|
||
5. 更新网络配置
|
||
|
||
**Core 层**:
|
||
1. Ctr 监听 STUN 配置变更
|
||
2. 自动配置 STUN 给 WG
|
||
3. 设置 endpoint 发现机制
|
||
|
||
**排查点**:
|
||
- ✅ STUN 服务器可达性
|
||
- ✅ WG Endpoint 自动填充
|
||
- ✅ NAT 类型检测准确
|
||
- ✅ 打洞成功率统计
|
||
|
||
---
|
||
|
||
### 路径 4: TURN 中继 fallback
|
||
|
||
**前端**:
|
||
1. 网络详情 → TURN 配置
|
||
2. 启用 TURN 中继
|
||
3. 配置 TURN 服务器
|
||
4. 设置 fallback 条件
|
||
|
||
**后端**:
|
||
1. `PUT /api/v1/networks/{id}/turn`
|
||
2. `handler.NetworkHandler.UpdateTURNConfig`
|
||
3. `service.TURNServerService.Validate`
|
||
4. 测试 TURN 服务器连接
|
||
5. 保存配置
|
||
|
||
**Core 层**:
|
||
1. Ctr 监听 TURN 配置
|
||
2. 监控打洞失败
|
||
3. 自动切换到 TURN 中继
|
||
4. 更新 Peer 配置
|
||
|
||
**排查点**:
|
||
- ✅ TURN 凭证生成
|
||
- ✅ fallback 触发条件
|
||
- ✅ 中继路由优先级
|
||
- ✅ 切换延迟
|
||
|
||
---
|
||
|
||
### 路径 5: DDNS 全自动模式
|
||
|
||
**前端**:
|
||
1. DDNS 管理 → 创建 Provider
|
||
2. 配置 API Token
|
||
3. 创建 DDNS Usage
|
||
4. 绑定到网络
|
||
|
||
**后端**:
|
||
1. `POST /api/v1/ddns/providers`
|
||
2. `POST /api/v1/ddns/usages`
|
||
3. `POST /api/v1/networks/{id}/bind-ddns`
|
||
4. 验证 Provider 配置
|
||
5. 测试 DNS API
|
||
6. 建立绑定关系
|
||
|
||
**Core 层**:
|
||
1. 监听 IP 变化
|
||
2. 自动更新 DNS 记录
|
||
3. 同步到所有 Peer
|
||
|
||
**排查点**:
|
||
- ✅ Provider 验证逻辑
|
||
- ✅ DNS 记录创建成功
|
||
- ✅ IP 检测准确性
|
||
- ✅ 更新频率控制
|
||
- ✅ 错误重试机制
|
||
|
||
---
|
||
|
||
### 路径 6: 备份与恢复
|
||
|
||
**前端**:
|
||
1. 系统管理 → 备份
|
||
2. 点击"创建备份"
|
||
3. 下载备份文件
|
||
4. 上传备份恢复
|
||
|
||
**后端**:
|
||
1. `POST /api/v1/system/backup`
|
||
2. `handler.BackupHandler.CreateBackup`
|
||
3. `service.BackupService.CreateBackup`
|
||
4. 导出数据库
|
||
5. 打包配置文件
|
||
6. 返回 ZIP 文件
|
||
|
||
**恢复流程**:
|
||
1. `POST /api/v1/system/restore`
|
||
2. 上传 ZIP 文件
|
||
3. 解压
|
||
4. 恢复数据库
|
||
5. 恢复配置
|
||
6. 重启服务
|
||
|
||
**排查点**:
|
||
- ✅ 数据库导出完整
|
||
- ✅ 配置文件备份
|
||
- ✅ 压缩包格式正确
|
||
- ✅ 恢复时事务安全
|
||
- ✅ 服务重启成功
|
||
|
||
---
|
||
|
||
### 路径 7: 实时通知推送
|
||
|
||
**前端**:
|
||
1. WebSocket 连接
|
||
2. 监听通知事件
|
||
3. 显示通知弹窗
|
||
4. 标记已读
|
||
|
||
**后端**:
|
||
1. WebSocket 握手
|
||
2. 认证中间件
|
||
3. 维护连接池
|
||
4. 广播通知
|
||
|
||
**排查点**:
|
||
- ✅ WebSocket 认证
|
||
- ✅ 心跳保活
|
||
- ✅ 断线重连
|
||
- ✅ 消息不丢失
|
||
- ✅ 并发连接处理
|
||
|
||
---
|
||
|
||
### 路径 8: Core 协议通信
|
||
|
||
**Core 客户端**:
|
||
1. TLS 握手
|
||
2. 认证（Token/mTLS）
|
||
3. 能力协商
|
||
4. 订阅事件
|
||
|
||
**Core 服务端**:
|
||
1. 监听端口
|
||
2. 接受连接
|
||
3. 验证客户端
|
||
4. 发送事件
|
||
|
||
**排查点**:
|
||
- ✅ Proto 定义一致性
|
||
- ✅ TLS 证书验证
|
||
- ✅ 消息序列化
|
||
- ✅ 错误处理
|
||
- ✅ 重连机制
|
||
|
||
---
|
||
|
||
## 🐛 重点排查问题清单
|
||
|
||
### P0 - 严重问题
|
||
1. **网络创建失败** - 雪花 ID、子网分配
|
||
2. **Peer 无法连接** - WG 配置、路由表
|
||
3. **STUN 打洞无效** - Endpoint 发现
|
||
4. **DDNS 更新失败** - API 调用、权限
|
||
|
||
### P1 - 重要问题
|
||
1. **备份恢复不完整** - 表遗漏、配置缺失
|
||
2. **通知推送延迟** - WebSocket 连接
|
||
3. **TURN 切换失败** - fallback 逻辑
|
||
4. **Core 连接断开** - 心跳、重连
|
||
|
||
### P2 - 次要问题
|
||
1. **UI 显示异常** - 数据格式化
|
||
2. **错误提示不清** - 错误包装
|
||
3. **性能问题** - 查询优化
|
||
4. **文档缺失** - API 注释
|
||
|
||
---
|
||
|
||
## 🔧 排查工具与方法
|
||
|
||
### 代码审查
|
||
- ✅ TODO/FIXME 标记
|
||
- ✅ 错误处理完整性
|
||
- ✅ 日志输出充分性
|
||
- ✅ 边界条件检查
|
||
|
||
### 运行时排查
|
||
- ✅ 编译检查
|
||
- ✅ 单元测试
|
||
- ✅ 集成测试
|
||
- ✅ 手动验证
|
||
|
||
### 数据验证
|
||
- ✅ 数据库约束
|
||
- ✅ 外键关系
|
||
- ✅ 索引效率
|
||
- ✅ 事务完整性
|
||
|
||
---
|
||
|
||
## 📊 预期输出
|
||
|
||
1. **问题清单** - 按优先级分类
|
||
2. **修复方案** - 具体代码修改
|
||
3. **验证结果** - 测试通过证明
|
||
4. **文档更新** - 使用说明完善
|
||
|
||
---
|
||
|
||
**开始时间**: 2026-03-20
|
||
**预计耗时**: 2-3 小时
|
||
**目标**: 零遗漏、零死角、全功能可用
|