使用 lego 的 Hetzner DNS Provider 签发 ACME 证书：配置、凭据与源码实现解析

网络安全密码学【免费下载链接】legoLets Encrypt/ACME client and library written in Go项目地址https://gitcode.com/gh_mirrors/le/lego点击查看免费下载本指南完整讲解 Go 编写的 Lets Encrypt/ACME 客户端 lego 中 Hetzner DNS 提供商provider code:hetzner的配置与使用包括获取 API Token、通过 DNS-01 挑战为域名含通配符域名签发证书的命令行示例、全部可调环境变量及其默认值、_FILE后缀与 dotenv 等凭据加载方式并结合仓库源码剖析其底层调用链Hetzner Cloud API 的 RRSet 操作与 action 轮询机制帮助你快速落地并在遇到问题时能定位到具体实现。Hetzner Provider 概览Hetzner 是 lego 官方内置的 DNS-01 挑战提供商之一自v3.7.0起可用见 hetzner.toml。它的作用是在 Hetzner DNS 中自动创建/删除 ACME 挑战所需的TXT记录从而让 lego 无需人工干预即可完成 DNS-01 验证并签发证书。在 lego 的 DNS 提供商目录docs/content/dns/_index.md中Hetzner 被登记为属性值Code命令行中使用名hetzner引入版本v3.7.0官方站点hetzner.com从源码结构看providers/dns/hetzner/该 provider 由统一入口hetzner.go对接到两套内部实现internal/hetznerv1/基于Hetzner Cloud APIhttps://api.hetzner.cloud/v1使用HETZNER_API_TOKEN是当前推荐路径internal/legacy/基于旧的Hetzner DNS APIhttps://dns.hetzner.com使用HETZNER_API_KEY已被标记为废弃deprecated。两套实现都实现了 lego 的challenge.ProviderTimeout接口Present/CleanUp/Timeout对外行为一致下文会分别说明其内部差异。快速开始签发通配符证书在 Hetzner Cloud 控制台创建 API Token 后使用官方文档给出的命令即可发起证书签发HETZNER_API_TOKENxxxxxxxxxxxxxxxxxxxxx \ lego run --dns hetzner -d *.example.com -d example.com要点说明--dns hetzner指定使用本 provider-d等价于--domains声明要签发证书的域名同时给出*.example.com与example.com可签发覆盖根域与所有子域的通配符证书这正是 DNS-01 挑战相对 HTTP-01 的核心优势——无需对外暴露 80/443 端口。lego 会自动完成在 Hetzner 中添加挑战TXT记录 → 等待 DNS 传播 → 向 ACME 服务器发起验证 → 验证通过后清理TXT记录。若想先了解该 provider 支持的全部 CLI 选项可运行lego run --help查看--dns相关参数详见参考文档 ref-flags。凭据配置HETZNER_API_TOKENHetzner provider 唯一必需的凭据环境变量是HETZNER_API_TOKENAPI token可在 Hetzner Cloud 项目中创建并授予 DNS 读写权限。基础用法与_FILE后缀所有凭据类环境变量都支持两种取值方式直接给值HETZNER_API_TOKENxxxxxxxxxxxxxxxxxxxxx lego run --dns hetzner -d example.com引用文件变量名追加_FILE后缀文件内容即凭据值文件内只能包含该值本身HETZNER_API_TOKEN_FILE/etc/lego/hetzner_token \ lego run --dns hetzner -d example.com该机制对后文所有HETZNER_*变量均适用相关约定详见 DNS Providers 文档 的 Configuration and Credentials 一节。使用 dotenv 文件当凭据较多或希望与命令解耦时可用--env-file加载 dotenv 文件格式为KEYvalue每行一个lego run --dns hetzner -d example.com --env-file .env.hetzner.env.hetzner内容示例HETZNER_API_TOKENxxxxxxxxxxxxxxxxxxxxx HETZNER_TTL120使用配置文件.lego.yml如果使用 lego 的 YAML 配置文件见 file-configuration可在 DNS 挑战段声明 provider并通过envFile指定 dotenv 路径challenges: hetzner-challenge: dns: provider: hetzner envFile: .env.hetzner certificates: example: domains: - example.com - *.example.com之后直接运行lego即可。凭据缺失时的行为从测试用例hetzner_test.go可以看到若HETZNER_API_TOKEN与HETZNER_API_KEY均为空NewDNSProvider()会返回错误hetzner: some credentials information are missing: HETZNER_API_TOKEN而在NewDNSProviderConfig路径下则返回hetzner: credentials missing见 hetzner.go。因此排错时应优先检查 Token 是否已正确注入环境。附加配置参数除凭据外Hetzner provider 还支持以下可调参数均通过环境变量设置同样支持_FILE后缀环境变量说明默认值HETZNER_HTTP_TIMEOUTAPI 请求超时秒30HETZNER_POLLING_INTERVALDNS 传播检查间隔秒2HETZNER_PROPAGATION_TIMEOUT等待 DNS 传播的最大时长秒60HETZNER_TTLDNS 挑战 TXT 记录的 TTL秒120这些默认值在源码中有明确落点HETZNER_HTTP_TIMEOUT30s见 hetzner.go构造http.Client时读取。HETZNER_POLLING_INTERVAL2s与HETZNER_PROPAGATION_TIMEOUT60s直接对应 lego 全局常量dns01.DefaultPollingInterval与dns01.DefaultPropagationTimeout见 dns_challenge.go。HETZNER_TTL120s对应dns01.DefaultTTL见 dns_challenge.go。配置示例HETZNER_API_TOKENxxxxxxxxxxxxxxxxxxxxx \ HETZNER_TTL60 \ HETZNER_PROPAGATION_TIMEOUT120 \ HETZNER_POLLING_INTERVAL2 \ HETZNER_HTTP_TIMEOUT30 \ lego run --dns hetzner -d example.com注意 TTL 的下限约束在 legacyHETZNER_API_KEY实现中TTL 被硬性要求不小于 60 秒否则NewDNSProviderConfig直接返回错误invalid TTL, TTL (N) must be greater than 60见 internal/legacy/hetzner.go。因此当你想调低 TTL 加速传播时需留意 legacy 路径会拒绝小于 60 的值。源码级实现解析双 API 的自动选择逻辑统一入口NewDNSProvider()根据环境变量决定走哪套实现hetzner.go检测到HETZNER_API_TOKEN→ 使用hetznerv1Hetzner Cloud API否则检测到HETZNER_API_KEY→ 使用legacy旧 Hetzner DNS API并打印警告APIKey (legacy Hetzner DNS API) is deprecated, please use APIToken (Hetzner Cloud API) instead.两者都未设置 → 尝试创建hetznerv1provider最终因缺少凭据而失败。如果同时设置了 Token 与 KeyToken 优先见测试用例 success (both)hetzner_test.go。因此新用户应统一使用HETZNER_API_TOKENHETZNER_API_KEY仅用于兼容旧脚本。v1基于 Cloud API 的 RRSet 操作hetznerv1实现hetznerv1.go的挑战流程如下定位授权区dns01.DefaultClient().FindZoneByFqdn()找到域名所属 zone随后用dns01.ExtractSubDomain()拆出子域并用idna.ToASCII处理国际化域名IDN。添加记录调用AddRRSetRecords通过POST /zones/{zone}/rrsets/{name}/TXT/actions/add_records在现有 RRSet 上追加挑战记录internal/client.go。TXT 记录值会先经strconv.Quote包装符合 TXT 记录的引号规范。等待 action 完成Hetzner Cloud API 的 RRSet 修改是异步的返回一个ActionwaitAction以HETZNER_POLLING_INTERVAL为周期轮询GET /actions/{id}直到状态变为success若为error或running持续超过HETZNER_PROPAGATION_TIMEOUT则返回错误hetznerv1.go。轮询采用指数退避backoff库实现。验证后清理CleanUp调用RemoveRRSetRecordsPOST .../actions/remove_records删除相同记录同样等待 action 完成。请求鉴权通过 OAuth2 静态 TokenBearer注入internal/client.go请求/响应的 JSON 编解码与错误解析都在该 client 中完成错误信息会带上 Hetzner API 返回的code、message与字段级详情。legacy基于旧 DNS API 的记录操作legacy实现internal/legacy/hetzner.go的流程更直接通过GetZoneID在GET /api/v1/zones?name...中按域名找到 zone IDCreateRecord直接POST /api/v1/records创建 TXT 记录CleanUp先GetTxtRecord按名称与值匹配记录再DeleteRecord删除DELETE /api/v1/records/{id}。鉴权方式是把 API Key 放在自定义请求头Auth-API-Token中internal/client.go。由于该 API 已废弃建议尽快迁移到HETZNER_API_TOKEN。排错与提示DNS 传播检查lego 在添加记录后等待HETZNER_PROPAGATION_TIMEOUT默认 60s若你的 DNS 服务器刷新较慢可适当调大该值与HETZNER_POLLING_INTERVAL的比值。zone 定位失败报错could not find zone for domain时先确认该域名确实托管在 Hetzner DNS 且 Token 有对应 zone 的权限见 hetznerv1.go。多 SOA 环境当 zone 同时存在内网与公网解析多个权威服务器时可用--dns.resolvers指定外部权威解析器例如lego run --dns hetzner --dns.resolvers 9.9.9.9:53 -d example.com避免传播检测命中内网记录详见 DNS-01 挑战指南 与 tips。请求超时HETZNER_HTTP_TIMEOUT只控制单次 HTTP 请求超时传播等待总时长由HETZNER_PROPAGATION_TIMEOUT控制两者职责不同。调试lego 默认会在出错时打印 HTTP 请求/响应摘要client 层通过clientdebug.Wrap包装可结合 log 的调试级别观察实际 API 交互。参考文档Hetzner provider 自动生成文档本文依据DNS Providers 总览与环境变量约定DNS-01 挑战使用指南Provider 入口实现v1 实现与 RRSet 操作legacy 实现Provider 选择逻辑测试配置模板 hetzner.toml赞分享网络安全密码学【免费下载链接】legoLets Encrypt/ACME client and library written in Go项目地址https://gitcode.com/gh_mirrors/le/lego点击查看免费下载相关推荐lego 使用 Epik DNS Provider 签发证书配置、参数与源码解析lego 使用 Epik DNS Provider 签发证书配置、参数与源码解析 导读 本文聚焦 legoLets Encrypt/ACME client网络安全密码学lego 使用 Bluecat v2 DNS Provider 签发证书配置、原理与源码级解析lego 使用 Bluecat v2 DNS Provider 签发证书配置、原理与源码级解析 本篇指南聚焦 legoLets Encrypt/ACME网络安全密码学Mordecai API完全指南10个高级用法提升地理数据处理效率Mordecai API完全指南10个高级用法提升地理数据处理效率 Mordecai是一个强大的Python地理解析库专门用于从英文文本中提取地名并将其解析网络安全密码学上一篇如何把魔百盒电视盒改成 Linux 服务器下一篇vinext是什么用Vite插件运行Next.js应用的终极入门指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考