Alwaysdata DNS 提供商接入指南:使用 lego 完成 DNS-01 挑战与通配符证书签发

原创2026-09-23 19:29:411,845 阅读
文章标签:应用安全网络安全密钥管理CLI

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:

  1. 登录 Alwaysdata 账户,进入账户设置中与 API 相关的页面;
  2. 生成(或复制)API Key,形如 xxxxxxxxxxxxxxxxxxxxx;
  3. 如果需要操作非主账户下的域名(例如子账户),还需要记录对应的账户名(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 挑战的「写入」阶段,调用链为:

  1. dns01.GetChallengeInfo(ctx, domain, keyAuth) 计算出挑战所需的权威 FQDN 与 TXT 记录值 info.Value;
  2. findZone()(alwaysdata.go)调用 ListDomains 拉取账户下全部域名,用 dns01.UnFqdnDomainsSeq 对 FQDN 逐级向上匹配最接近的托管区域;
  3. dns01.ExtractSubDomain() 从 FQDN 中剥离区域名,得到子域前缀(如 _acme-challenge);
  4. 构造 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。

登录后查看全文
lego