宝塔域名 API 怎么用？密钥申请、HMAC 签名与 DNS 解析记录管理

想用代码自动管理域名和 DNS 解析记录，宝塔提供了域名 API：接口地址是 https://dmp.bt.cn/，仅支持 HTTPS，可以程序化地查域名列表、添加外部域名，以及创建、更新、删除、暂停、启动解析记录。用法分三步：先在域名管理后台「域名安全 → API 管理」拿到 Account ID、Access Key、Secret Key 三份密钥；每次请求用 HMAC-SHA256 算签名；最后向接口地址发 POST 请求调用对应接口。

下面按「拿密钥 → 算签名 → 看接口」的顺序讲清。

域名 API 是什么、能做什么？

宝塔域名 API 是对域名服务的一套操作接口，接口地址固定为 https://dmp.bt.cn/。官方文档列出了两条限制，用之前要记牢：

• 接口仅支持 HTTPS。
• 每个账号每日最多可调用 2000 次，超限会在一定时间内暂停 API 权限；也不要用 API 抢注过期域名，短时间重复提交相同域名会被禁用 API 权限。

它支持的操作分两类，接口都以 POST 请求调用：

域名管理

• POST /api/v1/dns/manage/list_domains —— 获取域名列表
• POST /api/v1/dns/manage/add_external_domain —— 添加外部域名
• POST /api/v1/dns/manage/remove_domain —— 删除外部域名
• POST /api/v1/dns/manage/check_domain_status —— 检查域名状态

解析记录管理

• POST /api/v1/dns/record/create —— 创建解析记录
• POST /api/v1/dns/record/update —— 更新解析记录
• POST /api/v1/dns/record/delete —— 删除解析记录
• POST /api/v1/dns/record/list —— 获取解析记录列表
• POST /api/v1/dns/record/pause —— 暂停解析记录
• POST /api/v1/dns/record/start —— 启动解析记录

怎么申请 API 密钥？

API 密钥是调用接口的凭据，含 Account ID、Access Key、Secret Key 三个部分。申请入口在域名管理后台，不是面板里：

1. 登录堡塔域名管理后台，在左侧导航选择【域名管理】。
2. 点左侧菜单【域名安全】，进入后点顶部选项卡【API 管理】。

3. 点【创建 API 密钥】按钮，在弹窗里填写密钥名称，以及可选的 IP 白名单（每行一个 IP）。

4. 点【创建】后，系统返回三份密钥信息。

Secret Key 一旦关闭窗口就无法再次查看，务必立即复制保存；也不要把密钥硬编码进代码，官方建议改用环境变量读取。IP 白名单建议设置，只允许指定 IP 调用，能显著降低密钥泄露后的风险。

签名认证怎么算？

宝塔域名 API 用 HMAC-SHA256 做请求签名，不传签名或签名不对会返回 401。签名计算分四步：

1. 准备五个值：account_id、timestamp（Unix 时间戳，秒）、method（POST）、path（如 /api/v1/dns/record/create）、body（请求体的 JSON 字符串）。
2. 把这五段用换行 \n 拼成签名字符串：account_id + "\n" + timestamp + "\n" + method + "\n" + path + "\n" + body。
3. 用 secret_key 对签名字符串做 HMAC-SHA256，得到十六进制签名。
4. 把结果放进请求头 X-Signature，并同时带上另外三个头。

最终请求头形如：

Content-Type: application/json
X-Account-ID: <Account ID>
X-Access-Key: <Access Key>
X-Timestamp: <Unix 时间戳>
X-Signature: <HMAC-SHA256 签名>

官方文档给的 Python 签名代码（节选）如下：

import hmac, hashlib, time

signing_string = f"{account_id}\n{timestamp}\n{method}\n{path}\n{body}"
signature = hmac.new(
    secret_key.encode(),
    signing_string.encode(),
    hashlib.sha256
).hexdigest()

其中 timestamp 是 str(int(time.time()))，method 用大写 POST，body 是请求体的 JSON 字符串（没有请求体时用空字符串）。

常见错误码怎么排查？

调用失败时，按返回的错误码对号入座：

错误码	错误信息	解决方法
401	缺少 API 签名参数	检查请求头是否带全 X-Account-ID、X-Access-Key、X-Timestamp、X-Signature
401	时间戳格式错误 / 请求时间戳无效	时间戳要用 Unix 时间戳，并检查客户端时间是否同步
401	API 配置无效	检查 Account ID 和 Access Key 是否正确
401	API 签名验证失败	检查签名计算是否正确，签名字符串五段顺序和换行是否对齐
403	IP 地址不在白名单中	把客户端 IP 添加到该密钥的 IP 白名单

信息来源

本文事实以宝塔官方文档为准：《宝塔域名 API 概览与签名认证》、《宝塔域名 API 密钥管理》、《API·创建 DNS 解析记录》、《API·获取用户 DNS 域名列表》。