DNS 管理 API

概述

DNS API全面管理DNS区和记录,所有区都设在VPS.org名权威命名器上,自动生成和部署BIND9区文件。

命名器基础设施

ns1.vps.org (38.248.6.195) - DNSSEC内签有DNSSEC内联号的初级硕士
ns2.vps.org (38.248.6.196) - 二级奴隶
ns3.vps.org (38.248.6.197) - 二级奴隶

密钥特征

BIND9区文件的自动生成和部署
通过TSIG认证(技术奴役复制)进行区转让
支持所有主要的DNS记录类型(A、AAAA、CNAME、MX、TXT、NS、SRV、CAA)
域名过滤和UUUID区识别
具体区记录管理连接通道

验证

所有 DNS API 请求都需要贝尔代号验证。从您的账户仪表板上生成 API 代号 /account/developers/ 具有下列权限:

dns:list - 查看 DNS 区和记录
dns:create - 创建新区和记录
dns:update - 修改现有区和记录
dns:delete - 删除区和记录
dns:* - DNS 管理访问

示例示例示例示例

Authorization: Bearer vps_abc123def456...

重要: 创建时只显示一次 API 符号。安全保存它们。如果您失去了一个标记, 您必须生成一个新的标记。

得到 /api/v1/dns-zones/

列出所有 DNS 区域

获取已认证用户拥有的所有 DNS 区域列表。支持按域名过滤。

查询参数

参数	类型	必需的	说明说明
`domain`	string	否无	Filter zones by exact domain name (e.g., `example.com`)

示例请求

cURL

Python

JavaScript

curl -X GET "https://admin.vps.org/api/v1/dns-zones/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

import requests

url = "https://admin.vps.org/api/v1/dns-zones/"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

response = requests.get(url, headers=headers)
print(response.json())

const response = await fetch('https://admin.vps.org/api/v1/dns-zones/', {
  headers: {'Authorization': 'Bearer YOUR_API_TOKEN'}
});

const zones = await response.json();
console.log(zones);

示例回复

[
  {
    "uuid": "abc123-def456-ghi789",
    "domain": "example.com",
    "created_at": "2024-01-15T10:30:00Z",
    "record_count": 12
  },
  {
    "uuid": "xyz789-uvw456-rst123",
    "domain": "myapp.io",
    "created_at": "2024-06-20T14:15:00Z",
    "record_count": 8
  }
]

响应字段

外地	类型	说明说明
`uuid`	string	Unique zone identifier (used in API requests)
`domain`	string	Domain name for this DNS zone
`created_at`	datetime	Zone creation timestamp (ISO 8601 format)
`record_count`	integer	Total number of DNS records in this zone

响应状态码

200	Successfully retrieved DNS zones list
401	Unauthorized - Invalid or missing API token
403	Forbidden - Token lacks `dns:list` permission

得到 /api/v1/dns-zones/{uuid}/

获取 DNS 区细节

获取关于特定 DNS 区的详细信息,包括所有记录。

路径参数

参数	类型	必需的	说明说明
`uuid`	string	是的	Unique zone identifier

示例回复

{
  "uuid": "abc123-def456-ghi789",
  "domain": "example.com",
  "created_at": "2024-01-15T10:30:00Z",
  "record_count": 5,
  "records": [
    {
      "uuid": "rec-001",
      "record_type": "A",
      "name": "@",
      "value": "192.0.2.1",
      "ttl": 3600,
      "priority": null,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "uuid": "rec-002",
      "record_type": "MX",
      "name": "@",
      "value": "mail.example.com",
      "ttl": 3600,
      "priority": 10,
      "created_at": "2024-01-15T10:32:00Z"
    }
  ]
}

响应状态码

200	Successfully retrieved zone details
404	Zone not found or not owned by user

邮 /api/v1/dns-zones/

创建 DNS 区

为域创建新的 DNS 区。区将被立即部署到 VPS.org 名命名器。

请求体参数

参数	类型	必需的	说明说明
`domain`	string	是的	Domain name (e.g., `example.com`)

示例请求

cURL

Python

JavaScript

curl -X POST "https://admin.vps.org/api/v1/dns-zones/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain": "newdomain.com"}'

import requests

url = "https://admin.vps.org/api/v1/dns-zones/"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
data = {"domain": "newdomain.com"}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const response = await fetch('https://admin.vps.org/api/v1/dns-zones/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({domain: 'newdomain.com'})
});

const zone = await response.json();
console.log(zone);

示例回复

{
  "uuid": "new-zone-uuid",
  "domain": "newdomain.com",
  "created_at": "2026-01-18T16:45:00Z",
  "record_count": 0,
  "records": []
}

响应状态码

201	DNS zone created successfully
400	Bad Request - Invalid domain name or zone already exists
403	Forbidden - Token lacks `dns:create` permission

删除 /api/v1/dns-zones/{uuid}/

删除 DNS 区

永久删除 DNS 区和所有相关记录。此动作无法撤销。

路径参数

参数	类型	必需的	说明说明
`uuid`	string	是的	Unique zone identifier

响应状态码

204	Zone deleted successfully (no response body)
403	Forbidden - Token lacks `dns:delete` permission
404	Zone not found

得到 /api/v1/dns-zones/{uuid}/records/

列出区 DNS 记录

获取特定区域( 取消路线) 的所有 DNS 记录。

路径参数

参数	类型	必需的	说明说明
`uuid`	string	是的	Zone UUID

示例请求

curl -X GET "https://admin.vps.org/api/v1/dns-zones/{uuid}/records/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

示例回复

[
  {
    "uuid": "rec-001",
    "record_type": "A",
    "name": "@",
    "value": "192.0.2.1",
    "ttl": 3600,
    "priority": null,
    "created_at": "2024-01-15T10:30:00Z"
  },
  {
    "uuid": "rec-002",
    "record_type": "MX",
    "name": "@",
    "value": "mail.example.com",
    "ttl": 3600,
    "priority": 10,
    "created_at": "2024-01-15T10:32:00Z"
  }
]

邮 /api/v1/dns-zones/{uuid}/records/

在区域中创建 DNS 记录

在特定区域(取消路线)添加新的 DNS 记录。

请求体参数

参数	类型	必需的	说明说明
`record_type`	string	是的	Record type: A, AAAA, CNAME, MX, TXT, NS, SRV, CAA
`name`	string	是的	Record name (`@` for root, subdomain, or FQDN)
`value`	string	是的	Record value (IP address, hostname, text)
`ttl`	integer	No	Time to live in seconds (default: 3600)
`priority`	integer	For MX/SRV	Priority (required for MX and SRV records)

示例请求

cURL

Python

curl -X POST "https://admin.vps.org/api/v1/dns-zones/{uuid}/records/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "record_type": "A",
    "name": "www",
    "value": "192.0.2.1",
    "ttl": 3600
  }'

import requests

url = f"https://admin.vps.org/api/v1/dns-zones/{zone_uuid}/records/"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "record_type": "A",
    "name": "www",
    "value": "192.0.2.1",
    "ttl": 3600
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

响应状态码

201	DNS record created successfully
400	Bad Request - Invalid parameters or validation error (e.g., MX record missing priority)

GET PUT PATCH DELETE /api/v1/dns-records/{uuid}/

管理 DNS 记录( 直接访问)

使用记录UUUID,对单个 DNS 记录进行全面CRUD操作。

可用业务

GET /api/v1/dns-records/{uuid}/ - Retrieve record details
PUT /api/v1/dns-records/{uuid}/ - Full update (all fields required)
PATCH /api/v1/dns-records/{uuid}/ - Partial update (only changed fields)
DELETE /api/v1/dns-records/{uuid}/ - Delete record

查询参数(Get/api/v1/dns- records/)

Parameter	类型	说明说明
`zone`	string	Filter records by zone UUID
`record_type`	string	Filter by record type (A, AAAA, MX, etc.)

示例:更新记录TTL

curl -X PATCH "https://admin.vps.org/api/v1/dns-records/{rec-uuid}/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ttl": 1800}'

Supported DNS Record Types

类型	Purpose	Example Value	Priority Required
A	Maps domain to IPv4 address	192.0.2.1	否无
AAAA	Maps domain to IPv6 address	2001:0db8::1	否无
CNAME	Creates alias to another domain	example.com	否无
MX	Mail server for domain	mail.example.com	是的
TXT	Text record (SPF, DKIM, verification)	v=spf1 include:_spf.google.com ~all	否无
NS	Nameserver delegation	ns1.example.com	否无
SRV	Service location record	10 5060 sip.example.com	是的
CAA	Certificate authority authorization	0 issue "letsencrypt.org"	否无

最佳做法最佳做法

TTL 配置

生产(稳定): 3600-86400秒(1-24小时)
在移徙之前: 300-600秒(5-10分钟) -- -- 在计划变动前降低TTL
发展: 300-1800秒(5-30分钟),用于更快测试

共同模式

根域 (@ ) : 使用A/AAAAA记录,非NAME
www subdomain: 可以使用指向 root 或单独 A 记录的 NAME
电子邮件(MX): 总是包含优先级, 低数=高优先级
CNAME: 北冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋,南冰洋洋洋洋,南冰洋洋洋,南冰洋,南冰洋。无法与同名的其他记录类型共存

安全安全安全安全安全安全安全安全

CAA记录: 指定哪些 CA 可以签发证书
SPF/DKIM/DMARC: 配置电子邮件认证, 以防止欺骗
定期审计: 每季度审查DNS记录,删除未用条目

错误处理错误处理

常见错误

状态码	错误错误错误	解决方案
400	无效的域名	确保域域遵循 DNS 命名惯例
400	MX记录需要优先处理	包含 `priority` MX和SRV记录的字段
401	无效的 API 代号	检查代号格式( 必须以 `vps_`)
403	缺少许可	生成有需要的新标记 `dns:*` 权限权限
404	找不到区/记录	校验 UUUID 并确保资源属于您的账户

示例错误反应

{
  "detail": "MX records require a priority value",
  "error_code": "validation_error",
  "field": "priority"
}

测试 DNS 变化

核查记录传输

# Query A record
dig example.com A

# Query specific nameserver
dig @ns1.vps.org example.com

# Query MX records
dig example.com MX

# Check all records
dig example.com ANY

使用在线工具

whatsmydns.net: Check global DNS propagation
dnschecker.org: Multi-location DNS lookup
mxtoolbox.com: Email-related DNS testing

VPS.org API

概述

命名器基础设施

密钥特征

验证

示例示例示例示例

列出所有 DNS 区域

查询参数

示例请求

示例回复

响应字段

响应状态码

获取 DNS 区细节

路径参数

示例回复

响应状态码

创建 DNS 区

请求体参数

示例请求

示例回复

响应状态码

删除 DNS 区

路径参数

响应状态码

列出区 DNS 记录

路径参数

示例请求

示例回复

在区域中创建 DNS 记录

请求体参数

示例请求

响应状态码

管理 DNS 记录( 直接访问)

可用业务

查询参数(Get/api/v1/dns- records/)

示例:更新记录TTL

Supported DNS Record Types

最佳做法最佳做法

TTL 配置

共同模式

安全安全安全安全安全安全安全安全

错误处理错误处理

常见错误

示例 错误反应

测试 DNS 变化

核查记录传输

使用在线工具

示例错误反应