DDNS × ClouDNS 配置指南：Auth 认证、TTL 限制与根域名记录处理的完整实战

• 网络
• CLI

本篇基于 ClouDNS 配置指南 展开，讲解如何在 DDNS 项目中接入 ClouDNS 服务商：包括 Auth-ID / Auth-Password 的获取与配置、完整 JSON 配置写法、TTL 取值范围、根域名记录的表示方式，以及cloudns服务商在源码层的请求流程与故障排查方法。读完后可独立完成 ClouDNS 接入配置，并理解每条 API 调用背后的实现细节。

一、ClouDNS 服务商概述

ClouDNS 是一个全球性的 DNS 托管服务提供商，提供免费和付费（Premium）两档 DNS 解析服务，支持动态 DNS 记录的创建与更新。DDNS 项目通过 ClouDNS API 实现 DNS 记录的自动管理，在配置中仅需将dns字段设置为cloudns即可启用。

从源码结构看，cloudns是项目中已注册的一级服务商标识：get_provider_class 中的映射表把"cloudns"直接映射到CloudnsProvider类，不存在别名或兼容写法。入口逻辑在 run()：读取配置后通过get_provider_class(config.dns)取到对应类，并以config.id、config.token等参数实例化服务商对象，随后分别对 IPv4（A 记录）与 IPv6（AAAA 记录）执行update_ip。

官方相关链接（配置与调试时需要用到）：

• 控制面板：https://www.cloudns.net/dns-zones/
• API 设置页：https://www.cloudns.net/api-settings/
• API 文档：https://www.cloudns.net/wiki/

二、认证信息：Auth-ID 与 Auth-Password

ClouDNS 不使用常见的 API Token 模式，而是使用Auth-ID和Auth-Password进行 API 认证。在 DDNS 配置中，这两个值分别对应id和token字段：

{ "dns": "cloudns", "id": "12345", // ClouDNS Auth-ID "token": "your_auth_password" // ClouDNS Auth-Password }

获取认证信息的步骤

1. 登录 ClouDNS 控制面板；
2. 进入 "API" 设置页面（API settings）；
3. 如果尚未启用 API 访问，点击 "Enable API"；
4. 复制你的Auth-ID（通常是一个数字 ID）；
5. 创建或查看你的Auth-Password（API 密码）。

安全提示：为提高安全性，建议创建一个子账号专门用于 DDNS API 访问，并仅授予必要的 DNS 管理权限；定期检查 API 访问日志以监控异常活动。

权限要求

确保使用的 ClouDNS 账号具备以下权限：

• DNS 区域管理：能够列出和访问 DNS 区域；
• DNS 记录管理：能够创建、读取、更新 DNS 记录。

如果使用子账号，请在主账号中为子账号分配相应的权限。

源码视角：认证参数如何注入请求

在 CloudnsProvider 中，认证发生在每个请求内部而非初始化阶段。_request方法（ddns/provider/cloudns.py）会把配置中的两个字段以auth-id、auth-password参数名附加到每一次请求体中：

def _request(self, action, **params): # 自动添加认证参数 params["auth-id"] = self.id params["auth-password"] = self.token # 过滤 None 值后以 POST 发送 data = self._http("POST", action, body=params) ...

该服务商的三个关键类级常量同样定义在 ddns/provider/cloudns.py：

响应判定逻辑也值得注意：ClouDNS API 存在三种返回形态——成功操作返回{"status": "Success", ...}，失败操作返回{"status": "Failed", "statusDescription": "..."}，而查询类接口直接返回记录数据（不含status字段）。_request对显式的status == "Failed"会记录警告并返回None，其余情况原样交给上层处理。单元测试 tests/test_provider_cloudns.py 专门验证了auth-id/auth-password会被附加进请求体。

三、完整配置示例

一份可直接使用的完整配置如下（字段注释与 docs/en/providers/cloudns.md 中的示例一致）：

{ "$schema": "https://ddns.newfuture.cc/schema/v4.1.json", // 格式验证 "dns": "cloudns", // 当前服务商 "id": "12345", // ClouDNS Auth-ID "token": "your_auth_password", // ClouDNS Auth-Password "index4": ["url:http://api.ipify.org", "public"], // IPv4地址来源 "index6": "public", // IPv6地址来源 "ipv4": ["ddns.example.com"], // IPv4 域名 "ipv6": ["ddns.example.com", "ipv6.example.com"], // IPv6 域名 "ttl": 60 // DNS记录TTL（秒） }

其中cloudns已在 schema/v4.1.json 的dns枚举中合法声明，$schema可指向仓库内同构的 schema/v4.1.json 或线上地址做格式校验。

参数说明

参数类型说明：

• 公用配置：所有支持的 DNS 服务商均适用的标准 DNS 配置参数；
• 公用网络：所有支持的 DNS 服务商均适用的网络设置参数；
• 服务商参数：当前服务商支持，值与当前服务商相关。

几个公用参数对 ClouDNS 场景的实际影响，可对照 JSON 配置文档 理解：

• index4/index6：指定 IP 获取方式，支持public（公网 IP 查询）、url:...、regex:...、cmd:、shell:、网卡编号及false（禁用对应地址族）等写法，数组形式表示失败后依次回退。IPv4/IPv6 两族独立处理：一族获取失败不会阻止另一族更新，但任一启用的记录更新失败都会让本次 CLI 运行返回非零退出码。
• proxy：可为单个地址、数组（按序回退）、SYSTEM、DIRECT。注意代理只对 provider 请求生效，获取 IP 的 API 不走 proxy。
• ssl："auto"会自动降级到不验证证书，true强制验证，也可指定 CA 证书文件路径；该配置同时作用于 provider 与 IP 获取 API。
• ttl：配置为整数秒；从 config.py 的解析逻辑看，字符串形式的ttl也会被int()转换为整数，未配置时为None，此时由服务商侧采用默认值（对 ClouDNS 即DEFAULT_TTL = 60）。
• cache：true时默认写入临时目录下的ddns.{hash}.cache，可改为false或自定义文件路径；缓存命中时若 IP 未变化会跳过 API 更新请求。

四、TTL：ClouDNS 的取值范围与默认策略

ttl参数指定 DNS 记录的生存时间（TTL），单位为秒。ClouDNS 支持的范围与套餐类型强相关：

默认 TTL 为60 秒（最小值），适合快速更新 DDNS 记录。

这一点与源码实现完全对应：_create_record和_update_record中都有相同的兜底逻辑——若上层未传入ttl（即为None），则使用self.DEFAULT_TTL（60 秒）：

# ddns/provider/cloudns.py（创建记录） if ttl is None: ttl = self.DEFAULT_TTL params = { "domain-name": zone_id, "record-type": record_type, "host": host, "record": value, "ttl": ttl, } data = self._request("/dns/add-record.json", **params)

单元测试 test_create_record_default_ttl 与 test_update_record_default_ttl 分别断言了创建与更新两条路径在ttl=None时请求体中ttl均为 60。需要提醒：免费版账号若配置超过 86400 的 TTL，可能被供应商侧拒绝，此时应在日志中看到Failed to create/update record的报错。

五、根域名记录：""与"@"的自动处理

ClouDNS 使用空字符串""或"@"表示根域名记录，而 DDNS 内部以"@"表示根记录。DDNS 会自动处理这两种表示方式的转换，配置时无需区分：

• 想更新example.com的记录，直接使用域名example.com即可；
• 想更新www.example.com的记录，使用域名www.example.com。

源码中该转换体现在两处。查询时（_query_record）：

# 对 @（根域名）记录，ClouDNS 使用空字符串 host = "" if subdomain == "@" else subdomain params = {"domain-name": zone_id, "host": host, "type": record_type} data = self._request("/dns/records.json", **params)

且匹配现有记录时同时接受两种根域名写法：

if record_host == host or (subdomain == "@" and record_host in ("", "@")): if record.get("type") == record_type: return record

创建时同样把"@"映射为空字符串。tests/test_provider_cloudns.py 中的test_query_record_root验证了返回host: "@"的记录也能被正确识别为根记录。

另外，ClouDNS 与其他服务商的一个显著差异是：它直接把域名本身当作 zone 标识，没有数字型 zone ID。_query_zone_id 因此是一个无网络调用的直接返回：

def _query_zone_id(self, domain): # ClouDNS 直接使用 domain-name，无数字型 zone ID return domain

这意味着www.example.com会被拆解为sub="www"、main="example.com"（zone 即example.com），无需额外的"按域名查区域"API 调用。

六、更新流程：查询 → 更新或创建

CloudnsProvider继承自 BaseProvider，复用基类的set_record统一编排（ddns/provider/_base.py#L339-L385）：

1. 将完整域名拆解为zone_id/sub/main（支持~、+自定义分隔符，ClouDNS 走自动拆解路径）；
2. 调用_query_record查询现有记录：POST /dns/records.json，参数为domain-name、host、type，响应为{"<record_id>": {记录数据}, ...}形式的字典；
3. 若查找到记录，调用_update_record：POST /dns/mod-record.json，参数包含record-id（取自查询结果的id字段）、host（保留原记录的 host）、record（新 IP）、ttl；
4. 若未找到记录，调用_create_record：POST /dns/add-record.json；
5. 以响应中status == "Success"判定成败，失败时记录 error 日志并返回False。

三个 API 接口与对应源码位置：

测试用例覆盖了完整工作流：TestCloudnsProviderIntegration 模拟了"查无记录→创建成功"、"查到记录→更新成功"以及根域名记录三条链路；test_update_record_missing_id 则验证了旧记录缺少id字段时会直接返回失败而不是发起请求。

七、故障排除

调试模式

启用调试日志查看详细信息：

ddns -c config.json --debug

--debug由 CLI 参数定义 注册，会把日志级别提升到 DEBUG（见 ddns/config/cli.py），届时可以看到每次请求的完整 URL 与脱敏后的请求体（_http会记录body并调用_mask_sensitive_data屏蔽敏感字段），是排查认证与参数问题的首选手段。

常见问题

• Invalid authentication：检查id/token对应的 Auth-ID 与 Auth-Password 是否正确，API 是否已启用；
• Zone not found：确保域名已添加到 ClouDNS 账号、域名处于活跃状态；
• Record creation failed：检查记录格式和 TTL 值（注意免费版的 86400 秒上限），确认账号权限；
• API limit exceeded：API 调用频率超限，降低请求频率（调大调度间隔）或升级套餐。

从实现上看，上述第一类问题在 _request 中会输出ClouDNS API error: <statusDescription>的 warning，statusDescription即供应商返回的具体原因，调试日志里可直接定位。

免费套餐限制

ClouDNS 免费套餐有以下限制：

• 每个账号最多 4 个 DNS 区域；
• 每个区域最多 50 条记录；
• API 请求频率限制（具体限制请参考官方文档）。

如需更多资源，请考虑升级到付费套餐。

八、小结：配置要点速查

1. dns固定写cloudns；id填 Auth-ID，token填 Auth-Password，两者在每次请求中以auth-id/auth-password表单参数提交到https://api.cloudns.net；
2. ttl建议显式配置为 60，不配置时源码同样以 60 秒兜底；免费账号注意 86400 秒上限；
3. 根域名直接写完整主域名（如example.com），""与"@"的表示差异已由 CloudnsProvider 自动处理；
4. 出现认证、区域、权限类报错时，用ddns -c config.json --debug抓取statusDescription，并对照 单元测试 中的预期行为核对请求参数；
5. 安全上建议使用仅授予 DNS 记录管理权限的子账号，并定期查看 API 访问日志。

更多公用参数（index4/index6、proxy、ssl、cache、log等）的完整取值说明见 JSON 配置文档，服务商列表与接入总览见 docs/en/providers/README.md。

• 网络
• CLI