Certbot DNSimple DNS 插件certbot-dns-dnsimple实战指南基于 DNS-01 挑战的自动化通配符证书签发【免费下载链接】certbotCertbot is EFFs tool to obtain certs from Lets 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.项目地址: https://gitcode.com/gh_mirrors/ce/certbotCertbot 官方仓库为 DNSimple 用户提供了certbot-dns-dnsimple插件它通过调用 DNSimple v2 API 自动创建并删除 TXT 记录来完成 ACMEdns-01挑战从而签发含通配符在内的Lets Encrypt 证书。本文以该插件官方文档certbot-dns-dnsimple/docs/index.rst与模块 docstring为核心骨架结合仓库源码展开帮助你掌握插件安装、凭据配置、命令行参数与真实运行示例并理解其底层的 Lexicon 驱动实现。插件是什么用 DNS TXT 记录完成 dns-01 挑战在标准 HTTP-01 挑战无法使用例如服务器未暴露公网 80 端口、域名未指向本机时dns-01挑战是签发证书尤其是通配符证书的首选方案。certbot-dns-dnsimple插件正是为此设计它会调用 DNSimple 的 DNS 管理 API自动为待验证域名创建一条 TXT 记录以响应 ACME 服务器的验证请求验证完成后再将记录删除。源码中对插件职责的定位非常清晰见 插件模块 与 模块 docstringThis Authenticator uses the DNSimple v2 API to fulfill a dns-01 challenge. The plugin automates the process of completing adns-01challenge by creating, and subsequently removing, TXT records using the DNSimple API.插件本身不直接与 ACME 服务器交互也不管理证书文件它只负责用 DNSimple 托管域名下的 TXT 记录这一个环节其余证书获取、续期流程全部交由 Certbot 核心完成。安装与启用方式该插件默认不会随 Certbot 安装。官方文档明确提示The plugin is not installed by default. It can be installed by heading to certbot.eff.org, choosing your system and selecting the Wildcard tab.因此使用前需按以下两种方式之一安装方式一使用官方安装指引推荐访问 certbot.eff.org 的安装说明页面选择你的操作系统然后在安装标签页中选择 Wildcard通配符标签页面会给出适配当前系统的完整安装命令。对于大多数 Linux 发行版实质上是安装certbot-dns-dnsimple系统包或使用 pip 安装pip install certbot-dns-dnsimple方式二在源码仓库中构建/测试仓库内通过 pyproject.toml 与 setup.py 管理该插件的打包。从打包配置可以看出它的依赖与 Python 版本要求运行时依赖dns-lexicon3.14.1Lexicon 库用于对接 DNSimple API版本下限是为了规避 AnalogJ/lexicon#387 描述的问题同时依赖acme版本号与certbot版本号与当前插件版本号保持一致。Python 要求3.10支持 3.10 至 3.14。插件通过 setuptools entry point 注册见 pyproject.toml 第 44-45 行[project.entry-points.certbot.plugins] dns-dnsimple certbot_dns_dnsimple._internal.dns_dnsimple:Authenticator这意味着安装后运行certbot plugins即可看到dns-dnsimple插件命令中通过--dns-dnsimple即可启用。命令行参数详解插件通过 Authenticator.add_parser_arguments 注册两个参数官方文档以表格形式完整列出参数说明是否必填 / 默认值--dns-dnsimple-credentialsDNSimple 凭据 INI 文件路径必填--dns-dnsimple-propagation-seconds在 ACME 服务器验证 DNS 记录前等待 DNS 传播的秒数默认30propagation-seconds的默认值来自基类 dns_common_lexicon.LexiconDNSAuthenticator.add_parser_arguments 中default_propagation_seconds: int 30的默认参数在 dns_dnsimple.py 第 30-34 行 中显式透传。当你的域名 TTL 较高或 DNSimple 传播较慢时可以调大该值。此外插件还通过_add_provider_option注册了token提供者选项见 dns_dnsimple.py 第 26-28 行提示用户在 DNSimple 账户页面获取 v2 API 的用户访问令牌。凭据文件配置与安全要求使用该插件前需要从你的 DNSimple 账户页面https://dnsimple.com/user源码中以ACCOUNT_URL常量定义见 dns_dnsimple.py 第 13 行获取一个 API 访问令牌User access token然后创建凭据 INI 文件。官方文档给出了完整示例# DNSimple API credentials used by Certbot dns_dnsimple_token MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAw该文件路径可以在运行时通过交互提示输入或直接使用--dns-dnsimple-credentials命令行参数指定。Certbot 只记录凭据文件的路径用于续期不会存储文件内容本身。凭据的安全红线官方文档以caution级别强调了凭据保护的重要性这里逐条列出应像保护 DNSimple 账户密码一样保护这些 API 凭据能读取该文件的用户可以使用这些凭据以你的名义发起任意 API 调用能诱导 Certbot 使用这些凭据运行的用户可以完成dns-01挑战为关联域名获取新证书或吊销现有证书——即使这些域名并非由本服务器管理。权限告警机制Certbot 会在检测到凭据文件可被系统上其他用户读取时发出警告警告文本为 Unsafe permissions on credentials configuration file随后附上凭据文件路径。官方文档特别说明该警告会在每次使用凭据文件时输出包括续期场景该警告无法被静默抑制唯一解决方式是修复权限问题例如执行chmod 600限制文件访问权限。注意本文档仅介绍配置方式由于仓库为只读状态实际操作时请在你自己环境中的凭据文件上执行chmod 600等权限调整。实战示例签发证书官方文档提供了三组可直接复制的命令行示例。示例一为example.com签发证书certbot certonly \ --dns-dnsimple \ --dns-dnsimple-credentials ~/.secrets/certbot/dnsimple.ini \ -d example.com示例二为example.com和www.example.com签发单张证书certbot certonly \ --dns-dnsimple \ --dns-dnsimple-credentials ~/.secrets/certbot/dnsimple.ini \ -d example.com \ -d www.example.com示例三为example.com签发证书并等待 60 秒传播时间certbot certonly \ --dns-dnsimple \ --dns-dnsimple-credentials ~/.secrets/certbot/dnsimple.ini \ --dns-dnsimple-propagation-seconds 60 \ -d example.com这些命令都使用certonly子命令仅获取证书而不自动修改 Web 服务器配置--dns-dnsimple指定使用本插件--dns-dnsimple-credentials指定凭据文件。如果要签发通配符证书这是该插件最典型的用途只需追加-d *.example.com之类的通配符域名即可。底层原理Lexicon 驱动的 TXT 记录生命周期理解插件内部实现有助于排查问题并合理设置参数。继承自 LexiconDNSAuthenticator插件类Authenticator继承自 certbot.plugins.dns_common_lexicon.LexiconDNSAuthenticator因此复用了一整套基于 Lexicon 库对接各家 DNS 服务商的通用框架插件标识description为 Obtain certificates using a DNS TXT record (if you are using DNSimple for DNS)._provider_name返回dnsimple用于在 Lexicon 配置中定位 DNSimple provider见 dns_dnsimple.py 第 22、40-42 行。凭据注入__init__中调用_add_provider_option(token, ...)把 INI 文件中的dns_dnsimple_token映射为 Lexicon 的auth_token配置项见 dns_dnsimple.py 第 24-28 行。TXT 记录的创建与清理基类实现了 dns-01 挑战的两个关键动作见 dns_common_lexicon.py_perform(domain, validation_name, validation)解析出权威域名后通过Client(...)建立与 DNSimple 的连接调用create_record(rtypeTXT, namevalidation_name, contentvalidation)创建验证所需的 TXT 记录若请求异常抛出errors.PluginError(Error adding TXT record: ...)。_cleanup(domain, validation_name, validation)挑战结束后删除同名 TXT 记录实现用完即清避免残留记录造成安全隐患。也就是说从创建到删除的完整生命周期由 Certbot 的认证处理器按流程自动调度用户无需手动增删 DNS 记录。错误处理与可诊断性插件覆写了_handle_http_error见 dns_dnsimple.py 第 44-52 行对 DNSimple API 返回的 HTTP 错误进行增强当错误信息以401 Client Error: Unauthorized开头时会追加提示 Is your API token value correct?最终统一抛出包含域名上下文的errors.PluginError形如 Error determining zone identifier for {domain}...便于定位是令牌错误还是域名归属问题。这一行为在单元测试中也有覆盖测试类将LOGIN_ERROR设置为 401 Unauthorized 响应见 dns_dnsimple_test.py 第 20 行验证认证失败场景下的提示逻辑。测试与验证仓库为插件提供了基于 pytest 的单元测试见 dns_dnsimple_test.py测试类继承自dns_test_common_lexicon.BaseLexiconDNSAuthenticatorTest复用了 Lexicon 系列插件共用的测试骨架测试中会在临时目录生成file.ini并写入dnsimple_token然后以模拟配置构造Authenticator实例其中dnsimple_propagation_seconds0表示测试期间不等待传播TOKEN foo等常量用于验证凭据读取与解析路径。如果你想在本地源码环境中运行该测试可在仓库根目录执行pytest certbot-dns-dnsimple/src/certbot_dns_dnsimple/_internal/tests/dns_dnsimple_test.py需要先安装certbot、dns-lexicon等依赖与测试依赖。续期行为说明与所有 Certbot DNS 插件一致续期时 Certbot 会重新执行 dns-01 挑战它只依赖当初记录的凭据文件路径因此凭据文件必须持续存在且内容有效令牌未失效、未被轮换凭据文件的权限告警在每次续期使用凭据时同样会触发若令牌在 DNSimple 账户中被吊销或更换续期会失败并抛出 401 相关错误此时按报错提示更新凭据文件即可。常见问题速查现象可能原因与处理报错信息以401 Client Error: Unauthorized开头API 令牌错误或已失效检查dns_dnsimple_token取值参考 dns_dnsimple.py 错误处理提示 Unsafe permissions on credentials configuration file凭据文件权限过宽执行chmod 600收紧权限验证失败但 DNS 记录已创建DNS 传播延迟调大--dns-dnsimple-propagation-seconds找不到dns-dnsimple插件未安装certbot-dns-dnsimple按上文安装与启用方式安装后重试结语certbot-dns-dnsimple把在 DNSimple 托管 DNS 下完成 ACME dns-01 挑战这一流程完全自动化你只需提供 API 令牌与凭据文件Certbot 会自动创建 TXT 记录、等待传播、完成验证并清理记录从而为普通域名与通配符域名签发和续期证书。结合本文的源码分析你可以在遇到令牌错误、权限告警或传播超时等问题时快速定位根因。【免费下载链接】certbotCertbot is EFFs tool to obtain certs from Lets 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.项目地址: https://gitcode.com/gh_mirrors/ce/certbot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考