ljydlv
/
video_ca
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
video_ca/dns.md

874 lines
18 KiB
Markdown
Raw Permalink Normal View History

添加DNS接口
2026-05-02 15:09:58 +08:00
# 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等）被修改时，如果服务正在运行，系统会自动重启服务以应用新的配置。