Dyn DNS 提供商接入指南:用 lego 通过 DNS-01 挑战签发通配符证书

原创2026-09-23 13:51:281,821 阅读
文章标签:应用安全网络安全密钥管理CLI

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)在挑战开始时被调用,共四步:

  1. 计算挑战信息:通过 dns01.GetChallengeInfo 得到 _acme-challenge.<domain> 形式的有效 FQDN 与 TXT 记录值(基于 Key Authorization 计算);
  2. 定位所属 Zone:dns01.DefaultClient().FindZoneByFqdn 解析出域名所在的 Dyn 托管 Zone;
  3. 登录并写记录:CreateAuthenticatedContext 完成会话登录,随后 AddTXTRecord(ctxAuth, authZone, fqdn, value, ttl) 调用 Dyn API 创建 TXT 记录;
  4. 发布并登出: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 提供商时最常见的三类问题及定位方法:

  1. 报 some credentials information are missing:检查 DYN_CUSTOMER_NAME、DYN_USER_NAME、DYN_PASSWORD 是否全部设置且非空,错误信息会直接列出缺失的变量名;
  2. 报 could not find zone for domain:说明 dns01.FindZoneByFqdn 未在 Dyn 托管 Zone 中找到域名,请确认该域名确实托管于 Dyn Managed DNS,且 Zone 名称与域名后缀匹配;
  3. 报 API request returned HTTP 307:当前版本尚未支持 Dyn 的 307 长任务响应,属于 providers/dns/dyn/internal/client.go 中标注的已知限制。

Dyn 提供商是 lego 众多 DNS 提供商中结构清晰、接入简单的一个:三个凭据变量、四个可选参数即可投入使用;其"登录 → 写记录 → 发布 → 登出"的完整生命周期在源码与测试中均有迹可循,适合作为研究 lego DNS 提供商架构的入门范本。

登录后查看全文
lego