408 lines
8.9 KiB
Markdown
408 lines
8.9 KiB
Markdown
# 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 验证**:
|
||
```bash
|
||
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 验证**:
|
||
```bash
|
||
# 查询组网详情
|
||
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
|
||
}
|
||
}
|
||
```
|
||
|
||
**数据库验证** (可选):
|
||
```sql
|
||
-- 查看 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 验证**:
|
||
```bash
|
||
# 手动调用检测接口
|
||
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 测试
|
||
|
||
```bash
|
||
curl -G "http://localhost:9531/api/v1/ddns/usages/available" \
|
||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||
--data-urlencode "service_id={service_id}"
|
||
```
|
||
|
||
**期望返回**:
|
||
```json
|
||
{
|
||
"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 测试**:
|
||
```bash
|
||
# 手动触发 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. 鉴权失败
|
||
|
||
**排查步骤**:
|
||
```bash
|
||
# 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. 数据库表不存在
|
||
|
||
**排查步骤**:
|
||
```bash
|
||
# 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. 字段长度超限
|
||
|
||
**排查步骤**:
|
||
```bash
|
||
# 1. 查看后端日志
|
||
终端输出会显示详细错误信息
|
||
|
||
# 2. 检查数据库状态
|
||
sqlite3 meshray.db "SELECT * FROM networks ORDER BY id DESC LIMIT 1;"
|
||
|
||
# 3. 查看浏览器控制台
|
||
F12 → Console → 查看 JavaScript 错误
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 测试结果记录表
|
||
|
||
| 测试项 | 预期结果 | 实际结果 | 状态 | 备注 |
|
||
|--------|----------|----------|------|------|
|
||
| DDNS 服务配置 | 保存成功 | | ⬜ | |
|
||
| 服务列表加载 | 显示已配置的服务 | | ⬜ | |
|
||
| 自动生成模式 | 显示预览 | | ⬜ | |
|
||
| 自定义模式检测 | 实时检测占用 | | ⬜ | |
|
||
| 创建组网（自动） | 成功创建 | | ⬜ | |
|
||
| 创建组网（自定义） | 成功创建 | | ⬜ | |
|
||
| 前缀冲突检测 | 正确识别占用 | | ⬜ | |
|
||
| 数据库记录 | 字段完整 | | ⬜ | |
|
||
| Usage API | 返回正确数据 | | ⬜ | |
|
||
|
||
---
|
||
|
||
## ✅ 验收标准
|
||
|
||
### **功能完整性**
|
||
- [x] 后端 API 全部实现
|
||
- [x] 前端 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 和后端日志
|
||
|
||
准备开始测试了吗？🎯
|