51DNS（DNSCOM）DDNS 接入指南：API Key 认证、配置参数与源码实现解析

• 网络
• CLI

本指南以 DDNS 项目中 51DNS（DNSCOM）服务商文档为主体，讲解如何获取 51DNS API Key / Secret Key 认证信息、编写完整的 JSON 配置（含 TTL、解析线路等核心参数）、使用调试模式排查故障，并结合ddns/provider/dnscom.py源码与tests/test_provider_dnscom.py测试用例，深入解析其 MD5 签名、记录查询/创建/更新调用链等底层实现。读完即可在 DDNS 中完成 51DNS 域名的动态解析同步。

51DNS（DNSCOM）是国内知名的权威 DNS 解析服务商（原 dns.com，现 51dns.com），支持动态 DNS 记录的创建与更新。本 DDNS 项目通过 API Key 和 Secret Key 进行 API 认证。

⚠️注意：51DNS(DNSCOM) Provider 目前处于待验证状态，缺少充分的真实环境测试。建议在生产环境使用前进行充分测试，并请通过 GitHub Issues 反馈问题。

认证信息：API Key + Secret Key

51DNS 使用 API Key 和 Secret Key 进行 API 认证，这是官方推荐的认证方式。

获取认证信息

1. 登录 51DNS/DNS.COM 控制台
2. 进入「API 管理」页面
3. 点击「创建 API Key」
4. 记录生成的API Key和Secret Key，请妥善保存（Secret Key 用于请求签名，泄露等同于域名解析权限泄露）

最小认证配置如下：

{ "dns": "dnscom", "id": "your_api_key", // 51DNS API Key "token": "your_secret_key" // 51DNS Secret Key }

其中id对应 API Key，token对应 Secret Key，dns固定为dnscom。需要说明的是，从 provider 注册映射（ddns/provider/init.py）可以看到，dnscom、51dns、dns_com三个标识都会解析到同一个DnscomProvider实现类，因此三者均可作为dns字段的取值。

完整配置示例

以下是一份可直接参考的完整配置（来自 docs/en/providers/51dns.md）：

{ "$schema": "https://ddns.newfuture.cc/schema/v4.1.json", // 格式验证 "dns": "dnscom", // 当前服务商 "id": "your_api_key", // 51DNS API Key "token": "your_secret_key", // 51DNS Secret Key "index4": ["url:http://api.ipify.org", "public"], // IPv4地址来源 "index6": "public", // IPv6地址来源 "ipv4": ["ddns.newfuture.cc"], // IPv4 域名 "ipv6": ["ddns.newfuture.cc", "ipv6.ddns.newfuture.cc"], // IPv6 域名 "line": "1", // 解析线路 "ttl": 600 // DNS记录TTL（秒） }

配置文件中$schema指向项目维护的 JSON Schema（对应仓库中的 schema/v4.1.json），配合支持 JSON Schema 的编辑器（如 VSCode）可获得自动补全与格式校验；自 v4.1.0 版本起配置文件支持单行注释（//）。

参数说明

参数类型说明：

• 公用配置：所有支持的 DNS 服务商均适用的标准 DNS 配置参数（如index4、index6、ipv4、ipv6、cache、log）
• 公用网络：所有支持的 DNS 服务商均适用的网络设置参数（如proxy、ssl）
• 服务商参数：仅当前服务商支持，取值与当前服务商相关（如line、ttl）

注意：ttl和line不同套餐支持的值可能不同，请以实际开通的套餐为准。

ttl

ttl参数指定 DNS 记录的生存时间（TTL），单位为秒。51DNS 支持的 TTL 范围因套餐而异，如果不设置则使用服务商默认值：

注意：具体 TTL 范围请参考 51DNS 官方文档。在 schema/v4.1.json 中，ttl被定义为number | null，默认null表示沿用 DNS 服务商默认 TTL 策略。

line

line参数指定 DNS 解析线路（即按运营商或区域分流解析），51DNS 支持的线路标识：

更多线路（如海外、教育网等）请参考 51DNS 官方 API 文档的 ViewID 说明。在实际请求中，line会作为viewID字段随记录创建/查询请求一起发送（见下文源码解析）。

命令行配置与运行

除了 JSON 配置文件，也可以通过命令行参数直接配置并运行（命令行参数优先级最高，详见 docs/config/cli.md）：

# 指定配置文件运行 ddns -c config.json # 或使用 Python 源码运行 python -m ddns -c config.json # 调试模式，输出详细日志 ddns -c config.json --debug # 完全通过命令行参数配置 ddns --dns dnscom --id your_api_key --token your_secret_key --ipv4 ddns.newfuture.cc --line 1 --ttl 600

其中--debug等同于--log_level=DEBUG，可用于查看每一次 API 请求与响应细节。需要提示的是，--debug仅作为命令行参数生效，写入配置文件中的debug字段会被忽略（见 docs/config/cli.md）。

故障排除

调试模式

启用调试日志可以查看详细的请求与响应信息：

ddns -c config.json --debug

结合日志输出即可定位是认证失败、域名未找到，还是记录创建/更新环节出错。

常见问题

• 认证失败：检查 API Key 和 Secret Key 是否正确，确认 API 密钥状态为启用
• 域名未找到：确保域名已添加到 51DNS 账号，配置拼写无误，域名处于活跃状态
• 记录创建失败：检查子域名是否有冲突记录，TTL 设置是否合理，确认拥有修改权限
• 请求频率限制：51DNS 有 API 调用频率限制（每分钟最多 100 次），应降低请求频率；配合cache缓存参数（默认开启）可避免频繁更新、减少 API 调用

API 错误代码

在 ddns/provider/dnscom.py 的_request方法中，任何非 0 的code都会抛出"api error: {message}"异常，并最终在set_record中被捕获并记为失败（见 ddns/provider/_base.py），因此日志中出现的api error信息可以直接与上表对照。

源码实现：DnscomProvider 的调用链与签名原理

以上配置能正常工作，依赖的是 ddns/provider/dnscom.py 中DnscomProvider类的实现。它继承自 ddns/provider/_base.py 中的BaseProvider（标准 DNS 服务商抽象基类），按「查询 zone → 查询记录 → 更新或创建」的统一流程工作。

请求签名：MD5(query + SecretKey)

51DNS API 采用 MD5 签名认证，核心逻辑位于_signature方法（ddns/provider/dnscom.py）：

1. 过滤掉值为None的参数；
2. 注入apiKey（即配置的id）和timestamp（当前时间戳）；
3. 将所有参数编码为 URL 查询字符串（按 key 排序，见 ddns/provider/_base.py 的encode_params）；
4. 计算md5(query + self.token)的十六进制摘要，作为hash字段追加到参数中。

也就是说，每个请求的签名由「全部业务参数 + API Key + 时间戳」拼接 Secret Key 后取 MD5 生成，Secret Key 本身不随请求明文传输。对应测试 tests/test_provider_dnscom.py 验证了apiKey、timestamp、hash三个字段都会出现在签名后的参数中，同时None参数会被过滤（tests/test_provider_dnscom.py）。

请求封装与响应校验

_request方法（ddns/provider/dnscom.py）负责：

• 调用_signature对参数签名；
• 通过self._http("POST", "/api/{action}/", body=params)发送application/x-www-form-urlencoded表单请求（类常量content_type = TYPE_FORM，endpoint 为https://www.51dns.com）；
• 校验响应：响应为空或非 dict 时抛出"response data is none"，code非 0 时抛出"api error: {message}"，成功则返回data字段。

记录管理三步调用链

DnscomProvider实现了BaseProvider定义的四个抽象方法，与 API 的对应关系如下：

其中remark默认值为"Managed by [DDNS](https://link.gitcode.com/i/ae8ed8a4f81ff384f943ac8848b8398e) 验证了自定义 remark 的优先级）。创建/更新成功后，_create_record依据返回的recordID判断是否成功，_update_record` 依据返回结果是否非空判断。

在调度层，BaseProvider.set_record（ddns/provider/_base.py）会：

1. 将完整域名拆分为子域与主域（支持~或+自定义分隔符，也支持自动逐级尝试匹配 zone）；
2. 调用_query_zone_id获取 zone id（带_zone_map内存缓存）；
3. 调用_query_record查询现有记录；
4. 记录已存在则走_update_record，否则走_create_record。

tests/test_provider_dnscom.py中的集成测试完整模拟了这一流程：TestDnscomProviderIntegration.test_full_workflow_create_new_record（tests/test_provider_dnscom.py）依次断言了domain/getsingle→record/list→record/create三次 API 调用；test_full_workflow_update_existing_record（tests/test_provider_dnscom.py）则验证了查询到已有记录后走record/modify更新分支。

待验证状态提示

_validate方法（ddns/provider/dnscom.py）在初始化时会打印警告日志，提示「DNS.COM 缺少充分的真实环境测试，请及时在 GitHub Issues 中反馈」，这与文档中的待验证状态一致。因此在实际使用前，建议先用--debug模式在测试域名上完整跑通一次创建与更新流程，再迁移到生产环境。

多服务商格式中的 51DNS

自 v4.1.0 起，DDNS 支持在单个配置文件中使用providers数组定义多个 DNS 服务商（详见 docs/config/json.md）。51DNS 同样可以嵌套其中：

{ "$schema": "https://ddns.newfuture.cc/schema/v4.1.json", "ssl": "auto", "cache": true, "log": {"level": "INFO"}, "providers": [ { "provider": "51dns", "id": "your_api_key", "token": "your_secret_key", "ipv4": ["ddns.newfuture.cc"], "ipv6": ["ipv6.ddns.newfuture.cc"], "line": "1", "ttl": 600 } ] }

注意此格式中字段名是provider（而非dns），providers与顶层dns字段不能同时存在，多 provider 时全局不得出现ipv4/ipv6字段。在 schema/v4.1.json 的 provider 枚举中同时收录了51dns与dnscom，二者均指向同一个DnscomProvider实现（ddns/provider/init.py）。

支持与资源

• 51DNS 官方网站
• 51DNS API 文档
• 51DNS 控制台
• 配置基础：JSON 配置文件参考、命令行参数参考、环境变量配置
• 实现与测试：DnscomProvider 源码、单元测试、provider 注册映射、配置 Schema

⚠️待验证状态：51DNS Provider 缺少充分的真实环境测试，建议在生产环境使用前进行充分测试。如遇问题请通过 GitHub Issues 反馈。

• 网络
• CLI