18 KiB

Raw Permalink Blame History

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	否	描述

请求示例:

{
  "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 服务器"
}

响应示例:

{
  "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 获取全部（管理员）

请求示例:

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

响应示例:

{
  "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	否	描述

请求示例:

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

响应示例:

{
  "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 删除所有

请求示例:

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

响应示例:

{
  "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	否	描述

请求示例:

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

响应示例:

{
  "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 获取全部（管理员）

请求示例:

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

响应示例:

{
  "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	否	描述

请求示例:

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

响应示例:

{
  "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 删除所有

请求示例:

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

响应示例:

{
  "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 记录:

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

请求示例 - CNAME 记录:

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

请求示例 - MX 记录:

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

响应示例:

{
  "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 获取全部（管理员）

请求示例:

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

响应示例:

{
  "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	否	目标

请求示例:

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

响应示例:

{
  "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 删除所有

请求示例:

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

响应示例:

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

DNS 服务运行管理接口

13. 启动 DNS 服务器

接口路径: /dns/server/start

请求参数:

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

请求示例:

{
  "server_id": 1
}

响应示例:

{
  "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

请求示例:

{
  "server_id": 1
}

响应示例:

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

15. 重启 DNS 服务器

接口路径: /dns/server/restart

请求参数:

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

请求示例:

{
  "server_id": 1
}

响应示例:

{
  "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

请求示例:

{
  "server_id": 1
}

响应示例:

{
  "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等）被修改时，如果服务正在运行，系统会自动重启服务以应用新的配置。

18 KiB Raw Permalink Blame History Unescape Escape

DNS 管理 API 文档

概述

基础信息

常量定义

DNS 服务器状态

DNS 记录类型

DNS 服务器接口

1. 创建 DNS 服务器

2. 获取 DNS 服务器

3. 更新 DNS 服务器

4. 删除 DNS 服务器

DNS 区域接口

5. 创建 DNS 区域

6. 获取 DNS 区域

7. 更新 DNS 区域

8. 删除 DNS 区域

DNS 记录接口

9. 创建 DNS 记录

10. 获取 DNS 记录

11. 更新 DNS 记录

12. 删除 DNS 记录

DNS 服务运行管理接口

13. 启动 DNS 服务器

14. 停止 DNS 服务器

15. 重启 DNS 服务器

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

数据模型

DNSServer

DNSZone

DNSRecord

DNSServiceInstance

错误码说明

功能特性

基础功能

运行时管理

权限说明

自动重启特性

18 KiB

Raw Permalink Blame History