Meshray-Manager/docs/DDNS 双模式架构设计.md

# DDNS 双模式架构设计文档

## 📋 架构概述

DDNS（动态 DNS）在本系统中采用**双模式设计**，实现了配置与使用的完全解耦，支持两种不同的应用场景。

---

## 🎯 核心设计理念

### 1. 配置与使用分离
- **DDNS 配置**：仅存储 DNS 服务商的对接信息（基础设施）
- **DDNS 使用**：基于配置创建具体的 DNS 记录（应用层）

### 2. 双层架构
```
基础设施层（Tab 3: DDNS 配置）
└─ 配置 DNS 服务商信息
   ├─ 阿里云 DNS
   ├─ 腾讯云 DNSPod
   └─ Cloudflare

应用层（Tab 4: 增强 - DDNS 内网穿透）
└─ 基于配置创建完整服务
   ├─ A 记录（IPv4）
   ├─ AAAA 记录（IPv6）
   ├─ TXT 记录（文本）
   └─ CNAME 记录（别名）
```

---

## 🏗️ 两种配置模式详解

### 模式 A：基础设施配置 🏭

**使用场景**：组网同步 MeshSeed

**入口位置**：服务管理 → Tab 3 "DDNS"

**配置字段**：
| 字段 | 说明 | 示例 |
|------|------|------|
| DNS 服务商 | 选择云服务商 | Cloudflare / 阿里云 / 腾讯云 |
| 根域名 | 主域名 | example.com |
| API Token | Cloudflare API 令牌 | `cf_abc123...` |
| AccessKey ID | 阿里云访问密钥 | `LTAI5t...` |
| AccessKey Secret | 阿里云密钥 | `******` |
| SecretId | 腾讯云密钥 ID | `AKID...` |
| SecretKey | 腾讯云密钥 | `******` |

**特点**：
- ✅ 只配置服务商对接信息
- ✅ 不创建具体 DNS 记录
- ✅ 可在组网创建时直接选用
- ✅ 支持连通性测试

**使用流程**：
```
1. 在 Tab 3 配置 Cloudflare + example.com
2. 创建组网时 → 启用 DDNS 同步 → 选择上述配置
3. 系统自动创建 TXT 记录：_meshray.{短 ID}.example.com
4. 设备加入时读取 TXT 记录获取 MeshSeed
```

---

### 模式 B：全功能 DDNS 服务 🚀

**使用场景**：NAS 内网穿透、家庭服务器暴露、自定义 DNS 记录

**入口位置**：服务管理 → Tab 4 "增强" → DDNS 内网穿透

**配置字段**：
| 字段 | 说明 | 示例 |
|------|------|------|
| 选择 DDNS 配置 | 从已配置的服务商中选择 | Cloudflare (example.com) |
| 记录类型 | DNS 记录类型 | A / AAAA / TXT / CNAME |
| 主机记录 | 子域目前前缀 | nas, home, server |
| 目标 IP | IPv4/IPv6 地址 | 192.168.1.100 / ::ffff:192.168.1.100 |
| 检测端口 | 可达性检测端口 | 80, 443, 8080 |
| TXT 记录名称 | TXT 记录的键 | _meshray, verification-code |
| TXT 记录值 | TXT 记录的值 | 配置内容或验证信息 |
| TTL | DNS 缓存时间 | 600 (10 分钟) |

**特点**：
- ✅ 完整的 DNS 记录管理
- ✅ 支持多种记录类型
- ✅ 定时检测 IP 变化并自动更新
- ✅ 支持内网穿透等高级应用

**使用流程**：
```
前置条件：已在 Tab 3 配置 DDNS 服务商

1. 切换到 Tab 4 "增强"
2. 点击 "DDNS 内网穿透" 卡片
3. 选择已配置的 DDNS 服务商
4. 填写记录信息：
   - 记录类型：AAAA (IPv6)
   - 主机记录：nas
   - 目标 IP：::ffff:192.168.1.100
   - 检测端口：80
5. 系统开始工作：
   - 定时检测本地 IPv6 地址
   - 调用 DNS 服务商 API 更新记录
   - 用户可通过 nas.example.com 访问
```

---

## 🔄 两种模式对比

| 维度 | 基础设施配置 | 全功能服务 |
|------|-------------|-----------|
| **定位** | 基础设施层 | 应用层 |
| **用途** | 组网同步 | 内网穿透/自定义 |
| **入口** | Tab 3 "DDNS" | Tab 4 "增强" |
| **配置复杂度** | 简单（仅对接信息） | 复杂（完整记录） |
| **记录类型** | 无（由 Usage 定义） | A/AAAA/TXT/CNAME |
| **依赖关系** | 独立 | 依赖基础设施配置 |
| **典型场景** | MeshSeed 同步 | NAS 远程访问 |

---

## 📁 页面结构

```
服务管理（Service Management）
├── Tab 1: TUN - 虚拟网络接口配置
├── Tab 2: TURN - 中继服务配置
├── Tab 3: DDNS - 基础设施配置 ← 🏭
└── Tab 4: 增强 - 应用服务扩展 ← 🚀
    ├── DDNS 内网穿透
    └── 自定义服务（预留）
```

---

## 🔧 技术实现

### 前端关键代码

#### 1. 模式切换
```vue
<el-form-item label="配置模式" prop="config_mode">
  <el-radio-group v-model="formData.config_mode">
    <el-radio value="infrastructure">
      🏗️ 基础设施配置
      <span class="radio-desc">仅配置 DNS 服务商，用于组网同步等场景</span>
    </el-radio>
    <el-radio value="fullservice">
      🚀 全功能 DDNS 服务
      <span class="radio-desc">创建完整的 DDNS 记录，支持内网穿透等应用</span>
    </el-radio>
  </el-radio-group>
</el-form-item>
```

#### 2. 表单字段区分
```vue
<!-- 基础设施模式 -->
<template v-if="formData.config_mode === 'infrastructure'">
  <el-form-item label="DNS 服务商" prop="provider">
    <el-select v-model="formData.provider">
      <el-option label="阿里云 DNS" value="aliyun" />
      <el-option label="Cloudflare" value="cloudflare" />
    </el-select>
  </el-form-item>
  
  <el-form-item label="根域名" prop="domain">
    <el-input v-model="formData.domain" placeholder="example.com" />
  </el-form-item>
</template>

<!-- 全功能服务模式 -->
<template v-else-if="formData.config_mode === 'fullservice'">
  <el-form-item label="选择 DDNS 配置" prop="ddns_config_id">
    <el-select v-model="formData.ddns_config_id" filterable>
      <el-option
        v-for="config in ddnsConfigs"
        :key="config.id"
        :label="`${config.name} (${config.config?.domain})`"
        :value="config.id"
      />
    </el-select>
  </el-form-item>
  
  <el-form-item label="记录类型" prop="record_type">
    <el-select v-model="formData.record_type">
      <el-option label="A (IPv4)" value="A" />
      <el-option label="AAAA (IPv6)" value="AAAA" />
    </el-select>
  </el-form-item>
  
  <!-- 更多字段... -->
</template>
```

#### 3. 验证规则区分
```javascript
if (formData.value.type === 'DDNS') {
  if (formData.value.config_mode === 'infrastructure') {
    // 只校验服务商信息
    rules.provider = [{ required: true }]
    rules.domain = [{ required: true }]
  } else if (formData.value.config_mode === 'fullservice') {
    // 校验完整记录
    rules.ddns_config_id = [{ required: true }]
    rules.record_type = [{ required: true }]
    
    if (['A', 'AAAA'].includes(formData.value.record_type)) {
      rules.subdomain = [{ required: true }]
      rules.target_ip = [{ required: true, pattern: IP_REGEX }]
      rules.port = [{ required: true }]
    }
  }
}
```

---

## 💡 用户体验优化

### 1. 清晰的引导文案
- Tab 3 明确标注为"基础设施"
- 提示可在组网创建时直接选用
- 提示可在"增强"页创建完整服务

### 2. 智能的级联选择
- 全功能模式下，下拉框只显示已配置的 DDNS 服务商
- 未配置服务商时，提示用户先到 Tab 3 配置

### 3. 直观的视觉反馈
- 使用 Emoji 图标区分两种模式（🏗️ vs 🚀）
- 描述文字清晰说明用途差异
- 卡片式设计展示增强服务

---

## 🔮 未来扩展

Tab 4 "增强"页预留了扩展能力，未来可以添加：

1. **DDNS 高级应用**
   - 多记录联动（同时更新 A 和 AAAA）
   - 批量 DNS 记录管理
   - DNS 解析统计

2. **其他服务类型**
   - 反向代理配置
   - SSL 证书自动申请
   - 端口转发规则

3. **自动化场景**
   - 条件触发器（如：仅在检测到 IPv6 变化时更新）
   - Webhook 通知（更新后回调通知）

---

## 📝 总结

通过**双模式设计**，本系统实现了：

✅ **配置与使用解耦** - 基础设施与应用层分离  
✅ **灵活复用** - 一次配置，多处使用  
✅ **场景覆盖** - 同时支持组网同步和内网穿透  
✅ **易于扩展** - 增强页预留未来能力  

这种设计既保证了架构的清晰性，又提供了强大的功能性，为用户提供了最佳的使用体验。