Meshray-Manager/docs/DDNS_Usage 功能联调测试指南.md

DDNS Usage 功能 - 前后端联调测试指南

测试时间: 2026-03-26
服务状态: ✅ 已启动 http://localhost:9531

---

🎯 测试目标

验证 DDNS Usage 管理功能的前后端连通性和完整流程

---

📋 测试清单

阶段 1: 基础功能验证

1.1 登录系统

访问：http://localhost:9531
账户：admin
密码：admin123 (或你设置的密码)

预期结果:

• 成功登录
• 进入 Dashboard

---

1.2 配置 DDNS 服务（前提条件）

路径: 服务市场 → DNS 服务 → 添加服务

填写内容:

服务商：Cloudflare（或其他）
名称：公司主域名
记录类型：TXT
域名：mesh.example.com
API Token: cf_xxxxx (你的 Cloudflare Token)

预期结果:

• 保存成功
• 服务列表显示新配置的 DDNS 服务
• 状态正常（可达）

API 验证:

curl -X GET http://localhost:9531/api/v1/services?category=dns&type=ddns \
  -H "Authorization: Bearer YOUR_TOKEN"

---

阶段 2: 组网创建 - 自动生成模式

2.1 创建组网并启用 DDNS

路径: 组网管理 → 创建组网

步骤 1: 基础信息

组网名称：办公网络
虚拟 IPv4 网段：10.0.0.0/24
启用 DDNS 同步：✅ ON
DDNS 服务：选择刚才配置的 DDNS 服务
前缀模式：✨ 自动生成（默认）

预期结果:

• DDNS 服务下拉框正确加载
• 选择服务后显示域名信息
• 自动生成模式显示预览信息
• 预览格式：_meshray.{短 ID}.{域名}

步骤 2-4: 其他配置

按默认或自定义填写

步骤 5: 确认创建

预期结果:

• 创建成功提示
• 跳转到组网列表
• 新组网显示在列表中

---

2.2 验证数据库记录

API 验证:

# 查询组网详情
curl -X GET http://localhost:9531/api/v1/networks/{network_id} \
  -H "Authorization: Bearer YOUR_TOKEN"

# 期望看到 DDNS 相关字段
{
  "data": {
    "ddns_enabled": true,
    "ddns_service_id": "xxx",
    "ddns_usage_id": "xxx",
    "ddns_prefix": "EjRWeJyt5uU"  # Base64 编码的 ID
  }
}

数据库验证 (可选):

-- 查看 Network 表
SELECT id, name, ddns_enabled, ddns_service_id, ddns_usage_id, ddns_prefix 
FROM networks 
WHERE name = '办公网络';

-- 查看 DDNSUsage 表
SELECT id, provider_id, prefix_mode, record_prefix, description
FROM ddns_usages
WHERE record_prefix = 'EjRWeJyt5uU';

-- 查看绑定关系
SELECT * FROM network_ddns_bindings
WHERE network_id = {network_id};

预期结果:

• Network 表有 DDNS 字段数据
• DDNSUsage 表有对应记录
• PrefixMode = "auto"
• RecordPrefix = Base64 编码的网络 ID（约 11 字符）
• NetworkDDNSBinding 表有绑定关系

---

阶段 3: 组网创建 - 自定义模式

3.1 创建第二个组网

路径: 组网管理 → 创建组网

步骤 1: 基础信息

组网名称：测试环境
虚拟 IPv4 网段：10.0.1.0/24
启用 DDNS 同步：✅ ON
DDNS 服务：选择同一个 DDNS 服务
前缀模式：🔧 自定义
自定义前缀：test-env

预期结果:

• 输入前缀后自动检测（500ms 防抖）
• 如果前缀可用，显示绿色标签"该前缀可用"
• 如果前缀被占用，显示红色标签"该前缀已被占用"

测试冲突场景:

1. 输入已被占用的前缀（如第一个组网的前缀）
2. 观察实时检测结果
3. 修改为未使用的前缀
4. 确认可用后再提交

步骤 2-5: 完成创建

预期结果:

• 创建成功
• Database 中 RecordPrefix = "test-env"
• PrefixMode = "custom"

---

3.2 验证冲突检测

测试步骤:

1. 再次创建组网
2. 选择自定义模式
3. 输入已使用的前缀（如 "test-env"）
4. 等待 500ms

预期结果:

• 显示红色标签"该前缀已被占用"
• 无法提交（或提交时报错）

API 验证:

# 手动调用检测接口
curl -G "http://localhost:9531/api/v1/ddns/check-prefix" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --data-urlencode "service_id={service_id}" \
  --data-urlencode "prefix=test-env"

# 期望返回
{
  "data": {
    "occupied": true,
    "count": 1
  }
}

---

阶段 4: 获取可用 Usage 列表

4.1 API 测试

curl -G "http://localhost:9531/api/v1/ddns/usages/available" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --data-urlencode "service_id={service_id}"

期望返回:

{
  "data": [
    {
      "id": "usage_id_1",
      "provider_id": "service_id",
      "prefix_mode": "auto",
      "record_prefix": "EjRWeJyt5uU",
      "record_type": "TXT",
      "description": "MeshSeed 同步 - 办公网络",
      "is_occupied": true,
      "network_id": 123456789,
      "full_domain": "_meshray.EjRWeJyt5uU.mesh.example.com"
    },
    {
      "id": "usage_id_2",
      "prefix_mode": "custom",
      "record_prefix": "test-env",
      "is_occupied": true,
      "full_domain": "_meshray.test-env.mesh.example.com"
    }
  ]
}

验证点:

• 返回正确的 JSON 结构
• full_domain 格式正确
• is_occupied 标记正确
• prefix_mode 区分 auto/custom

---

阶段 5: MeshSeed 同步验证

5.1 分享组网时查看 DDNS 信息

路径: 组网管理 → 详情 → 分享 MeshSeed

预期结果:

• 显示 DDNS 同步开关
• 显示将同步到的完整域名
• 格式：_meshray.{前缀}.{域名}

---

5.2 手动触发同步（可选）

API 测试:

# 手动触发 DDNS 同步
curl -X POST http://localhost:9531/api/v1/ddns/sync \
  -H "Authorization: Bearer YOUR_TOKEN"

预期结果:

• 同步成功
• 日志显示同步到正确的域名
• DNS 记录包含加密的 MeshSeed

---

🔍 问题排查

问题 1: DDNS 服务列表为空

可能原因:

1. 未配置 DDNS 服务
2. API 路径错误
3. 鉴权失败

排查步骤:

# 1. 检查服务是否存在
curl -X GET http://localhost:9531/api/v1/services?category=dns&type=ddns \
  -H "Authorization: Bearer YOUR_TOKEN"

# 2. 查看浏览器控制台是否有错误
F12 → Console → 查看错误信息

# 3. 检查后端日志
查看终端输出的日志信息

---

问题 2: 前缀检测不工作

可能原因:

1. API 路径错误
2. 参数传递错误
3. 数据库表不存在

排查步骤:

# 1. 手动调用检测接口
curl -G "http://localhost:9531/api/v1/ddns/check-prefix" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --data-urlencode "service_id={service_id}" \
  --data-urlencode "prefix=test"

# 2. 检查数据库表结构
sqlite3 meshray.db ".schema ddns_usages"

# 3. 查看前端网络请求
F12 → Network → 查找 check-prefix 请求

---

问题 3: 创建组网失败

可能原因:

1. 事务处理错误
2. 外键约束冲突
3. 字段长度超限

排查步骤:

# 1. 查看后端日志
终端输出会显示详细错误信息

# 2. 检查数据库状态
sqlite3 meshray.db "SELECT * FROM networks ORDER BY id DESC LIMIT 1;"

# 3. 查看浏览器控制台
F12 → Console → 查看 JavaScript 错误

---

📊 测试结果记录表

测试项	预期结果	实际结果	状态	备注
DDNS 服务配置	保存成功		⬜
服务列表加载	显示已配置的服务		⬜
自动生成模式	显示预览		⬜
自定义模式检测	实时检测占用		⬜
创建组网（自动）	成功创建		⬜
创建组网（自定义）	成功创建		⬜
前缀冲突检测	正确识别占用		⬜
数据库记录	字段完整		⬜
Usage API	返回正确数据		⬜

---

✅ 验收标准

功能完整性

• 后端 API 全部实现
• 前端 UI 全部实现
• 前后端联调通过
• 完整流程无报错

数据正确性

• Network 表 DDNS 字段正确存储
• DDNSUsage 表 PrefixMode 正确标记
• RecordPrefix 格式正确（auto 为 Base64，custom 为用户输入）
• NetworkDDNSBinding 表绑定关系正确

用户体验

• DDNS 服务列表正确加载
• 自动生成模式有清晰预览
• 自定义模式实时检测（500ms 防抖）
• 占用状态直观显示（绿/红标签）
• 错误提示清晰明确

性能表现

• API 响应时间 < 200ms
• 前端操作流畅无卡顿
• 防抖机制正常工作

---

🚀 开始测试

服务已启动: http://localhost:9531

测试步骤:

1. 点击预览按钮打开浏览器
2. 登录系统（admin/admin123）
3. 按照上述测试清单逐项测试
4. 记录测试结果

发现问题:

• 如果发现任何 bug 或不一致，立即记录并修复
• 如果 API 报错，检查后端日志和前端 Network 面板
• 如果 UI 不显示，检查浏览器 Console 和后端日志

准备开始测试了吗？🎯