网络安全CLI后端【免费下载链接】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点击查看免费下载本指南聚焦 Certbot 生态中的certbot-dns-google插件它通过 Google Cloud DNS API 自动创建并清理_acme-challengeTXT 记录完成 ACME 协议中的dns-01挑战从而为域名尤其是通配符域名自动签发 Lets Encrypt 证书。读完本文你将掌握插件的三个核心命令行参数、Application Default CredentialsADC与服务账号 JSON 两种凭据接入方式、预定义角色与自定义角色的最小权限授权方案以及从源码层面理解 TXT 记录增删与 DNS 传播等待的完整工作链路。插件定位为 dns-01 挑战而生certbot-dns-google是 Certbot 的 DNS 认证插件之一官方描述为Google Cloud DNS Authenticator plugin for Certbot见 certbot-dns-google/pyproject.toml。它解决的核心问题是当你的域名托管在 Google Cloud DNS 时如何自动化完成dns-01挑战——这是唯一支持签发通配符证书的 ACME 挑战类型而 HTTP-01 无法覆盖通配符域名。该插件的模块文档即 certbot-dns-google/src/certbot_dns_google/init.py 中的 docstring也是插件文档页docs/index.rst通过automodule指令渲染的主体内容明确指出插件通过 Google Cloud DNS API 创建、随后移除 TXT 记录自动化完成dns-01挑战。从插件源码看其类描述与行为定义在 dns_google.py 中Authenticator继承自certbot.plugins.dns_common.DNSAuthenticatordescriptionObtain certificates using a DNS TXT record (if you are using Google Cloud DNS for DNS).默认 TTL 固定为60秒。需要注意的是插件默认不随 Certbot 一起安装模块文档中的 note 明确说明需要根据你的操作系统选择 Wildcard 标签页单独安装。安装完成后Certbot 通过 pyproject.toml 中声明的 entry point 自动发现插件[project.entry-points.certbot.plugins] dns-google certbot_dns_google._internal.dns_google:Authenticator从源码结构看插件的公开接口对外 API就是 Certbot 插件标准接口docs/api.rst也明确指出插件实现的是 Certbot Plugins API除此之外没有额外外部 API。三个核心命令行参数模块文档以表格形式定义了插件的全部命名参数均由 dns_google.py 中重写的add_parser_arguments方法注册参数说明默认值--dns-google-credentialsGoogle Cloud Platform 服务账号凭据 JSON 文件路径。不使用 ADC 时必填。无依赖 ADC--dns-google-projectGoogle Cloud DNS 托管区域managed zone所在的 Google Cloud 项目 ID。凭据所属项目自动推断--dns-google-propagation-seconds在 ACME 服务器校验 DNS 记录前等待 DNS 传播的秒数。60从源码看参数的具体语义--dns-google-credentials的 help 文本明确该文件用于替代Application Default CredentialsADC并给出了官方文档指引ADC 说明、服务账号创建方式、修改 Cloud DNS 记录所需权限参数defaultNone即未指定时走 ADC 路径。--dns-google-project用于指定托管区域所在的项目 IDdefaultNone时从凭据自动确定。其 help 文本说明了场景托管区域与凭据可能不在同一项目。传播等待时间默认 60 秒插件父类DNSAuthenticator.add_parser_arguments接收default_propagation_seconds60插件调用时显式传入60保持一致。此外Authenticator内部固定使用ttl 60作为 TXT 记录的 TTL源码第 34 行不对外暴露参数。凭据配置ADC 与服务账号 JSON插件要求凭据具备修改目标托管区域的能力模块文档 Credentials 一节。配置方式分两类场景首选方案Application Default CredentialsADC模块文档将在 Certbot 运行环境中配置 ADC列为首选方式。ADC 的优势是无需在命令行中暴露凭据文件路径Google 官方认证库会按既定顺序自动寻找可用凭据。在 Google Cloud 上运行 Certbot可直接为各类工作负载挂载服务账号包括 Compute Engine 虚拟机、Kubernetes Engine Pod、Cloud Run 任务、Cloud Functions 以及 Cloud Build无需下载任何密钥文件。在 Google Cloud 之外运行其他云、CI 平台等若平台支持 OIDC Token可考虑工作负载身份联合workload identity federation实现免密钥认证常见平台均有官方指引。备选方案服务账号 JSON 文件不在 Google Cloud 内运行时通过--dns-google-credentials显式传入服务账号密钥文件。模块文档给出了示例文件结构{ type: service_account, project_id: ..., private_key_id: ..., private_key: ..., client_email: ..., client_id: ..., auth_uri: https://accounts.google.com/o/oauth2/auth, token_uri: https://accounts.google.com/o/oauth2/token, auth_provider_x509_cert_url: https://www.googleapis.com/oauth2/v1/certs, client_x509_cert_url: ... }安全警告模块文档明确强调凭据文件必须像密码一样保护。能读取该文件的人可以代表你发起部分 API 调用能诱导 Certbot 使用这些凭据运行的人可以完成dns-01挑战从而为这些凭据有权管理的域名签发新证书或吊销现有证书。Certbot 会对权限过宽的凭据文件发出警告文案为Unsafe permissions on credentials configuration file并附上文件路径。该警告在每次使用凭据时包括续期都会输出无法静默关闭唯一解决办法是修复权限例如用chmod 600限制为仅属主可读写。这一行为在源码中有对应实现_setup_credentials中当指定了credentials参数时会调用dns_common.validate_file_permissions(self.conf(credentials))进行权限校验dns_google.py。源码中的凭据加载逻辑_GoogleClient构造函数dns_google.py完整体现了两种凭据路径请求的 OAuth scope 固定为https://www.googleapis.com/auth/ndev.clouddns.readwriteCloud DNS 读写传入account_json时调用google.auth.load_credentials_from_file(account_json, scopesscopes)同时返回凭据对象与项目 ID文件损坏或认证失败时抛出PluginError错误信息形如Error loading credentials file 路径: ...未传入时调用google.auth.default(scopesscopes)走 ADC 标准流程若抛出DefaultCredentialsError插件会在_setup_credentials中将其转换为PluginError并提示使用--dns-google-credentials file项目 ID 优先级显式--dns-google-project 凭据携带的项目两者都为空时抛出PluginError提示使用--dns-google-project projectAPI 客户端通过discovery.build(dns, v1, credentialscredentials, cache_discoveryFalse)构建。权限授权预定义角色与自定义角色模块文档提供了两种授权策略。所有角色授权操作需借助 Google Cloud IAM 完成针对项目或针对单个托管区域授权。策略一使用预定义角色推荐两种可行组合二选一组合 A最小授权在 Certbot 要签发证书的托管区域zone上授予dns.admin角色同时在项目上授予dns.reader角色组合 B便捷在包含相关 DNS 区域的项目上授予dns.admin角色。安全警告在项目级别授予dns.admin存在显著安全风险——它提供项目内所有 DNS 区域的完整管理权限可执行包括删除项目内全部区域在内的任何操作。因此在生产环境应优先考虑组合 A 或下方自定义角色方案。策略二使用自定义角色最小权限适合生产或安全敏感场景遵循最小权限原则。模块文档给出了完整的双角色方案第一步创建含 DNS 记录更新权限的自定义角色建议命名为Certbot - Zone EditorID 为certbot.zoneEditor所需权限dns.changes.createdns.changes.getdns.changes.listdns.resourceRecordSets.createdns.resourceRecordSets.deletedns.resourceRecordSets.listdns.resourceRecordSets.update第二步创建含托管区域发现权限的自定义角色建议命名为Certbot - Zone ListerID 为certbot.zoneLister所需权限dns.managedZones.getdns.managedZones.list第三步将角色授予 Certbot 认证所用的用户或服务账号在 Certbot 要签发证书的托管区域上授予Certbot - Zone Editor角色在包含相关 DNS 区域的项目上授予Certbot - Zone Lister角色。这 9 项权限与源码的实际调用一一对应dns.managedZones.list对应托管区域查找、dns.resourceRecordSets.list对应现有 TXT 记录查询、dns.changes.create/get对应变更提交与轮询、dns.resourceRecordSets.create/delete/update对应记录增删改。实战示例五种典型签发场景模块文档提供了 5 个可直接复用的命令行示例假设已安装插件并完成前述配置。示例 1指定凭据文件签发example.comcertbot certonly \ --dns-google \ --dns-google-credentials ~/.secrets/certbot/google.json \ -d example.com示例 2ADC 可用时无需凭据文件certbot certonly \ --dns-google \ -d example.com示例 3单证书覆盖多个域名certbot certonly \ --dns-google \ -d example.com \ -d www.example.com示例 4托管区域位于其他 Google Cloud 项目certbot certonly \ --dns-google \ --dns-google-credentials ~/.secrets/certbot/google-project-test-foo.json \ --dns-google-project test-bar \ -d example.com示例 5调整 DNS 传播等待时间certbot certonly \ --dns-google \ --dns-google-propagation-seconds 120 \ -d example.com实际使用时按需叠加例如通配符场景可写为certbot certonly --dns-google --dns-google-credentials file -d example.com -d *.example.comdns-01是签发通配符证书的前提。签发后 Certbot 会自动配置续期续期时复用同一插件与参数。源码级工作链路解析理解插件内部实现有助于排查问题与合理调整参数。核心类_GoogleClient封装了与 Google Cloud DNS API 的全部通信dns_google.py验证逻辑可在 dns_google_test.py 中逐一印证。挑战执行流程_perform → add_txt_record查找托管区域_find_managed_zone_id使用dns_common.base_domain_name_guesses(domain)生成候选域名从完整域名逐级向上猜测区域名对每个候选调用managedZones.list(project..., dnsNamezone_name .)命中可见性为 public的区域即返回其 ID否则抛出PluginError提示 Unable to determine managed zone ...。注意私有区域private会被跳过测试test_add_txt_record_and_poll_split_horizon专门验证了同名公私有区域并存时选择 public 区域的行为。读取现有 TXT 记录get_existing_txt_rrset调用resourceRecordSets.list(..., namerecord_name ., typeTXT)。若.list权限缺失无法枚举返回None并按不存在记录处理——如果实际存在记录后续 API 会以 HTTP 409/412 报错源码注释引用了 issue #5678。若响应为空如请求通配符证书时同样返回None。幂等去重若目标验证值已存在于现有rrdatas中说明上次流程被中断、验证 token 仍在直接返回不重复创建——对应测试test_add_txt_record_noop。构造 change 请求拼装kind: dns#change请求体additions中写入dns#resourceRecordSettype: TXT、name: record_name.、ttl: 60、合并后的rrdatas若该标签下已有记录则在同一请求的deletions中携带旧记录避免 HTTP 409/412 冲突——test_add_txt_record_delete_old与test_add_txt_record_delete_old_ttl_case验证了 deletions 中必须保留旧记录的原始 TTL。提交并轮询changes.create(...)提交变更若返回status pending则循环调用changes.get(changeId...)直到status done——test_add_txt_record_and_poll验证了这一轮询路径。任何googleapiclient错误都会被包装为PluginError并记录日志。清理流程_cleanup → del_txt_record清理发生在挑战验证完成之后无论成功与否只要执行过 _perform查找托管区域失败时仅记录 warning 并跳过清理防止因区域被删导致整个流程报错对应测试test_del_txt_record_error_during_zone_lookup与test_del_txt_record_zone_not_found读取现有 TXT 记录集构造deletions删除当前验证值所在整个 RRset若该标签下还有其他 TXT 值如多证书并发验证则在additions中重新添加剩余记录保证只删除本次挑战的 token——test_del_txt_record_multi_rrdatas精确断言了deletions 全删 additions 回写剩余值的请求体若只剩一条记录则只发 deletionstest_del_txt_record_single_rrdatas删除过程中的 API 错误仅记录 warning不抛出清理失败不应让签发流程失败。单元测试印证认证器测试覆盖了perform调用add_txt_record(domain, _acme-challenge.domain, validation, ttl)、cleanup调用del_txt_record、凭据加载失败与项目缺失的PluginError抛出、客户端缓存_get_google_client只初始化一次等关键路径测试通过 testdata/discovery.jsonGoogle Cloud DNS API v1 的 discovery 文档与HttpMock模拟真实 API 交互。常见问题与排查要点Unsafe permissions on credentials configuration file 警告凭据文件权限过宽执行chmod 600 文件后重试该警告无法静默只能修复权限。The Google Cloud project could not be automatically determined凭据中无项目信息且未指定--dns-google-project按提示显式传入项目 ID。Error loading credentials file ...凭据 JSON 损坏或路径错误检查文件内容与--dns-google-credentials路径。Unable to determine managed zone ...区域查找失败确认域名托管在 Google Cloud DNS、区域可见性为 public且服务账号具备dns.managedZones.list与dns.reader/dns.admin权限。HTTP 409/412 冲突标签下已有未预期记录例如缺少.list权限时旧记录未被正确合并检查服务账号是否具备dns.resourceRecordSets.list权限。传播超时导致验证失败默认等待 60 秒若权威 DNS 传播较慢或使用多级 NS/上游缓存用--dns-google-propagation-seconds调大等待时间如 120 秒。结语certbot-dns-google以极小的参数面完成了 Google Cloud DNS 下dns-01挑战的全自动化凭据层支持 ADC 免密钥接入与服务账号 JSON 两种模式权限层提供预定义角色与双自定义角色两种粒度执行层则在一次dns#change请求中原子完成合并新增 删除旧值并以幂等去重和容错清理保证可重复运行。对于域名托管在 Google Cloud DNS 且需要通配符证书的场景这是与 Certbot 配合度最高的自动化方案。安装与配置要点见 certbot-dns-google/README.rst核心实现见 dns_google.py测试用例见 dns_google_test.py。赞分享网络安全CLI后端【免费下载链接】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点击查看免费下载相关推荐Certbot DNSimple DNS 插件certbot-dns-dnsimple实战指南基于 DNS-01 挑战的自动化通配符证书签发Certbot DNSimple DNS 插件certbot dns dnsimple实战指南基于 DNS 01 挑战的自动化通配符证书签发 Certbo网络安全CLI后端Certbot DNS-01 认证插件 certbot-dns-route53 实战指南基于 AWS Route 53 自动签发通配符证书Certbot DNS 01 认证插件 certbot dns route53 实战指南基于 AWS Route 53 自动签发通配符证书 本指南围绕 Cer网络安全CLI后端certbot-dns-nsone 插件实战使用 NS1 DNS 自动完成 dns-01 验证并签发通配符证书certbot dns nsone 插件实战使用 NS1 DNS 自动完成 dns 01 验证并签发通配符证书 本指南围绕 Certbot 官方 DNS 插件网络安全CLI后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
