Dyn DNS 提供商接入指南:用 lego 通过 DNS-01 挑战签发通配符证书
Dyn DNS 提供商接入指南:用 lego 通过 DNS-01 挑战签发通配符证书
本指南以 lego 项目自动生成的 Dyn 提供商文档(docs/content/dns/zz_gen_dyn.md,其内容源自 providers/dns/dyn/dyn.toml)为核心,结合
providers/dns/dyn包源码与测试,完整讲解如何在 lego 中使用 Dyn Managed DNS 完成 ACME DNS-01 挑战。读完本文,你将掌握 Dyn 提供商的环境变量配置、附加调优参数、CLI 用法,以及其底层 API 调用流程与库方式集成方法。
一、Dyn 提供商概览
Dyn(Dyn Managed DNS)是 lego 内置的 DNS 提供商之一,用于在 DNS-01 挑战中通过 Dyn 的 REST API 自动创建和删除 _acme-challenge TXT 记录。它让用户无需手动登录 DNS 控制台即可完成证书签发,特别适合为 *.example.com 这类通配符域名申请证书。
| 项目 | 值 |
|---|---|
| 提供商代码(Code) | dyn |
| 引入版本(Since) | v0.3.0 |
| 提供商名称 | Dyn |
| 官方 API 文档 | Dyn REST API |
该提供商自 v0.3.0 起便随 lego 提供,代码位于 providers/dns/dyn/dyn.go,包注释明确其职责为 "solving the DNS-01 challenge using Dyn Managed DNS"。
二、快速上手:一条命令签发通配符证书
在配置好以下三个必填环境变量后,即可直接使用 lego CLI 发起证书申请。官方文档给出的示例命令如下:
DYN_CUSTOMER_NAME=xxxxxx \
DYN_USER_NAME=yyyyy \
DYN_PASSWORD=zzzz \
lego run --dns dyn -d '*.example.com' -d example.com
命令要点:
--dns dyn:指定使用 Dyn 提供商解决 DNS-01 挑战;-d '*.example.com' -d example.com:同时申请通配符域名及其根域名(ACME 协议要求通配符证书必须同时覆盖根域,因为通配符只能匹配单级子域);- lego 会自动完成 TXT 记录的写入、等待 DNS 传播、向 CA 提交校验,并在校验完成后清理 TXT 记录。
从源码看,--dns 参数会在 providers/dns/dns_providers_test.go 中 NewDNSChallengeProviderByName("dyn") 这样的工厂函数中被解析为对应的提供商实例,而该函数在构建 DNSProvider 时会调用 NewDNSProvider() 读取环境变量(见 providers/dns/dyn/dyn.go)。
三、凭据配置:三个必填环境变量
Dyn 提供商要求提供三组凭据,对应 Dyn 账户体系中的客户名(Customer Name)、用户名(User Name)和密码(Password):
| 环境变量名 | 说明 |
|---|---|
DYN_CUSTOMER_NAME |
客户名称(Customer name) |
DYN_USER_NAME |
用户名(User name) |
DYN_PASSWORD |
密码(Password) |
这三个变量在源码中以常量形式定义在 providers/dns/dyn/dyn.go:
const (
envNamespace = "DYN_"
EnvCustomerName = envNamespace + "CUSTOMER_NAME"
EnvUserName = envNamespace + "USER_NAME"
EnvPassword = envNamespace + "PASSWORD"
...
)
在 NewDNSProvider() 中,三者通过 env.Get(EnvCustomerName, EnvUserName, EnvPassword) 一次性读取,任何一个缺失都会返回错误,且错误信息会明确指出缺少哪个变量(见 providers/dns/dyn/dyn_test.go 的测试用例):
dyn: some credentials information are missing: DYN_CUSTOMER_NAME,DYN_USER_NAME,DYN_PASSWORD
3.1 从文件读取凭据(_FILE 后缀)
所有环境变量名都可以加上 _FILE 后缀,改为从一个文件中读取值。例如:
DYN_CUSTOMER_NAME_FILE=/etc/lego/dyn/customer \
DYN_USER_NAME_FILE=/etc/lego/dyn/user \
DYN_PASSWORD_FILE=/etc/lego/dyn/pass \
lego run --dns dyn -d '*.example.com' -d example.com
这一机制适用于密码、密钥等敏感信息,避免在 shell 历史或进程环境中暴露明文。它由 platform/env 包统一实现,是 lego 所有 DNS 提供商共享的能力,相关通用说明见 docs/content/dns/_index.md 中的 "Configuration and credentials" 一节。
四、附加配置:传播等待与超时调优
除了必填凭据,Dyn 提供商还支持四个可选环境变量,用于控制 API 超时和 DNS 传播等待行为:
| 环境变量名 | 说明 | 默认值 |
|---|---|---|
DYN_HTTP_TIMEOUT |
API 请求超时(秒) | 10 |
DYN_POLLING_INTERVAL |
DNS 传播检查的轮询间隔(秒) | 2 |
DYN_PROPAGATION_TIMEOUT |
DNS 传播最大等待时间(秒) | 60 |
DYN_TTL |
用于 DNS 挑战的 TXT 记录 TTL(秒) | 120 |
这些默认值并非写死在文档中,而是与 lego 的 DNS-01 挑战通用常量一一对应(见 challenge/dns01/dns_challenge.go):
const (
DefaultPropagationTimeout = 60 * time.Second
DefaultPollingInterval = 2 * time.Second
DefaultTTL = 120
)
在 NewDefaultConfig()(providers/dns/dyn/dyn.go)中,这些默认值通过 env.GetOrDefaultInt / env.GetOrDefaultSecond 被赋予各配置项,DYN_HTTP_TIMEOUT 则单独作用于 http.Client 的超时时间:
func NewDefaultConfig() *Config {
return &Config{
TTL: env.GetOrDefaultInt(EnvTTL, dns01.DefaultTTL),
PropagationTimeout: env.GetOrDefaultSecond(EnvPropagationTimeout, dns01.DefaultPropagationTimeout),
PollingInterval: env.GetOrDefaultSecond(EnvPollingInterval, dns01.DefaultPollingInterval),
HTTPClient: &http.Client{
Timeout: env.GetOrDefaultSecond(EnvHTTPTimeout, 10*time.Second),
},
}
}
4.1 各参数的实战意义
DYN_PROPAGATION_TIMEOUT:TXT 记录写入后,lego 会持续轮询公共 DNS,直到记录在全球范围内可查询,超过该时长则报错。如果您的域名 NS 较多、传播较慢,可适当调大,例如DYN_PROPAGATION_TIMEOUT=120;DYN_POLLING_INTERVAL:每次轮询之间的间隔。调小可加快校验速度,但会增加对 DNS 的查询频率;DYN_TTL:写入的 TXT 记录的 TTL 值。TTL 越大,DNS 缓存时间越长,传播等待时间也可能越长;在临时记录场景下保持默认 120 秒即可;DYN_HTTP_TIMEOUT:与 Dyn REST API 通信的 HTTP 客户端超时。当 API 响应缓慢或网络不佳时,可调大此值避免请求被过早取消。
DNSProvider 实现了 challenge.ProviderTimeout 接口(见 providers/dns/dyn/dyn.go),Timeout() 方法返回的正是 PropagationTimeout 与 PollingInterval,lego 的 dns01 挑战调度器在 Solve 阶段会读取这两个值来驱动传播等待(见 challenge/dns01/dns_challenge.go)。
五、源码视角:一次 DNS-01 挑战的完整 API 调用链
Dyn 提供商的实现并不复杂,其核心流程分布在 providers/dns/dyn/dyn.go(对外接口)与 internal 子包(API 客户端)中。理解这条调用链有助于排障和二次开发。
5.1 挑战前置:Present(写入 TXT 记录)
Present 方法(providers/dns/dyn/dyn.go)在挑战开始时被调用,共四步:
- 计算挑战信息:通过
dns01.GetChallengeInfo得到_acme-challenge.<domain>形式的有效 FQDN 与 TXT 记录值(基于 Key Authorization 计算); - 定位所属 Zone:
dns01.DefaultClient().FindZoneByFqdn解析出域名所在的 Dyn 托管 Zone; - 登录并写记录:
CreateAuthenticatedContext完成会话登录,随后AddTXTRecord(ctxAuth, authZone, fqdn, value, ttl)调用 Dyn API 创建 TXT 记录; - 发布并登出:Dyn 的改动需显式
Publish才会生效(备注为 "Added TXT record for ACME dns-01 challenge using lego client"),最后Logout销毁会话。
对应 API 端点在 providers/dns/dyn/internal/client.go 中可见,其基础地址为 https://api.dynect.net/REST(defaultBaseURL 常量):
| 操作 | HTTP 方法与路径 | 源码函数 |
|---|---|---|
| 登录 | POST /Session |
login(见 session.go) |
| 创建 TXT 记录 | POST /TXTRecord/{zone}/{fqdn} |
AddTXTRecord |
| 发布 Zone | PUT /Zone/{zone} |
Publish |
| 删除 TXT 记录 | DELETE /TXTRecord/{zone}/{fqdn} |
RemoveTXTRecord |
| 登出 | DELETE /Session |
Logout |
请求体结构定义在 providers/dns/dyn/internal/types.go:创建记录时提交 {"rdata":{"txtdata": value}, "ttl": "120"}(TTL 以字符串形式传入),APIResponse 则统一解析 status(success/failure/incomplete)、data、job_id 与 msgs 字段。
5.2 挑战收尾:CleanUp(删除 TXT 记录)
CleanUp 方法(providers/dns/dyn/dyn.go)与 Present 对称:定位 Zone → 登录 → RemoveTXTRecord 删除记录 → Publish(备注 "Removed TXT record for ACME dns-01 challenge using lego client")→ Logout。这样证书签发完成后,DNS 中不会残留任何挑战记录。
5.3 会话机制:Token 鉴权
Dyn API 使用会话 Token 而非在每个请求中重复提交密码。CreateAuthenticatedContext(providers/dns/dyn/internal/session.go)先调用 login 换取 token,将其存入 context,后续请求通过 getToken 取出并以 Auth-Token 请求头携带(见 providers/dns/dyn/internal/client.go 的 newJSONRequest)。每个 Present/CleanUp 周期独立完成"登录-操作-登出",保证会话生命周期最小化。
5.4 已知限制:HTTP 307 尚未支持
在 providers/dns/dyn/internal/client.go 的响应处理中,若 API 返回 307 Temporary Redirect,客户端会直接报错:
API request returned HTTP 307. This is currently unsupported
代码注释标明这是 TODO 项。Dyn 的长时间运行任务(long running jobs)可能触发 307,遇到该错误时说明当前 lego 版本尚不兼容此类任务响应。
5.5 测试与模拟数据
providers/dns/dyn 包内置了完整的单元测试与 live 测试:
- providers/dns/dyn/dyn_test.go:覆盖
NewDNSProvider的环境变量缺失校验(逐项验证DYN_CUSTOMER_NAME/DYN_USER_NAME/DYN_PASSWORD缺失时的报错信息)、NewDNSProviderConfig的凭据校验,以及TestLivePresent/TestLiveCleanUp两个需真实凭据的线上测试(未设置环境时自动跳过); - providers/dns/dyn/internal/client_test.go 与 providers/dns/dyn/internal/fixtures 目录下的
login.json、create-txt-record.json、publish.json,用于模拟 Dyn API 的登录、建记录、发布响应,验证客户端解析逻辑。
六、以库方式集成:在 Go 代码中使用 Dyn 提供商
除了 CLI,lego 也允许在自有 Go 程序中以库方式使用 Dyn 提供商。NewDNSProviderConfig(providers/dns/dyn/dyn.go)接受一个 Config 结构体,方便以编程方式注入配置:
package main
import (
"time"
"github.com/go-acme/lego/v5/providers/dns/dyn"
)
func main() {
config := dyn.NewDefaultConfig()
config.CustomerName = "your-customer"
config.UserName = "your-user"
config.Password = "your-password"
config.PropagationTimeout = 60 * time.Second
config.PollingInterval = 2 * time.Second
config.TTL = 120
provider, err := dyn.NewDNSProviderConfig(config)
if err != nil {
panic(err)
}
// 将 provider 传入 lego 的 certificate 签发流程…
_ = provider
}
注意事项:
Config结构体字段与文档中的环境变量一一对应:CustomerName、UserName、Password、PropagationTimeout、PollingInterval、TTL,另有可自定义的HTTPClient;- 凭据任一为空时返回错误
dyn: credentials missing(与测试用例 providers/dns/dyn/dyn_test.go 一致); - 创建实例时,HTTP 客户端会被
clientdebug.Wrap包裹(providers/dns/dyn/dyn.go),便于输出调试信息。
七、总结与排障速查
使用 Dyn 提供商时最常见的三类问题及定位方法:
- 报
some credentials information are missing:检查DYN_CUSTOMER_NAME、DYN_USER_NAME、DYN_PASSWORD是否全部设置且非空,错误信息会直接列出缺失的变量名; - 报
could not find zone for domain:说明dns01.FindZoneByFqdn未在 Dyn 托管 Zone 中找到域名,请确认该域名确实托管于 Dyn Managed DNS,且 Zone 名称与域名后缀匹配; - 报
API request returned HTTP 307:当前版本尚未支持 Dyn 的 307 长任务响应,属于 providers/dns/dyn/internal/client.go 中标注的已知限制。
Dyn 提供商是 lego 众多 DNS 提供商中结构清晰、接入简单的一个:三个凭据变量、四个可选参数即可投入使用;其"登录 → 写记录 → 发布 → 登出"的完整生命周期在源码与测试中均有迹可循,适合作为研究 lego DNS 提供商架构的入门范本。