Alwaysdata DNS 提供商接入指南:使用 lego 完成 DNS-01 挑战与通配符证书签发
Alwaysdata DNS 提供商接入指南:使用 lego 完成 DNS-01 挑战与通配符证书签发
导读
本文围绕 lego(Let's Encrypt/ACME 客户端与 Go 库)内置的 Alwaysdata DNS 提供商展开,完整讲解如何通过 Alwaysdata API 自动完成 DNS-01 挑战:包括 API Key 凭据获取、命令行签发通配符证书、全部可调环境变量(TTL、传播超时、轮询间隔、HTTP 超时等)的语义与默认值,并结合仓库源码剖析其「定位区域 → 添加 TXT 记录 → 等待传播 → 校验 → 清理记录」的完整实现链路与 API 调用细节。读完本文,你可以直接用一条命令为 *.example.com 签发通配符证书,也可以在自己的 Go 程序里以库的方式集成 Alwaysdata 提供商,还能在遇到认证失败、传播超时等问题时快速定位根因。
Alwaysdata DNS 提供商概览
Alwaysdata 是一家提供虚拟主机、域名与 DNS 托管服务的平台,其开放的 REST API(基地址为 https://api.alwaysdata.com/v1)允许程序化管理域名与 DNS 记录。lego 从 v4.31.0 起内置了该 DNS 提供商,提供商代码为 alwaysdata,对应文档由 providers/dns/alwaysdata/alwaysdata.toml 自动生成,源文档即 docs/content/dns/zz_gen_alwaysdata.md。
在 lego 的架构中,DNS-01 挑战由各 DNS 提供商的实现独立承担,所有提供商的统一入口由 providers/dns/zz_gen_dns_providers.go 汇总注册。Alwaysdata 提供商适合以下场景:
- 域名的 DNS 托管在 Alwaysdata,希望通过 API 自动添加/删除用于 ACME 验证的 TXT 记录,无需手动操作控制面板;
- 需要签发
*.example.com这类通配符证书(只能走 DNS-01 挑战); - 希望在证书到期前自动续期(配合 lego 的
renew命令)。
与 HTTP-01 相比,DNS-01 无需开放 80 端口、不依赖 Web 服务器,尤其适合纯 API 自动化场景。
前置准备:获取 API Key 与账户名
使用该提供商前,需要在 Alwaysdata 控制台生成 API Key:
- 登录 Alwaysdata 账户,进入账户设置中与 API 相关的页面;
- 生成(或复制)API Key,形如
xxxxxxxxxxxxxxxxxxxxx; - 如果需要操作非主账户下的域名(例如子账户),还需要记录对应的账户名(Account name);仅操作主账户域名时账户名可以省略。
从源码 internal/client.go 可以看到,该提供商实际调用的是 https://api.alwaysdata.com/v1 下的 domain 与 record 两组资源接口,因此 API Key 至少应具备读写域名的 DNS 记录权限(后续「底层实现」小节会给出具体端点)。
快速开始:一条命令签发通配符证书
拿到 API Key 后,将其导出为环境变量,即可直接运行 docs/content/dns/zz_gen_alwaysdata.md 中给出的标准命令:
ALWAYSDATA_API_KEY="xxxxxxxxxxxxxxxxxxxxx" \
lego run --dns alwaysdata -d '*.example.com' -d example.com
命令要点:
--dns alwaysdata指定使用 Alwaysdata 提供商完成 DNS-01 挑战;-d '*.example.com'请求签发通配符证书;-d example.com同时为裸域签发,通配符证书并不覆盖裸域,两者通常需要一起请求;- 首次使用还需补充注册参数,例如
--email you@example.com --accept-tos(具体以你使用的 lego 版本lego --help为准),并建议先用--server https://acme-staging-v02.api.letsencrypt.org/directory做一次预演,再切换到生产环境。
执行过程中 lego 会自动完成:查找域名所属区域 → 添加 _acme-challenge TXT 记录 → 等待 DNS 传播 → 向 ACME 服务器提交校验 → 校验通过后清理 TXT 记录。下面逐一说明驱动这一流程的配置项。
凭据配置(Credentials)
| 环境变量名 | 描述 |
|---|---|
ALWAYSDATA_API_KEY |
API Key(必填) |
对应源码 alwaysdata.go 中的 EnvAPIKey。缺少该变量时,NewDNSProvider() 会返回形如 alwaysdata: some credentials information are missing: ALWAYSDATA_API_KEY 的错误——这一点由 alwaysdata_test.go 中的 missing credentials 用例明确验证。
所有凭据/配置环境变量名都可以追加 _FILE 后缀,改为引用一个文件路径、由 lego 从文件中读取实际值,便于在容器、systemd 或 CI 场景中通过挂载 Secret 文件注入敏感信息,例如 ALWAYSDATA_API_KEY_FILE=/run/secrets/alwaysdata_key。关于这一机制的通用说明,参见 docs/content/dns/_index.md 中的「Configuration and credentials」小节。
附加配置(Additional Configuration)
| 环境变量名 | 描述 | 默认值 |
|---|---|---|
ALWAYSDATA_ACCOUNT |
Alwaysdata 账户名(非主账户场景必填) | 空 |
ALWAYSDATA_HTTP_TIMEOUT |
API 请求超时(秒) | 30 |
ALWAYSDATA_POLLING_INTERVAL |
DNS 传播检查的轮询间隔(秒) | 2 |
ALWAYSDATA_PROPAGATION_TIMEOUT |
等待 DNS 传播的最长时间(秒) | 60 |
ALWAYSDATA_TTL |
挑战 TXT 记录的 TTL(秒) | 120 |
这些参数对应 alwaysdata.go 中 ALWAYSDATA_ 命名空间下的一组环境变量常量,并在 NewDefaultConfig()(alwaysdata.go)中读取默认值。其中三个与传播相关参数的默认值,来自 DNS-01 通用常量 challenge/dns01/dns_challenge.go:
DefaultPropagationTimeout = 60 * time.Second:若你的 DNS 服务商解析较慢,可适当调大ALWAYSDATA_PROPAGATION_TIMEOUT,避免在记录尚未生效时校验失败;DefaultPollingInterval = 2 * time.Second:轮询间隔越小、检测越灵敏,但会略微增加 API 请求频率;DefaultTTL = 120:TTL 影响记录在全球 DNS 缓存中的存活时间;挑战记录校验前即被删除,较短的 TTL 通常足够,一般无需修改。
ALWAYSDATA_HTTP_TIMEOUT 控制对 Alwaysdata API 的单次 HTTP 请求超时(默认 30 秒),在 API 偶发缓慢时可适当放宽。上述变量同样支持 _FILE 后缀。
底层实现:源码级解析
1. 凭据校验与客户端构建
NewDNSProvider()(alwaysdata.go)从环境变量读取 API Key,并以 env.GetOrFile 方式读取账户名,然后调用 NewDNSProviderConfig() 构建实例。NewDNSProviderConfig()(alwaysdata.go)会拒绝 nil 配置,并通过 internal.NewClient() 创建 API 客户端——若 API Key 为空则直接返回 credentials missing。
2. 挑战发起(Present):添加 TXT 记录
Present()(alwaysdata.go)是 DNS-01 挑战的「写入」阶段,调用链为:
dns01.GetChallengeInfo(ctx, domain, keyAuth)计算出挑战所需的权威 FQDN 与 TXT 记录值info.Value;findZone()(alwaysdata.go)调用ListDomains拉取账户下全部域名,用dns01.UnFqdnDomainsSeq对 FQDN 逐级向上匹配最接近的托管区域;dns01.ExtractSubDomain()从 FQDN 中剥离区域名,得到子域前缀(如_acme-challenge);- 构造
RecordRequest(见 internal/types.go),字段包含domain(区域 ID)、name(子域)、type: "TXT"、value、ttl以及annotation: "lego",随后调用AddRecord完成创建。
测试夹具 record_add-request.json 展示了实际 POST 的请求体:
{
"domain": 132,
"name": "_acme-challenge",
"type": "TXT",
"value": "ADw2sEd82DUgXcQ9hNBZThJs7zVJkR5v9JeSbAb9mZY",
"ttl": 120,
"annotation": "lego"
}
3. 传播等待(Timeout)
Timeout()(alwaysdata.go)返回 PropagationTimeout 与 PollingInterval,lego 据此循环查询 DNS,直到 TXT 记录在全球解析中可见。Alwaysdata 提供商声明实现了 challenge.ProviderTimeout 接口(见 alwaysdata.go),因此可以自定义传播等待参数,以应对传播延迟波动。
4. 校验后清理(CleanUp):删除 TXT 记录
校验完成后,CleanUp()(alwaysdata.go)负责删除临时记录:同样先定位区域与子域,再调用 ListRecords(zoneID, subDomain) 列出该子域下所有记录(请求夹具见 records.json,其中包含 ID 为 789 的 _acme-challenge TXT 记录与一条无关的 A 记录),仅当记录类型为 TXT 且值与 info.Value 完全一致时才调用 DeleteRecord 删除——这样既精准清理本次挑战记录,又不会误删用户已有的其他记录。
5. API 客户端细节
internal/client.go 实现了对 Alwaysdata REST API 的封装:
- 基地址
https://api.alwaysdata.com/v1(L19); - 鉴权采用 HTTP Basic Auth(L117-L123):用户名即 API Key;若配置了账户名,用户名会拼接为
APIKeyaccount=<account>的形式; - 涉及四个端点:
GET /domain/(列出区域)、POST /record/(添加记录)、GET /record/?domain=<id>&name=<sub>(按区域与名字过滤查询记录)、DELETE /record/<id>/(删除记录); - 非 2xx 响应会包装为带状态码与响应体的错误,便于排查。
以上调用关系与端点路径均由 alwaysdata_test.go 中的 TestDNSProvider_Present、TestDNSProvider_CleanUp 等用例通过 mock 服务器逐条验证(例如 CleanUp 用例断言了 GET /record/ 必须携带 domain=132 与 name=_acme-challenge 两个查询参数)。
以 Go 库的形式集成
lego 同时是 Go 库,你可以在自己的程序中直接使用该提供商。参考 alwaysdata.go 导出的 API,最小用法如下:
import (
"github.com/go-acme/lego/v4/challenge"
"github.com/go-acme/lego/v4/providers/dns/alwaysdata"
)
// 方式一:从环境变量读取配置(ALWAYSDATA_API_KEY 等)
provider, err := alwaysdata.NewDNSProvider()
if err != nil {
// 处理凭据缺失等情况
}
// 方式二:程序化构造配置
config := alwaysdata.NewDefaultConfig()
config.APIKey = "xxxxxxxxxxxxxxxxxxxxx"
config.Account = "my-account" // 可选
config.TTL = 120 // 可选,默认 120
config.PropagationTimeout = 90 * time.Second // 可选,默认 60s
config.PollingInterval = 3 * time.Second // 可选,默认 2s
provider, err = alwaysdata.NewDNSProviderConfig(config)
if err != nil {
// 处理配置非法等情况
}
// 将其挂载到 lego 客户端,配合 ObtainCertificate 发起挑战
// client.Challenge.SetDNS01Provider(provider)
_ = challenge.ProviderTimeout(provider) // 提供方支持自定义传播等待
集成时注意:NewDNSProvider() 依赖环境变量注入凭据,适合与命令行/容器环境保持一致;NewDNSProviderConfig() 支持完全编程式配置,适合把配置纳入自有配置系统。
常见问题与排查
- 提示缺少
ALWAYSDATA_API_KEY:确认环境变量已导出,或改用ALWAYSDATA_API_KEY_FILE指向包含 Key 的文件;文件内容应为纯文本值。 - API 返回 401/认证失败:多为 API Key 错误,或是在非主账户场景下未设置
ALWAYSDATA_ACCOUNT。从源码可知,账户名会拼进 Basic Auth 用户名中,缺失时 API 会把请求视为主账户身份。 - 报错
domain not found:说明在GET /domain/返回的域名列表里没有匹配到待签发域名的托管区域,请确认该域名的 DNS 确实托管在 Alwaysdata,且 API Key 有权限访问该区域。 - 校验频繁超时:适当调大
ALWAYSDATA_PROPAGATION_TIMEOUT,并确认 Alwaysdata 的 DNS 传播速度;必要时结合ALWAYSDATA_POLLING_INTERVAL调节轮询粒度。 - 调试网络交互:lego 内置的
LEGO_HTTP_DEBUG类调试能力可输出请求/响应细节(具体变量名以对应版本文档为准),可据此核对上述四个端点的调用与状态码。
小结
Alwaysdata DNS 提供商是 lego 内置 DNS-01 解决方案之一:配置仅需一个 API Key,即可全自动完成通配符证书的签发、续期与挑战记录清理。通过本文你可以直接套用命令示例投入生产,也可以在遇到问题时依据 alwaysdata.go 与 internal/client.go 中的实现细节快速定位;若需了解 DNS-01 挑战与凭据机制的通用约定,可进一步阅读 docs/content/dns/_index.md。