- 网络安全
- CLI
- 后端
【免费下载链接】certbot
Certbot is EFF's tool to obtain certs from Let's Encrypt and (optionally) auto-enable HTTPS on your server. It can also act as a client for any other CA that uses the ACME protocol.
Certbot 的certbot-dns-dnsmadeeasy插件让用户能够通过 DNS Made Easy 的 API 自动完成 ACMEdns-01挑战——插件自动创建并清理用于验证的 TXT 记录，从而无需在服务器上开放 80 端口即可为任意域名（包括通配符域名）签发 Let's Encrypt 证书。读完本文，你将掌握该插件的安装方式、两个核心命令行参数、凭据文件的正确配置与安全防护，以及从源码层面理解 TXT 记录创建/删除的完整执行链路。
插件定位与工作原理
certbot-dns-dnsmadeeasy是 Certbot 官方维护的 DNS 认证插件之一。其核心职责在模块文档字符串中有明确定义（见 certbot-dns-dnsmadeeasy/src/certbot_dns_dnsmadeeasy/init.py）：
该插件通过调用 DNS Made Easy API，创建并在验证完成后删除 TXT 记录，来自动化完成
dns-01挑战（~acme.challenges.DNS01）。
整个流程不需要 Web 服务器参与，因此特别适合：
- 通配符域名（
*.example.com）证书签发； - 服务器不开放 80/443 端口、或证书目标不在本机的场景；
- 希望完全自动化、无需人工干预的证书续期场景。
从源码结构看，插件的Authenticator类继承自LexiconDNSAuthenticator（certbot/src/certbot/plugins/dns_common_lexicon.py），即底层通过开源库dns-lexicon与 DNS Made Easy 的 API 通信，而不是直接手写 HTTP 请求。
安装方式
文档明确说明：该插件默认不随 Certbot 安装。用户需要前往 certbot.eff.org 的安装指引页面，选择自己的操作系统并切换到Wildcard（通配符）标签页，按页面提示安装对应插件包。
以 pip 方式安装时，包名为certbot-dns-dnsmadeeasy。从 certbot-dns-dnsmadeeasy/pyproject.toml 可以看到其声明方式：
- 插件入口：
[project.entry-points."certbot.plugins"]中将dns-dnsmadeeasy指向certbot_dns_dnsmadeeasy._internal.dns_dnsmadeeasy:Authenticator（pyproject.toml），Certbot 据此识别并加载该插件； - Python 版本要求：
requires-python = ">=3.10"； - 运行时依赖（setup.py）：
dns-lexicon>=3.14.1，以及与本插件同版本的acme与certbot（非 Snap 构建时）。其中dns-lexicon>=3.14的版本要求与源码中"使用 Client 作为上下文管理器"的写法直接对应（见下文源码解析）。
命令行参数详解
该插件只暴露两个命令行参数，均以--dns-dnsmadeeasy-为前缀。文档中的参数表如下：
| 参数 | 说明 | 是否必填/默认值 |
|---|---|---|
--dns-dnsmadeeasy-credentials | DNS Made Easy 凭据 INI 文件路径 | 必填 |
--dns-dnsmadeeasy-propagation-seconds | 等待 DNS 传播的秒数，之后再请 ACME 服务器验证 DNS 记录 | 默认60 |
从实现角度看，Authenticator.add_parser_arguments（dns_dnsmadeeasy.py）在基类基础上注册了credentials参数，并把default_propagation_seconds设为60，覆盖了基类DNSAuthenticator默认的 10 秒（certbot/src/certbot/plugins/dns_common.py）。
关于传播等待时间，基类的perform方法（dns_common.py）在创建完所有 TXT 记录后，会先打印Waiting %d seconds for DNS changes to propagate提示，然后sleep指定的秒数。因为本地 DNS 缓存与 ACME 服务器看到的 DNS 状态并不同步，这一固定等待是"以时间换可靠"的稳妥做法。如果验证失败，Certbot 会给出auth_hint提示，建议检查域名是否托管在该 DNS 服务商，或调大--dns-dnsmadeeasy-propagation-seconds。
凭据文件配置
使用该插件前，需要先从 DNS Made Easy 账户页面获取 API 凭据（API Key 与 Secret Key）。文档给出的示例凭据文件如下（INI 格式）：
# DNS Made Easy API credentials used by Certbot dns_dnsmadeeasy_api_key = 1c1a3c91-4770-4ce7-96f4-54c0eb0e457a dns_dnsmadeeasy_secret_key = c9b5625f-9834-4ff8-baba-4ed5f32cae55凭据文件路径有两种提供方式：
- 交互式输入：运行
certbot certonly --dns-dnsmadeeasy时，若未通过命令行指定，Certbot 会提示输入路径； - 命令行指定：通过
--dns-dnsmadeeasy-credentials参数传入。
需要注意：Certbot 会记录该文件的路径用于续期，但不会保存文件内容本身。续期时 Certbot 会重新读取该路径下的凭据文件，因此请保证此文件长期存在且内容有效。
凭据文件的校验逻辑由基类_configure_credentials（dns_common.py）完成：它要求文件中必须存在插件声明为必填的变量，否则抛出PluginError。本插件通过_add_provider_option声明了两个必填项（dns_dnsmadeeasy.py）：
api-key→ 映射为 Lexicon 提供商的auth_username；secret-key→ 映射为 Lexicon 提供商的auth_token。
凭据安全与权限警告
文档对凭据安全给出了明确的警告：
应当像保护 DNS Made Easy 账户密码一样保护这些 API 凭据。能读取该文件的用户可以利用这些凭据以你的名义发起任意 API 调用；能诱使 Certbot 使用这些凭据运行的用户，可以完成
dns-01挑战，为相关域名获取新证书或吊销已有证书，即使这些域名并非由当前服务器管理。
此外，Certbot 会在检测到凭据文件可被系统内其他用户访问时发出警告，警告信息为Unsafe permissions on credentials configuration file（后接凭据文件路径）。该警告在每次使用凭据文件时都会出现，包括续期场景，且无法通过任何开关静默——只能通过修复权限问题来消除，例如：
chmod 600 ~/.secrets/certbot/dnsmadeeasy.ini建议将凭据文件放在仅当前用户可读的目录（如~/.secrets/certbot/）下，并设置600权限。
实战示例
以下示例均来自文档，可直接复制使用（需根据实际情况替换域名与凭据路径）。
示例 1：为example.com签发证书
certbot certonly \ --dns-dnsmadeeasy \ --dns-dnsmadeeasy-credentials ~/.secrets/certbot/dnsmadeeasy.ini \ -d example.com示例 2：为example.com与www.example.com签发单个证书（多域名 SAN 证书）
certbot certonly \ --dns-dnsmadeeasy \ --dns-dnsmadeeasy-credentials ~/.secrets/certbot/dnsmadeeasy.ini \ -d example.com \ -d www.example.com示例 3：为example.com签发证书，等待 2 分钟（120 秒）用于 DNS 传播
certbot certonly \ --dns-dnsmadeeasy \ --dns-dnsmadeeasy-credentials ~/.secrets/certbot/dnsmadeeasy.ini \ --dns-dnsmadeeasy-propagation-seconds 120 \ -d example.com提示：把
--dns-dnsmadeeasy-propagation-seconds从默认的 60 秒调大（如 120），适用于 DNS 记录传播较慢、或曾遇到验证超时的场景；调小则会加快签发流程，但可能增加验证失败概率。
源码实现原理
插件类的构成
Authenticator类定义在 certbot-dns-dnsmadeeasy/src/certbot_dns_dnsmadeeasy/_internal/dns_dnsmadeeasy.py，关键点如下：
description：向用户展示的功能说明——"使用 DNS TXT 记录获取证书（当你使用 DNS Made Easy 作为 DNS 服务商时）"；_provider_name：返回dnsmadeeasy，即 Lexicon 中对应的提供商名称；more_info()：说明插件通过 DNS Made Easy API 配置 TXT 记录以响应dns-01挑战。
TXT 记录的创建与清理
插件继承自LexiconDNSAuthenticator，其核心逻辑位于 dns_common_lexicon.py：
_perform(domain, validation_name, validation)：先解析出实际托管 zone 的域名，再以with Client(config) as operations上下文管理器方式创建TXT记录，记录名为_acme-challenge.开头的验证域名，记录内容为挑战验证值；_cleanup(domain, validation_name, validation)：删除之前创建的 TXT 记录。若解析 zone 失败则静默返回（"fails gracefully"），避免在证书已签发、清理失败时中断流程；_build_lexicon_config(domain)：组装 Lexicon 配置，包括domain、delegated（设为与 domain 相同的值，以绕过 Lexicon 的子域解析逻辑，直接使用传入的 zone 名）、provider_name以及从凭据文件读取的提供商选项；_ttl：属性返回60，即创建的 TXT 记录 TTL 固定为 60 秒（dns_common_lexicon.py）。
Zone 识别与错误处理
_resolve_domain（dns_common_lexicon.py）会通过base_domain_name_guesses逐级猜测域名（如先试www.example.com再试example.com），尝试用每个候选域名连接提供商，直到成功为止。本插件重写了_handle_http_error（dns_dnsmadeeasy.py）以提供更友好的错误信息：
- 404 Not Found：说明该候选 zone 不存在，返回
None让上层继续尝试下一个候选域名； - 403 Forbidden：通常意味着凭据有误，错误信息会附带提示
Are your API key and Secret key values correct?； - 其余 HTTP 错误：包装为
PluginError（Error determining zone identifier: ...）。
与基类的协作流程
整个签发流程可概括为（对应 dns_common.py 的perform/cleanup）：
perform先调用_setup_credentials读取并校验凭据文件；- 对每个待验证域名计算验证记录名与验证值，调用
_perform创建 TXT 记录； - 统一等待
propagation-seconds秒，让 DNS 记录传播； - ACME 服务器完成验证、证书签发后，调用
cleanup删除 TXT 记录。
测试验证
仓库提供了针对本插件的单元测试：certbot-dns-dnsmadeeasy/src/certbot_dns_dnsmadeeasy/_internal/tests/dns_dnsmadeeasy_test.py。测试类继承BaseLexiconDNSAuthenticatorTest，验证要点包括：
- 在临时目录中写入含
dnsmadeeasy_api_key、dnsmadeeasy_secret_key的凭据文件，并构造dnsmadeeasy_credentials、dnsmadeeasy_propagation_seconds=0（测试期间不等待传播）的配置； - 定义
DOMAIN_NOT_FOUND（404 响应）与LOGIN_ERROR（403 响应）两类 HTTP 错误场景，分别对应源码中"404 继续猜测 zone、403 提示检查 Key"的分支逻辑； - 通过模拟的 Lexicon 客户端验证 TXT 记录的创建、删除与错误处理路径。
这说明插件的凭据解析、zone 识别和错误提示行为均有对应的自动化测试保障。
续期与使用注意
- 续期时 Certbot 会自动复用当初记录的凭据文件路径，无需再次交互输入；请确保凭据文件路径稳定、内容长期有效；
- 通配符证书（
-d '*.example.com'）只能通过dns-01挑战签发，这正是本插件的典型使用场景； - 若使用过程中遇到 "Unsafe permissions on credentials configuration file" 警告，应通过
chmod 600收紧文件权限，而不是忽略它。
更多插件 API 层面的说明可参考 certbot-dns-dnsmadeeasy/docs/api.rst——Certbot 插件实现的是 Certbot 插件 API，除此之外不对外暴露独立 API；文档的完整索引位于 certbot-dns-dnsmadeeasy/docs/index.rst。
- 网络安全
- CLI
- 后端
【免费下载链接】certbot
Certbot is EFF's tool to obtain certs from Let's Encrypt and (optionally) auto-enable HTTPS on your server. It can also act as a client for any other CA that uses the ACME protocol.
相关推荐
Certbot DNSimple DNS 插件（certbot-dns-dnsimple）实战指南：基于 DNS-01 挑战的自动化通配符证书签发
Certbot DNSimple DNS 插件（certbot dns dnsimple）实战指南：基于 DNS 01 挑战的自动化通配符证书签发 Certbo
网络安全CLI后端Sandstorm 的 acme-dns-01-sandcats 插件：借助 ACME dns-01 挑战自动签发 Sandcats.io 子域证书
Sandstorm 的 acme dns 01 sandcats 插件：借助 ACME dns 01 挑战自动签发 Sandcats.io 子域证书 导读 ac
后端容器运行时安全云原生Certbot 通配符证书签发实战：certbot-dns-google 插件与 Google Cloud DNS 的 dns-01 自动化配置指南
Certbot 通配符证书签发实战：certbot dns google 插件与 Google Cloud DNS 的 dns 01 自动化配置指南 本指南聚焦
网络安全CLI后端
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
