# DNS 管理 API 文档

## 概述

本文档描述了 DNS 管理系统的 API 接口，包括 DNS 服务器、DNS 区域和 DNS 记录的增删改查操作。

## 基础信息

- 基础路径: `/dns`
- 请求方法: POST
- 认证: 需要在请求头中携带认证 token

## 常量定义

### DNS 服务器状态

| 值 | 说明 |
|----|------|
| 0 | 已停止 |
| 1 | 运行中 |
| 2 | 错误 |

### DNS 记录类型

| 值 | 类型 | 说明 |
|----|------|------|
| 1 | A | IPv4 地址记录 |
| 28 | AAAA | IPv6 地址记录 |
| 5 | CNAME | 别名记录 |
| 15 | MX | 邮件交换记录 |
| 2 | NS | 名称服务器记录 |
| 6 | SOA | 起始授权记录 |
| 16 | TXT | 文本记录 |
| 33 | SRV | 服务位置记录 |

## DNS 服务器接口

### 1. 创建 DNS 服务器

**接口路径**: `/dns/server/create`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | DNS 服务器名称 |
| port | uint | 否 | 监听端口，默认 53 |
| listen_ip | string | 否 | 监听 IP，默认 0.0.0.0 |
| upstream_dns | string | 否 | 上游 DNS 服务器，多个用逗号分隔 |
| enable_recursion | bool | 否 | 是否启用递归查询 |
| description | string | 否 | 描述 |

**请求示例**:

```json
{
  "name": "我的 DNS 服务器",
  "port": 53,
  "listen_ip": "0.0.0.0",
  "upstream_dns": "8.8.8.8,8.8.4.4",
  "enable_recursion": true,
  "description": "个人 DNS 服务器"
}
```

**响应示例**:

```json
{
  "code": 0,
  "message": "创建DNS服务器成功",
  "data": {
    "ID": 1,
    "CreatedAt": "2024-01-01T00:00:00Z",
    "UpdatedAt": "2024-01-01T00:00:00Z",
    "DeletedAt": null,
    "user_id": 1,
    "name": "我的 DNS 服务器",
    "port": 53,
    "listen_ip": "0.0.0.0",
    "upstream_dns": "8.8.8.8,8.8.4.4",
    "enable_recursion": true,
    "status": 0,
    "description": "个人 DNS 服务器"
  }
}
```

### 2. 获取 DNS 服务器

**接口路径**: `/dns/server/get`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| server_id | uint | 否 | DNS 服务器 ID，0 表示获取全部 |
| get_type | int | 否 | 获取类型：0 获取自己的，1 获取全部（管理员） |

**请求示例**:

```json
{
  "server_id": 1,
  "get_type": 0
}
```

**响应示例**:

```json
{
  "code": 0,
  "message": "获取DNS服务器成功",
  "data": [
    {
      "ID": 1,
      "CreatedAt": "2024-01-01T00:00:00Z",
      "UpdatedAt": "2024-01-01T00:00:00Z",
      "DeletedAt": null,
      "user_id": 1,
      "name": "我的 DNS 服务器",
      "port": 53,
      "listen_ip": "0.0.0.0",
      "upstream_dns": "8.8.8.8,8.8.4.4",
      "enable_recursion": true,
      "status": 0,
      "description": "个人 DNS 服务器"
    }
  ]
}
```

### 3. 更新 DNS 服务器

**接口路径**: `/dns/server/update`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| server_id | uint | 是 | DNS 服务器 ID |
| name | string | 否 | DNS 服务器名称 |
| port | uint | 否 | 监听端口 |
| listen_ip | string | 否 | 监听 IP |
| upstream_dns | string | 否 | 上游 DNS 服务器 |
| enable_recursion | bool | 否 | 是否启用递归查询 |
| status | uint | 否 | 状态：0 停止，1 运行中，2 错误 |
| description | string | 否 | 描述 |

**请求示例**:

```json
{
  "server_id": 1,
  "name": "更新后的 DNS 服务器",
  "status": 1
}
```

**响应示例**:

```json
{
  "code": 0,
  "message": "更新DNS服务器成功",
  "data": {
    "ID": 1,
    "CreatedAt": "2024-01-01T00:00:00Z",
    "UpdatedAt": "2024-01-01T01:00:00Z",
    "DeletedAt": null,
    "user_id": 1,
    "name": "更新后的 DNS 服务器",
    "port": 53,
    "listen_ip": "0.0.0.0",
    "upstream_dns": "8.8.8.8,8.8.4.4",
    "enable_recursion": true,
    "status": 1,
    "description": "个人 DNS 服务器"
  }
}
```

### 4. 删除 DNS 服务器

**接口路径**: `/dns/server/delete`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| server_id | uint | 否 | DNS 服务器 ID |
| del_type | uint | 是 | 删除类型：0 删除单条，1 删除所有 |

**请求示例**:

```json
{
  "server_id": 1,
  "del_type": 0
}
```

**响应示例**:

```json
{
  "code": 0,
  "message": "删除DNS服务器成功"
}
```

## DNS 区域接口

### 5. 创建 DNS 区域

**接口路径**: `/dns/zone/create`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| server_id | uint | 是 | 所属 DNS 服务器 ID |
| domain | string | 是 | 域名，如 example.com |
| soa_mname | string | 否 | SOA 记录的主域名服务器 |
| soa_rname | string | 否 | SOA 记录的管理员邮箱 |
| soa_serial | uint | 否 | SOA 记录的序列号，默认 1 |
| soa_refresh | uint | 否 | SOA 记录的刷新时间（秒），默认 86400 |
| soa_retry | uint | 否 | SOA 记录的重试时间（秒），默认 7200 |
| soa_expire | uint | 否 | SOA 记录的过期时间（秒），默认 3600000 |
| soa_minimum | uint | 否 | SOA 记录的最小 TTL（秒），默认 3600 |
| ttl | uint | 否 | 默认 TTL（秒），默认 3600 |
| description | string | 否 | 描述 |

**请求示例**:

```json
{
  "server_id": 1,
  "domain": "example.com",
  "soa_mname": "ns1.example.com",
  "soa_rname": "admin.example.com",
  "description": "示例域名"
}
```

**响应示例**:

```json
{
  "code": 0,
  "message": "创建DNS区域成功",
  "data": {
    "ID": 1,
    "CreatedAt": "2024-01-01T00:00:00Z",
    "UpdatedAt": "2024-01-01T00:00:00Z",
    "DeletedAt": null,
    "server_id": 1,
    "domain": "example.com",
    "soa_mname": "ns1.example.com",
    "soa_rname": "admin.example.com",
    "soa_serial": 1,
    "soa_refresh": 86400,
    "soa_retry": 7200,
    "soa_expire": 3600000,
    "soa_minimum": 3600,
    "ttl": 3600,
    "description": "示例域名"
  }
}
```

### 6. 获取 DNS 区域

**接口路径**: `/dns/zone/get`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| zone_id | uint | 否 | Zone ID，0 表示获取全部 |
| server_id | uint | 否 | DNS 服务器 ID，用于过滤 |
| get_type | int | 否 | 获取类型：0 获取自己的，1 获取全部（管理员） |

**请求示例**:

```json
{
  "zone_id": 1,
  "get_type": 0
}
```

**响应示例**:

```json
{
  "code": 0,
  "message": "获取DNS区域成功",
  "data": [
    {
      "ID": 1,
      "CreatedAt": "2024-01-01T00:00:00Z",
      "UpdatedAt": "2024-01-01T00:00:00Z",
      "DeletedAt": null,
      "server_id": 1,
      "domain": "example.com",
      "soa_mname": "ns1.example.com",
      "soa_rname": "admin.example.com",
      "soa_serial": 1,
      "soa_refresh": 86400,
      "soa_retry": 7200,
      "soa_expire": 3600000,
      "soa_minimum": 3600,
      "ttl": 3600,
      "description": "示例域名"
    }
  ]
}
```

### 7. 更新 DNS 区域

**接口路径**: `/dns/zone/update`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| zone_id | uint | 是 | Zone ID |
| domain | string | 否 | 域名 |
| soa_mname | string | 否 | SOA 记录的主域名服务器 |
| soa_rname | string | 否 | SOA 记录的管理员邮箱 |
| soa_serial | uint | 否 | SOA 记录的序列号 |
| soa_refresh | uint | 否 | SOA 记录的刷新时间（秒） |
| soa_retry | uint | 否 | SOA 记录的重试时间（秒） |
| soa_expire | uint | 否 | SOA 记录的过期时间（秒） |
| soa_minimum | uint | 否 | SOA 记录的最小 TTL（秒） |
| ttl | uint | 否 | 默认 TTL（秒） |
| description | string | 否 | 描述 |

**请求示例**:

```json
{
  "zone_id": 1,
  "description": "更新后的描述"
}
```

**响应示例**:

```json
{
  "code": 0,
  "message": "更新DNS区域成功",
  "data": {
    "ID": 1,
    "CreatedAt": "2024-01-01T00:00:00Z",
    "UpdatedAt": "2024-01-01T01:00:00Z",
    "DeletedAt": null,
    "server_id": 1,
    "domain": "example.com",
    "soa_mname": "ns1.example.com",
    "soa_rname": "admin.example.com",
    "soa_serial": 1,
    "soa_refresh": 86400,
    "soa_retry": 7200,
    "soa_expire": 3600000,
    "soa_minimum": 3600,
    "ttl": 3600,
    "description": "更新后的描述"
  }
}
```

### 8. 删除 DNS 区域

**接口路径**: `/dns/zone/delete`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| zone_id | uint | 否 | Zone ID |
| del_type | uint | 是 | 删除类型：0 删除单条，1 删除所有 |

**请求示例**:

```json
{
  "zone_id": 1,
  "del_type": 0
}
```

**响应示例**:

```json
{
  "code": 0,
  "message": "删除DNS区域成功"
}
```

## DNS 记录接口

### 9. 创建 DNS 记录

**接口路径**: `/dns/record/create`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| zone_id | uint | 是 | 所属 Zone ID |
| name | string | 是 | 记录名称，如 www 或 @ |
| type | uint | 是 | 记录类型：1=A, 28=AAAA, 5=CNAME, 15=MX 等 |
| value | string | 否 | 记录值 |
| ttl | uint | 否 | TTL（秒），如果为 0 则使用 Zone 的默认 TTL |
| priority | uint | 否 | 优先级（用于 MX、SRV 等记录） |
| weight | uint | 否 | 权重（用于 SRV 记录） |
| port | uint | 否 | 端口（用于 SRV 记录） |
| target | string | 否 | 目标（用于 SRV 记录） |

**请求示例 - A 记录**:

```json
{
  "zone_id": 1,
  "name": "www",
  "type": 1,
  "value": "192.168.1.1",
  "ttl": 3600
}
```

**请求示例 - CNAME 记录**:

```json
{
  "zone_id": 1,
  "name": "mail",
  "type": 5,
  "value": "mailserver.example.com",
  "ttl": 3600
}
```

**请求示例 - MX 记录**:

```json
{
  "zone_id": 1,
  "name": "@",
  "type": 15,
  "value": "mx1.example.com",
  "ttl": 3600,
  "priority": 10
}
```

**响应示例**:

```json
{
  "code": 0,
  "message": "创建DNS记录成功",
  "data": {
    "ID": 1,
    "CreatedAt": "2024-01-01T00:00:00Z",
    "UpdatedAt": "2024-01-01T00:00:00Z",
    "DeletedAt": null,
    "zone_id": 1,
    "name": "www",
    "type": 1,
    "value": "192.168.1.1",
    "ttl": 3600,
    "priority": 0,
    "weight": 0,
    "port": 0,
    "target": ""
  }
}
```

### 10. 获取 DNS 记录

**接口路径**: `/dns/record/get`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| record_id | uint | 否 | 记录 ID，0 表示获取全部 |
| zone_id | uint | 否 | Zone ID，用于过滤 |
| get_type | int | 否 | 获取类型：0 获取自己的，1 获取全部（管理员） |

**请求示例**:

```json
{
  "record_id": 1,
  "get_type": 0
}
```

**响应示例**:

```json
{
  "code": 0,
  "message": "获取DNS记录成功",
  "data": [
    {
      "ID": 1,
      "CreatedAt": "2024-01-01T00:00:00Z",
      "UpdatedAt": "2024-01-01T00:00:00Z",
      "DeletedAt": null,
      "zone_id": 1,
      "name": "www",
      "type": 1,
      "value": "192.168.1.1",
      "ttl": 3600,
      "priority": 0,
      "weight": 0,
      "port": 0,
      "target": ""
    }
  ]
}
```

### 11. 更新 DNS 记录

**接口路径**: `/dns/record/update`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| record_id | uint | 是 | 记录 ID |
| name | string | 否 | 记录名称 |
| type | uint | 否 | 记录类型 |
| value | string | 否 | 记录值 |
| ttl | uint | 否 | TTL（秒） |
| priority | uint | 否 | 优先级 |
| weight | uint | 否 | 权重 |
| port | uint | 否 | 端口 |
| target | string | 否 | 目标 |

**请求示例**:

```json
{
  "record_id": 1,
  "value": "192.168.1.2"
}
```

**响应示例**:

```json
{
  "code": 0,
  "message": "更新DNS记录成功",
  "data": {
    "ID": 1,
    "CreatedAt": "2024-01-01T00:00:00Z",
    "UpdatedAt": "2024-01-01T01:00:00Z",
    "DeletedAt": null,
    "zone_id": 1,
    "name": "www",
    "type": 1,
    "value": "192.168.1.2",
    "ttl": 3600,
    "priority": 0,
    "weight": 0,
    "port": 0,
    "target": ""
  }
}
```

### 12. 删除 DNS 记录

**接口路径**: `/dns/record/delete`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| record_id | uint | 否 | 记录 ID |
| del_type | uint | 是 | 删除类型：0 删除单条，1 删除所有 |

**请求示例**:

```json
{
  "record_id": 1,
  "del_type": 0
}
```

**响应示例**:

```json
{
  "code": 0,
  "message": "删除DNS记录成功"
}
```

## DNS 服务运行管理接口

### 13. 启动 DNS 服务器

**接口路径**: `/dns/server/start`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| server_id | uint | 是 | DNS 服务器 ID |

**请求示例**:

```json
{
  "server_id": 1
}
```

**响应示例**:

```json
{
  "code": 0,
  "message": "启动DNS服务器成功",
  "data": {
    "server_id": 1,
    "config": {
      "ID": 1,
      "CreatedAt": "2024-01-01T00:00:00Z",
      "UpdatedAt": "2024-01-01T00:00:00Z",
      "DeletedAt": null,
      "user_id": 1,
      "name": "我的 DNS 服务器",
      "port": 53,
      "listen_ip": "0.0.0.0",
      "upstream_dns": "8.8.8.8,8.8.4.4",
      "enable_recursion": true,
      "status": 1,
      "description": "个人 DNS 服务器"
    },
    "running": true
  }
}
```

### 14. 停止 DNS 服务器

**接口路径**: `/dns/server/stop`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| server_id | uint | 是 | DNS 服务器 ID |

**请求示例**:

```json
{
  "server_id": 1
}
```

**响应示例**:

```json
{
  "code": 0,
  "message": "停止DNS服务器成功"
}
```

### 15. 重启 DNS 服务器

**接口路径**: `/dns/server/restart`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| server_id | uint | 是 | DNS 服务器 ID |

**请求示例**:

```json
{
  "server_id": 1
}
```

**响应示例**:

```json
{
  "code": 0,
  "message": "重启DNS服务器成功",
  "data": {
    "server_id": 1,
    "config": {
      "ID": 1,
      "CreatedAt": "2024-01-01T00:00:00Z",
      "UpdatedAt": "2024-01-01T00:00:00Z",
      "DeletedAt": null,
      "user_id": 1,
      "name": "我的 DNS 服务器",
      "port": 53,
      "listen_ip": "0.0.0.0",
      "upstream_dns": "8.8.8.8,8.8.4.4",
      "enable_recursion": true,
      "status": 1,
      "description": "个人 DNS 服务器"
    },
    "running": true
  }
}
```

### 16. 获取 DNS 服务器运行状态

**接口路径**: `/dns/server/status`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| server_id | uint | 是 | DNS 服务器 ID |

**请求示例**:

```json
{
  "server_id": 1
}
```

**响应示例**:

```json
{
  "code": 0,
  "message": "获取DNS服务器状态成功",
  "data": {
    "server_id": 1,
    "config": {
      "ID": 1,
      "CreatedAt": "2024-01-01T00:00:00Z",
      "UpdatedAt": "2024-01-01T00:00:00Z",
      "DeletedAt": null,
      "user_id": 1,
      "name": "我的 DNS 服务器",
      "port": 53,
      "listen_ip": "0.0.0.0",
      "upstream_dns": "8.8.8.8,8.8.4.4",
      "enable_recursion": true,
      "status": 1,
      "description": "个人 DNS 服务器"
    },
    "running": true
  }
}
```

## 数据模型

### DNSServer

| 字段 | 类型 | 说明 |
|------|------|------|
| ID | uint | 主键 ID |
| CreatedAt | time.Time | 创建时间 |
| UpdatedAt | time.Time | 更新时间 |
| DeletedAt | *time.Time | 删除时间 |
| user_id | uint | 用户 ID |
| name | string | DNS 服务器名称 |
| port | uint | 监听端口 |
| listen_ip | string | 监听 IP |
| upstream_dns | string | 上游 DNS 服务器 |
| enable_recursion | bool | 是否启用递归查询 |
| status | uint | 状态：0 停止，1 运行中，2 错误 |
| description | string | 描述 |

### DNSZone

| 字段 | 类型 | 说明 |
|------|------|------|
| ID | uint | 主键 ID |
| CreatedAt | time.Time | 创建时间 |
| UpdatedAt | time.Time | 更新时间 |
| DeletedAt | *time.Time | 删除时间 |
| server_id | uint | 所属 DNS 服务器 ID |
| domain | string | 域名 |
| soa_mname | string | SOA 记录的主域名服务器 |
| soa_rname | string | SOA 记录的管理员邮箱 |
| soa_serial | uint | SOA 记录的序列号 |
| soa_refresh | uint | SOA 记录的刷新时间（秒） |
| soa_retry | uint | SOA 记录的重试时间（秒） |
| soa_expire | uint | SOA 记录的过期时间（秒） |
| soa_minimum | uint | SOA 记录的最小 TTL（秒） |
| ttl | uint | 默认 TTL（秒） |
| description | string | 描述 |

### DNSRecord

| 字段 | 类型 | 说明 |
|------|------|------|
| ID | uint | 主键 ID |
| CreatedAt | time.Time | 创建时间 |
| UpdatedAt | time.Time | 更新时间 |
| DeletedAt | *time.Time | 删除时间 |
| zone_id | uint | 所属 Zone ID |
| name | string | 记录名称 |
| type | uint | 记录类型 |
| value | string | 记录值 |
| ttl | uint | TTL（秒） |
| priority | uint | 优先级 |
| weight | uint | 权重 |
| port | uint | 端口 |
| target | string | 目标 |

### DNSServiceInstance

| 字段 | 类型 | 说明 |
|------|------|------|
| server_id | uint | DNS 服务器 ID |
| config | DNSServer | DNS 服务器配置 |
| running | bool | 是否正在运行 |

## 错误码说明

| 错误码 | 说明 |
|--------|------|
| 0 | 成功 |
| 1 | 参数错误 |
| 2 | 系统错误 |

## 功能特性

### 基础功能
- 支持多 DNS 服务器实例管理
- 每个 DNS 服务器可以管理多个域名区域（Zone）
- 每个域名区域可以添加多条 DNS 记录
- 支持常见 DNS 记录类型：A、AAAA、CNAME、MX、NS、TXT、SRV、SOA
- 完整的 SOA 记录配置

### 运行时管理
- 支持 DNS 服务的启动、停止、重启操作
- 同时支持 UDP 和 TCP 协议
- 配置修改后自动重启运行中的服务
- 实时获取服务运行状态
- 支持递归查询，可配置上游 DNS 服务器

### 权限说明
- 普通用户只能操作自己创建的 DNS 服务器、区域和记录
- 管理员可以操作所有 DNS 服务器、区域和记录
- 删除操作会级联删除相关的子资源（删除服务器会删除其下的区域，删除区域会删除其下的记录）

### 自动重启特性
当 DNS 服务器的配置（端口、监听IP、上游DNS等）被修改时，如果服务正在运行，系统会自动重启服务以应用新的配置。