lego 使用 Duck DNS 提供商自动完成 DNS-01 挑战配置、环境变量与源码实现解析【免费下载链接】legoLets Encrypt/ACME client and library written in Go项目地址: https://gitcode.com/gh_mirrors/le/lego本指南聚焦于 legoGo 编写的 Lets Encrypt/ACME 客户端与库中 Duck DNS 提供商的完整配置方法覆盖从环境变量凭据、超时与传播参数到 API 调用原理与源码实现细节。读完本文你将能够使用DUCKDNS_TOKEN一键签发包含通配符域名的证书并理解 lego 是如何通过 Duck DNS 更新接口完成 ACME DNS-01 挑战的。功能定位duckdns 提供商Duck DNS 是一个免费提供动态 DNS 与子域服务的平台它同时也允许用户通过简单的 HTTP GET 请求更新域名的 TXT 记录这使其非常适合用于 ACME DNS-01 挑战。lego 自 v0.5.0 起内置了该提供商支持CodeduckdnsSincev0.5.0对应实现位于 providers/dns/duckdns 目录提供方元数据定义在 duckdns.toml快速开始一行命令签发证书原文档给出的最小可用示例来自 duckdns.toml 的Example字段DUCKDNS_TOKENxxxxxx \ lego run --dns duckdns -d *.example.com -d example.com命令要点拆解DUCKDNS_TOKENxxxxxx通过环境变量注入 Duck DNS 账户令牌在 duckdns.org 控制面板中可以获取--dns duckdns指定使用 duckdns 作为 DNS-01 挑战的提供商-d *.example.com -d example.com同时申请通配符域名与根域名两者共用同一张证书。执行后lego 会调用 Duck DNS 的更新接口写入 ACME 挑战所需的 TXT 记录等待 DNS 传播完成后向 CALets Encrypt发起签发请求并在签发完成后清理该 TXT 记录。凭据配置DUCKDNS_TOKENDuck DNS 提供商仅需要一个凭据环境变量环境变量名说明DUCKDNS_TOKENDuck DNS 账户令牌Account token当DUCKDNS_TOKEN缺失或为空时lego 会直接报错中止。这一点在 duckdns_test.go 的测试用例中有明确印证缺省令牌时NewDNSProvider()返回duckdns: some credentials information are missing: DUCKDNS_TOKEN而NewDNSProviderConfig()返回duckdns: credentials missing。使用文件引用凭据_FILE后缀所有环境变量名都可以追加_FILE后缀改为引用一个文件路径而不是直接提供值DUCKDNS_TOKEN_FILE/path/to/duckdns_token \ lego run --dns duckdns -d *.example.com -d example.com其中/path/to/duckdns_token文件内容必须只包含令牌本身不要带换行以外的任何字符。该机制由 platform/env/env.go 统一实现读取环境变量时优先取KEY的值否则回退检查KEY_FILE指向的文件内容。使用 dotenv 文件也可以在.env文件中集中管理凭据并通过--env-file参数加载lego run --dns duckdns -d *.example.com -d example.com --env-file .env.duckdns# .env.duckdns DUCKDNS_TOKENxxxxxx在库library的使用方式下则可在配置文件如.lego.yml中为 dns 挑战指定envFile。完整的环境变量与 dotenv 用法说明见 docs/content/dns/_index.md。附加配置超时与传播参数Duck DNS 提供商支持 4 个可调参数全部通过环境变量注入环境变量名说明默认值DUCKDNS_HTTP_TIMEOUTAPI 请求超时秒30DUCKDNS_POLLING_INTERVAL两次 DNS 传播检查之间的间隔秒2DUCKDNS_PROPAGATION_TIMEOUTDNS 传播最长等待时间秒60DUCKDNS_SEQUENCE_INTERVAL顺序执行各挑战之间的间隔秒60这些默认值可以直接在源码中核对见 duckdns.go 的NewDefaultConfigDUCKDNS_HTTP_TIMEOUT默认 30 秒用于构造http.ClientDUCKDNS_PROPAGATION_TIMEOUT与DUCKDNS_POLLING_INTERVAL分别回退到 lego 内置的dns01.DefaultPropagationTimeout60 秒与dns01.DefaultPollingInterval2 秒这两个常量定义在 challenge/dns01/dns_challenge.goDUCKDNS_SEQUENCE_INTERVAL默认同样为 60 秒。与凭据一样上述参数名也支持_FILE后缀。源码级原理解析提供商生命周期Present → 传播等待 → CleanUpDuck DNS 提供商实现了challenge.Provider接口见 challenge/provider.go核心是Present与CleanUp两个方法duckdns.goPresent(ctx, domain, token, keyAuth)由dns01.GetChallengeInfo计算出挑战记录名_acme-challenge.域名的 FQDN与挑战值然后调用底层客户端写入 TXT 记录CleanUp(ctx, domain, token, keyAuth)挑战完成或失败后清除对应的 TXT 记录Timeout()返回(PropagationTimeout, PollingInterval)告知 lego 在签发前应等待 DNS 传播多久、以什么频率轮询检查——这正是DUCKDNS_PROPAGATION_TIMEOUT与DUCKDNS_POLLING_INTERVAL发挥作用的位置Sequential()返回SequenceInterval表示该提供商的多个挑战如同时签发example.com与*.example.com将串行执行每个挑战之间间隔 60 秒以降低对 Duck DNS 更新接口的压力。与 Duck DNS 更新接口的交互底层 HTTP 客户端位于 providers/dns/duckdns/internal/client.go其实现揭示了几个关键事实更新端点默认基地址为https://www.duckdns.org/update全程使用一次 GET 请求即可完成 TXT 记录的写入或清除请求携带以下查询参数参数含义domains要更新的主域名经规范化处理token账户令牌txt要写入的 TXT 记录值清除时为空clear是否清除现有 TXT 记录true/false响应校验接口的响应体必须是字符串OK否则返回错误错误信息中会附带实际响应内容与请求 URL这为排查网络/令牌问题提供了直接线索。域名规范化逻辑由于 Duck DNS 只允许用户写入自己的子域记录名必须是subdomain.duckdns.org形式而不是subsubdomain.subdomain.duckdns.org。因此getMainDomain会对以duckdns.org结尾的域名剥离到最顶层的三级域名取subdomain.duckdns.org对其他域名你自己的托管域名取最后一级标签之后的完整域无法解析出主域名时直接返回错误。这一设计意味着使用通配符域名签发时挑战 TXT 记录最终会落在 Duck DNS 为你分配的子域上并通过 Duck DNS 现有的 DNS 解析对外生效。作为 Go 库使用除了 CLIduckdns 提供商同样可以嵌入你自己的 Go 程序import github.com/go-acme/lego/v5/providers/dns/duckdns config : duckdns.NewDefaultConfig() config.Token xxxxxx // 或读取自环境变量 provider, err : duckdns.NewDNSProviderConfig(config) if err ! nil { // 处理错误 }NewDNSProvider()是便捷入口直接读取环境变量DUCKDNS_TOKEN构建提供商NewDNSProviderConfig(config)则允许编程式传入Token、各超时值以及自定义HTTPClient。若传入nil配置或空令牌两者都会返回明确错误见 duckdns_test.go 中的对应测试用例。测试与验证方式duckdns_test.go 覆盖了三类场景单元测试验证NewDNSProvider/NewDNSProviderConfig在令牌缺失、令牌有效两种情况下的行为Live 测试TestLivePresent与TestLiveCleanUp在设置了真实DUCKDNS_TOKEN与域名环境变量时会真实调用 Duck DNS 接口完成一次写入与清理默认跳过需显式开启 live 测试请求调试HTTP 客户端被clientdebug.Wrap包装配合LEGO_HTTP_DEBUG之类的调试开关可观察实际发出的请求。使用注意事项令牌即凭据DUCKDNS_TOKEN等同于账户令牌泄露后他人可修改你的 TXT 记录请避免写入公开仓库优先使用_FILE或 dotenv 方式注入单 TXT 记录模型Duck DNS 中每个子域共享一条 TXT 记录因此 lego 实现的是写入/清除而非追加式管理同一时间建议只运行一个使用 duckdns 提供商的签发任务域名形态限制更新对象必须落在subdomain.duckdns.org层级上更深的子域会被自动规范化到主域详见getMainDomain的实现注释传播等待默认 60 秒传播超时与 2 秒轮询间隔可满足多数场景若你的网络环境解析较慢可适当调大DUCKDNS_PROPAGATION_TIMEOUT。至此你已掌握 duckdns 提供商从 CLI 一行命令、环境变量配置到源码级工作原理的完整链路可将其直接用于自动化证书签发与续期流程。【免费下载链接】legoLets Encrypt/ACME client and library written in Go项目地址: https://gitcode.com/gh_mirrors/le/lego创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考