zkcoi/Meshray-Manager

Fork 0

Files

T

zkcoi 15dab96872 Initial commit

2026-06-30 15:14:37 +08:00

7.0 KiB

Raw Blame History

MeshRay 全功能遍历与问题排查报告 - Phase 1

📋 遍历范围

时间: 2026-03-20
方法: 从用户视角出发，沿着实际使用流程
覆盖: 前端页面 → API 接口 → 业务逻辑 → 数据库 → Core 层

✅ 已验证的正常功能

1. 用户认证流程

✅ 登录页面 (/login)
- 表单验证完整（用户名、密码规则）
- UI 交互正常（loading 状态、错误提示）
- 首次登录提示友好
✅ Auth Store
- Token 存储到 localStorage
- UserInfo 管理
- 登出功能
⚠️ Token 刷新 (待修复)
- 后端 API 已实现：POST /api/v1/auth/refresh
- 前端未调用刷新逻辑
- 影响: Token 过期后用户体验不佳

2. Dashboard 首页

✅ 统计卡片
- 网络数量、设备总数统计
- 在线/离线设备显示
✅ 系统监控
- CPU 使用率仪表盘
- 内存使用率
- 系统负载
✅ WebSocket 实时推送
- 监听 Core 状态更新
- 流量统计实时更新
- fallback 次数显示

3. 网络创建流程

✅ 创建网络页面 (/networks/create)
- 步骤条清晰（4 步）
- 基础信息配置
- 模式选择（原生/增强）
- DDNS 同步配置
✅ 表单验证
- 网段格式检查
- 前缀可用性检测
- 必填项验证
✅ 后端 API
- POST /api/v1/networks
- NetworkHandler.CreateNetwork
- NetworkService.CreateNetwork
✅ 雪花 ID 生成
- uint64 处理正确
- ID 唯一性保证
✅ 子网分配
- validateSubnet 验证
- 冲突检测

4. 网络列表与详情

✅ 网络列表 (/networks)
- List.vue 存在
✅ 网络详情 (/networks/:id)
- Detail.vue 存在
- Peer 管理
- 配置修改

5. Ctr 集成

✅ CtrClient 调用
- CreateNetwork 时调用 ctr
- 失败降级处理（宽松模式）
- 日志记录完整

🐛 发现的问题清单

P1 - 重要问题

问题 1: Token 刷新功能未实现

位置: web/src/store/auth.js
现象:

// 第 78 行注释了刷新逻辑
// TODO: 实现后端 API：POST /api/v1/auth/refresh
// const res = await refreshToken(this.refreshToken)

影响:

Token 过期后用户需要重新登录
无法实现无感知刷新
用户体验差

修复方案:

async refreshAccessToken() {
  if (!this.refreshToken) {
    this.logout()
    return Promise.reject(new Error('Refresh token 不存在'))
  }
  
  try {
    const res = await refreshToken(this.refreshToken)
    this.token = res.data.access_token
    this.refreshToken = res.data.refresh_token
    localStorage.setItem('token', this.token)
    localStorage.setItem('refreshToken', this.refreshToken)
  } catch (error) {
    console.error('刷新 Token 失败:', error)
    this.logout()
    throw error
  }
}

并在 main.js 或 axios 拦截器中自动调用。

P2 - 次要问题

问题 2: DDNS Provider 配置页面缺失

位置: web/src/views/Service/
现象:

DDNS Provider 管理只有 List 和 Pending 页面
缺少创建/编辑 Provider 的表单页面
用户无法添加新的 DDNS 服务

影响:

只能使用预配置的 Provider
无法自定义阿里云/腾讯云 DNS
DDNS 功能不完整

建议: 创建 ProviderCreate.vue 和 ProviderEdit.vue

问题 3: STUN/TURN 配置页面可能缺失

位置: web/src/views/Settings/
现象:

Settings 目录只有 1 个文件
STUN/TURN服务器配置是核心功能
应该有独立的管理页面

排查: 需要检查 Settings/index.vue 是否包含 STUN/TURN 配置

P3 - 优化建议

优化 1: 错误提示不够友好

位置: 多处 API 调用
现象:

ElMessage.error('创建失败：' + (error.response?.data?.error || error.message))

建议:

统一错误处理中间件
错误代码映射到友好提示
提供解决方案链接

优化 2: 加载状态不一致

位置: 各页面
现象:

有些页面用 loading.value = true
有些用 v-loading 指令
缺少统一的 Loading 组件

建议:

封装统一的 Loading 组件
全局请求拦截器处理
避免重复点击

优化 3: 表单验证规则重复

位置: Create.vue, Detail.vue
现象:

每个组件都定义自己的 rules
相同的验证逻辑重复出现
难以维护

建议:

抽取公共验证规则
使用 mixin 或 composition API
集中管理验证规则

🔍 深度排查结果

数据库表完整性

✅ Network 表

ID (uint64,雪花算法)
Name (varchar)
SubnetIPv4 (varchar)
Mode (varchar)
CreatedAt/UpdatedAt

✅ Device/Peer表

关联 network_id
公钥/私钥
IP 地址

⚠️ 待检查:

NetworkDDNSBinding 表数据一致性
STUNServer/TURNServer 表是否有数据

Core 协议层排查

✅ Proto 定义

core.pb.go 存在
消息序列化正常

✅ Core Client

CtrClient 调用正常
CreateNetwork 时调用

⚠️ 待验证:

Core 服务端监听端口
TLS 证书配置
客户端认证逻辑

WireGuard 设备管理

✅ 用户态模式

wg.go 实现完整
AddPeer/RemovePeer
TUN 设备创建

✅ 内核态模式

配置文件生成
wintun.dll 检查