lego 对接 SelfHost.(de|eu) DNS 提供商：DNS-01 挑战的配置指南与源码实现解析

网络安全密码学【免费下载链接】legoLets Encrypt/ACME client and library written in Go项目地址https://gitcode.com/gh_mirrors/le/lego点击查看免费下载SelfHost.(de|eu) 是 lego 内置的 DNS-01 挑战提供商之一从 v4.19.0 起可用代码名selfhostde。由于其后台不提供创建或删除 TXT 记录的官方 API只能通过一个非官方、未文档化的端点更新已存在的 TXT 记录因此使用该提供商前必须先手工准备记录与记录 ID 映射。本文将以 docs/content/dns/zz_gen_selfhostde.md 为核心骨架结合 providers/dns/selfhostde 下的源码与测试完整讲解环境变量配置、映射格式、通配符场景处理、底层调用链与常见报错让你能直接照做跑通证书签发。一、概述这是什么解决什么问题SelfHost.(de|eu) 是一个以德国市场为主的域名与托管服务商。lego 通过selfhostde这个 DNS 提供商标识接入其更新 TXT 记录的私有端点从而完成 ACME DNS-01 挑战——即在_acme-challenge.domain记录中写入验证 token等待 CA 校验后签发证书。需要特别强调的限制该信息同时出现在文档与 providers/dns/selfhostde/internal/readme.md 中SelfHost.de 没有创建或删除 TXT 记录的 API只有一个非官方且未文档化的端点用于更新已存在的 TXT 记录。因此整个流程是半自动化的手工建记录 → 提取记录 ID → 配置映射 → lego 只负责更新值。这正是SELFHOSTDE_RECORDS_MAPPING这个特殊环境变量存在的原因。二、快速上手一条命令发起证书申请使用--dns selfhostde即可选择该提供商。官方文档给出的最小示例为SELFHOSTDE_USERNAMExxx \ SELFHOSTDE_PASSWORDyyy \ SELFHOSTDE_RECORDS_MAPPINGmy.example.com:123 \ lego run --dns selfhostde -d *.example.com -d example.com参数说明-d *.example.com为通配符域名申请证书-d example.com同时为主域名申请证书三条环境变量是必填凭证见下一节lego run会自动完成订单创建、DNS-01 挑战、签发与保存证书的完整流程。三、凭证Credentials与环境变量所有配置均通过环境变量传入这是 lego 所有 DNS 提供商统一的设计参见 docs/content/dns/_index.md 的 Configuration and Credentials 一节。必填凭证环境变量名说明SELFHOSTDE_USERNAMESelfHost 账号用户名SELFHOSTDE_PASSWORD账号密码SELFHOSTDE_RECORDS_MAPPING域名与记录 ID 的映射如example.com:123:456,example.org:789,foo.example.com:147这三项缺一不可。从 selfhostde.go 的NewDNSProvider()可以看到构造时会调用env.Get(EnvUsername, EnvPassword, EnvRecordsMapping)统一读取任何一个缺失都会直接报错selfhostde_test.go 中的用例验证了缺失时的错误信息例如selfhostde: some credentials information are missing: SELFHOSTDE_USERNAME。_FILE后缀从文件读取敏感值所有环境变量名都可以追加_FILE后缀改从文件读取值便于在容器、systemd 或 CI 中注入密钥而不暴露在命令行SELFHOSTDE_USERNAME_FILE/path/to/username \ SELFHOSTDE_PASSWORD_FILE/path/to/password \ SELFHOSTDE_RECORDS_MAPPING_FILE/path/to/mapping \ lego run --dns selfhostde -d example.com对应文件内容只需包含纯值即可例如/path/to/password文件中就是一行密码。该机制同样适用于下面的附加配置变量详见 docs/content/dns/_index.md 的 _FILEsuffix 小节。四、附加配置Additional Configuration环境变量名说明默认值SELFHOSTDE_HTTP_TIMEOUTAPI 请求超时秒30SELFHOSTDE_POLLING_INTERVAL两次 DNS 传播检查的间隔秒30SELFHOSTDE_PROPAGATION_TIMEOUTDNS 传播最大等待时间秒240SELFHOSTDE_TTL用于 DNS 挑战的 TXT 记录 TTL秒120这些默认值在源码NewDefaultConfig()中均有对应实现selfhostde.goTTL 默认取dns01.DefaultTTL120 秒传播超时默认4 * time.Minute240 秒轮询间隔默认30 * time.SecondHTTP 客户端默认超时30 * time.Second。其中传播超时与轮询间隔通过DNSProvider.Timeout()方法selfhostde.go上报给 lego 的传播等待逻辑当你发现记录已更新但 CA 校验仍失败时可适当调大SELFHOSTDE_PROPAGATION_TIMEOUT或调小SELFHOSTDE_POLLING_INTERVAL以应对传播延迟抖动。五、核心前置步骤手工创建 TXT 记录由于没有创建/删除记录的 API在真正运行 lego 之前你必须先在 SelfHost 的 DNS 管理界面为每一个目标域名预先创建好_acme-challenge记录若目标域名不使用通配符例如my.example.org需要1 条TXT 记录_acme-challenge.my.example.org若目标域名使用通配符例如*.my.example.org需要2 条TXT 记录_acme-challenge.my.example.org因为通配符挑战会同时涉及通配域名本身及其基域。创建完成后进入记录编辑页面找到每条记录的IDSelfHost 后台为每条记录分配的标识符。六、SELFHOSTDE_RECORDS_MAPPING格式详解映射变量遵循以下格式domain_A:record_id_A1:record_id_A2,domain_B:record_id_B1:record_id_B2,domain_C:record_id_C1:record_id_C2每组域名 记录 ID之间用逗号,分隔域名与记录 ID、多个记录 ID 之间用冒号:分隔单个域名最多可配置2 个记录 ID应对通配符双记录场景。官方示例假设你要为my.example.org、*.my.example.org和other.example.org签发/续期证书则需准备_acme-challenge.my.example.org的2 条记录覆盖通配符_acme-challenge.other.example.org的1 条记录。最终的映射变量为SELFHOSTDE_RECORDS_MAPPINGmy.example.com:123:456,other.example.com:789文档中此处的域名写法以你实际申请的域名为准123、456、789均为后台可见的记录 ID 占位符。解析规则与校验源码视角mapping.go 中的parseRecordsMapping实现了这套语法行为要点解析前会先去除所有空格因此example.com:123, example.org:456这类带空格的写法也能正确解析mapping_test.go 的用例即覆盖了空格场景每个域名对应的记录 ID 数量超过 2 个会报错too many record IDs for one domain: ...以下错误写法都会被拒绝并给出明确提示缺冒号missing :: example.com、空映射empty mapping、以冒号/逗号开头或结尾first char is .../last char is ...等。双记录 ID 的轮询机制当同一个域名配置了 2 个记录 ID通配符场景时lego 会按**轮询round-robin**方式依次使用。Seq.Next()的实现mapping.go保证单个 ID 时恒返回该 ID多个 ID 时按顺序循环取用。Present()中通过getSeqNext(effectiveDomain, fqdn)取号selfhostde.go并在映射表中找不到有效域名时回退到 FQDN 键再查一次。七、底层调用链lego 是如何更新 TXT 记录的挑战阶段PresentPresent()selfhostde.go完成三步由dns01.GetChallengeInfo计算挑战信息得到_acme-challenge子域名与验证值从映射中取出或轮询出一个记录 ID调用内部客户端UpdateTXTRecord(ctx, recordID, info.Value)把验证值写入该记录并将token → recordID存入内存 map供清理阶段使用。清理阶段CleanUpCleanUp()selfhostde.go则根据之前保存的 token 找到记录 ID调用UpdateTXTRecord(ctx, recordID, empty)把记录内容置空——注意这里并没有删除记录只是清空内容这与无删除 API的限制一致。HTTP 客户端非官方端点的真实请求内部客户端定义在 providers/dns/selfhostde/internal/client.go默认端点https://account.selfhost.de/cgi-bin/api.pl请求方式HTTP GET查询参数为username、password、rid记录 ID、content要写入的内容非 2xx 响应会被包装为unexpected status code: [status code: ...]错误。client_test.go 通过 mock 服务器严格校验了请求必须携带rid、content、username、password四个参数同时验证了 400 响应时的错误文本。顺带一提internal/readme.md 明确说明SelfHost 官方公开的 DynDNS/ddns API 文档PDF描述的是另一套端点本客户端并不使用不要误配。八、源码与测试给出的健壮性保障构造期校验NewDNSProviderConfigselfhostde.go依次校验配置非空、用户名/密码非空、映射非空、且每个域名至少有一个记录 ID任一项不满足都会返回带selfhostde:前缀的错误。映射解析测试mapping_test.go 覆盖单域名单 ID、多域名、双 ID、空格容错以及十余种非法格式错误信息均可在运行go test ./providers/dns/selfhostde/...时复现。live 测试selfhostde_test.go 提供TestLivePresent/TestLiveCleanUp只有设置了真实凭证环境变量tester.NewEnvTest才会执行可用于在真实账号上验证写值与清空流程。九、常见问题与排查建议现象可能原因处理方式some credentials information are missing: SELFHOSTDE_...三项必填变量缺失补全SELFHOSTDE_USERNAME/SELFHOSTDE_PASSWORD/SELFHOSTDE_RECORDS_MAPPINGmalformed records mapping: ...映射语法错误缺冒号、超 2 个 ID、前后缀符号非法对照第六节格式修正或参考 mapping 解析测试中的错误提示missing record ID for ...映射中某域名没有记录 ID为该域名补上后台的真实记录 IDupdate DNS TXT record (id...): unexpected status code记录 ID 失效、账号无权限或端点临时异常核对记录 ID、检查账号凭证必要时调大SELFHOSTDE_HTTP_TIMEOUTCA 校验失败但记录已更新传播尚未完成调大SELFHOSTDE_PROPAGATION_TIMEOUT并确认记录 TTLSELFHOSTDE_TTL默认 120 秒符合预期十、小结SelfHost.(de|eu) 提供商是 lego DNS-01 体系中受限自动化的典型代表没有创建/删除 API只有更新已有记录的私有端点。掌握好三条必填环境变量、SELFHOSTDE_RECORDS_MAPPING的domain:id[:id]逗号分隔语法、以及通配符需要双记录 ID 的轮询机制再结合 providers/dns/selfhostde 源码对默认超时、请求格式与错误信息的理解即可顺利为普通域名与通配符域名签发并续期证书。赞分享网络安全密码学【免费下载链接】legoLets Encrypt/ACME client and library written in Go项目地址https://gitcode.com/gh_mirrors/le/lego点击查看免费下载相关推荐lo 库 NthOrEmpty 详解Go 泛型切片安全取值的零值兜底方案lo 库 NthOrEmpty 详解Go 泛型切片安全取值的零值兜底方案 lo.NthOrEmpty 是 Go 1.18 泛型函数库 lo https://网络安全密码学使用 Curanet DNS 提供商完成 lego 的 DNS-01 挑战配置指南与源码解析使用 Curanet DNS 提供商完成 lego 的 DNS 01 挑战配置指南与源码解析 本指南介绍如何在 lego https://link.gitco网络安全密码学使用 aisuite 调用本地 Ollama 模型零 API Key 的本地 Chat Completions 实战指南使用 aisuite 调用本地 Ollama 模型零 API Key 的本地 Chat Completions 实战指南 Ollama 让开发者可以完全在本地网络安全密码学上一篇Swift Package Manager 注册表配置移除指南swift package-registry unset 命令全解析下一篇Kata Containers VM 模板VM Templating原理、配置与实操指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考