Meshray-Manager/docs/全功能遍历与问题排查计划.md

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 小时
目标: 零遗漏、零死角、全功能可用