宝塔域名 API 怎么暂停/恢复解析记录、托管外部域名？5 个接口一次讲清

用宝塔域名 API 管理 DNS，除了创建、查询、更新、删除四个解析记录接口，还有 5 个「维护与托管」接口，解决两类场景：临时下线某条解析记录而不删掉它（暂停/启动），以及把其他注册商注册的域名接入宝塔 DNS 托管（添加外部域名、检查域名状态、删除外部域名）。调用前提和 CRUD 接口相同：先在域名管理后台申请 Account ID、Access Key、Secret Key，再用 HMAC-SHA256 算签名（详见官方文档《宝塔域名 API 概览与签名认证》）。本文逐个讲清这 5 个接口的请求参数、返回字段和错误码。

这 5 个接口分别做什么

接口	地址	作用
暂停解析记录	POST /api/v1/dns/record/pause	停止解析但保留记录，可恢复
启动解析记录	POST /api/v1/dns/record/start	恢复已暂停的记录，重新生效
添加外部域名	POST /api/v1/dns/manage/add_external_domain	把其他注册商的域名接入宝塔 DNS
检查域名状态	POST /api/v1/dns/manage/check_domain_status	查域名的注册信息、NS 与解析状态
删除外部域名	POST /api/v1/dns/manage/remove_domain	移除外部域名（不可逆）

下面分「暂停/恢复解析记录」和「外部域名托管」两块讲。

怎么临时下线一条解析记录？用暂停，不要用删除

网站维护或临时切流时，常需要让某条解析记录停止生效，但之后还要恢复。这时用暂停接口而不是删除接口——暂停只停止解析、记录信息原样保留，随时可以恢复；删除则是彻底移除、无法找回。两者的区别：

• 暂停：记录停止解析但信息保留，可恢复
• 删除：记录完全移除，无法恢复

暂停接口 POST /api/v1/dns/record/pause，请求示例：

{
  "record_id": 9,
  "domain_type": 2,
  "domain_id": 1
}

三个请求参数都是必选：

参数名称	必选	类型	描述
record_id	是	Integer	记录 ID
domain_type	是	Integer	域名类型：1（宝塔内部域名）、2（外部域名）
domain_id	是	Integer	域名 ID

成功后返回 code: 0、msg: "暂停解析记录成功"、status: true，data 为空对象。如果这条记录本来就处于暂停状态，再暂停会返回 code: 409、msg: "记录已经是暂停状态"。

要恢复时，用启动接口 POST /api/v1/dns/record/start，参数与暂停完全一致（同样是 record_id、domain_type、domain_id 三个必选参数），成功后返回 code: 0、msg: "启动解析记录成功"。

启动接口只能用于已暂停（disabled）的记录。对已启用（enabled）的记录调用启动接口，会返回 code: 409、msg: "记录已经是启动状态" 的状态冲突错误。

怎么把其他注册商的域名接入宝塔 DNS？分添加、检查、删除三步

域名不在宝塔注册时，也可以把它接入宝塔域名管理系统、使用宝塔的 DNS 解析服务，相关的三个接口是「添加外部域名 → 检查域名状态 → 删除外部域名」。

添加外部域名：接口 POST /api/v1/dns/manage/add_external_domain，把其他注册商注册的域名添加到堡塔域名管理系统。请求示例：

{
  "full_domain": "example.com",
  "remark": ""
}

参数名称	必选	类型	描述
full_domain	是	String	域名名称，需要是有效的域名格式
remark	否	String	备注信息

成功后 data 返回四个字段：dns_id（DNS 解析 ID）、domain_id（域名 ID）、full_domain（域名名称）、ns_status（当前 DNS 状态）。其中 ns_status 有三个值：0 未设置、1 已设置、2 检测中。域名格式不对时返回 code: 400、msg: "域名格式不正确"。

检查域名状态：接口 POST /api/v1/dns/manage/check_domain_status，用于查询指定域名的详细状态，包括注册信息、DNS 配置、解析状态等，常见用途是判断外部域名的 NS 是否已经指向宝塔云解析。请求示例：

{
  "domain_id": 14,
  "domain_type": 2
}

参数名称	必选	类型	描述
domain_id	是	Integer	域名 ID
domain_type	是	Integer	域名类型：1（平台域名）、2（外部域名）

返回的 data 里最关键是 check_result 字段，它有三个值：

状态码	描述
0	检测进行中
1	检测成功，DNS 配置正确
2	检测失败，DNS 配置错误

同时返回 current_ns（当前 DNS 服务器列表）和 expected_ns（期望的 DNS 服务器列表），两者对比就能看出 NS 是否已经切换到位；check_time 是检查时间，status_text 是状态描述文本。域名不存在时返回 code: 404、msg: "域名不存在"。

删除外部域名：接口 POST /api/v1/dns/manage/remove_domain，把域名从堡塔域名管理系统中移除，删除后将无法继续使用堡塔的 DNS 解析服务。请求参数只有一个必选的 domain_id（域名 ID）：

{
  "domain_id": 1
}

成功后 data 返回 domain_id 和 full_domain 两个字段。删除是不可逆操作，删除后该域名的所有解析记录也会被一并清除，调用前务必确认。域名不存在时返回 code: 404、msg: "域名不存在"。

信息来源

本文事实以宝塔官方文档为准：《API·暂停 DNS 解析记录》、《API·启动 DNS 解析记录》、《API·添加外部域名》、《API·检查域名状态》、《API·删除外部域名》。