使用 lego 的 ConoHa v2 DNS Provider 完成 ACME DNS-01 挑战：配置指南与实现原理

使用 lego 的 ConoHa v2 DNS Provider 完成 ACME DNS-01 挑战配置指南与实现原理【免费下载链接】legoLets Encrypt/ACME client and library written in Go项目地址: https://gitcode.com/gh_mirrors/le/lego导读本篇文章聚焦于 Go 语言编写的 Lets Encrypt/ACME 客户端 lego 中内置的ConoHa v2 DNS Provider代码名conoha自 v1.2.0 起支持。文章围绕其在docs/content/dns/zz_gen_conoha.md中定义的配置规范展开结合仓库内providers/dns/conoha/的源码与测试完整讲解如何通过 ConoHa 的 DNS API 为通配符域名自动签发证书覆盖环境变量凭证、可选参数调优、底层认证与 DNS 记录操作原理帮助你直接复制命令完成生产级接入。ConoHa v2 Provider 是什么ConoHa日本 GMO 旗下云服务商提供 VPS、对象存储和 DNS 托管服务。ConoHa v2 Provider 是 lego 内置的 DNS-01 挑战求解器当域名托管在 ConoHa DNS 时lego 可以调用其官方 API 自动添加与删除用于验证的 TXT 记录从而无需人工干预即可签发包含通配符在内的证书。该 Provider 在 docs/content/dns/zz_gen_conoha.md 中定义其配置元数据源文件为 providers/dns/conoha/conoha.toml包含以下关键标识CodeconohaSincev1.2.0用途求解 DNS-01 挑战challenge/dns01 包API 文档ConoHa 官方提供的 DNS v2 API对应paas-dns-list-domains-v2、paas-dns-create-record-v2等接口快速上手一行命令签发通配符证书当你的域名 DNS 托管在 ConoHa 时只需导出三个必需的环境变量即可通过lego run命令申请证书CONOHA_TENANT_ID487727e3921d44e3bfe7ebb337bf085e \ CONOHA_API_USERNAMExxxx \ CONOHA_API_PASSWORDyyyy \ lego run --dns conoha -d *.example.com -d example.com命令要点--dns conoha指定使用 ConoHa v2 Provider 完成 DNS-01 挑战-d *.example.com -d example.com同时申请通配符域名及其根域名注意通配符域名需加单引号防止 shell 展开示例中的CONOHA_TENANT_ID487727e3921d44e3bfe7ebb337bf085e为文档给出的占位 Tenant ID实际使用请替换为你账户的租户 ID。凭证配置三个必填环境变量环境变量名说明CONOHA_API_PASSWORDAPI 密码CONOHA_API_USERNAMEAPI 用户名CONOHA_TENANT_ID租户 IDTenant ID这三者缺一不可。从源码 providers/dns/conoha/conoha.go 可以看到NewDNSProvider()通过env.Get(EnvTenantID, EnvAPIUsername, EnvAPIPassword)一次性读取三个变量任一缺失都会返回形如conoha: some credentials information are missing: CONOHA_TENANT_ID的错误。测试 providers/dns/conoha/conoha_test.go 专门验证了以下场景三变量齐全 → 正常创建 Provider三变量全缺 → 报错并列出缺失项仅缺CONOHA_TENANT_ID、CONOHA_API_USERNAME或CONOHA_API_PASSWORD之一 → 报错并精确指明缺失项。使用文件代替明文值_FILE 后缀所有环境变量名都可以追加_FILE后缀将值指向一个文件而非直接内联CONOHA_TENANT_ID_FILE/run/secrets/conoha_tenant_id \ CONOHA_API_USERNAME_FILE/run/secrets/conoha_username \ CONOHA_API_PASSWORD_FILE/run/secrets/conoha_password \ lego run --dns conoha -d example.com这种方式适合容器化部署如 Docker/K8s Secret 挂载避免把密钥写进命令行或 CI 日志。通用说明见 docs/content/dns/_index.md 的 Configuration and Credentials 一节。可选参数超时、区域与 TTL 调优除三个必填凭证外ConoHa v2 Provider 还支持以下可选环境变量环境变量名说明默认值CONOHA_HTTP_TIMEOUTAPI 请求超时时间秒30CONOHA_POLLING_INTERVALDNS 传播检查间隔秒2CONOHA_PROPAGATION_TIMEOUT等待 DNS 传播的最大时间秒60CONOHA_REGION区域regiontyo1CONOHA_TTLDNS 挑战 TXT 记录的 TTL秒60同样支持_FILE后缀。默认值的源码依据这些默认值在 providers/dns/conoha/conoha.go 的NewDefaultConfig()中定义func NewDefaultConfig() *Config { return Config{ Region: env.GetOrDefaultString(EnvRegion, tyo1), TTL: env.GetOrDefaultInt(EnvTTL, 60), PropagationTimeout: env.GetOrDefaultSecond(EnvPropagationTimeout, dns01.DefaultPropagationTimeout), PollingInterval: env.GetOrDefaultSecond(EnvPollingInterval, dns01.DefaultPollingInterval), HTTPClient: http.Client{ Timeout: env.GetOrDefaultSecond(EnvHTTPTimeout, 30*time.Second), }, } }其中dns01.DefaultPropagationTimeout与dns01.DefaultPollingInterval定义于 challenge/dns01/dns_challenge.go分别为 60 秒和 2 秒——这就是文档中两个默认值的真实来源。DNSProvider实现了challenge.ProviderTimeout接口其Timeout()方法conoha.go将PropagationTimeout与PollingInterval返回给挑战调度器用于控制验证 TXT 记录传播的等待节奏。参数调优建议TTLCONOHA_TTLTXT 记录存活时间。挑战记录创建时直接使用该值默认 60 秒传播较快无需刻意调大。传播等待CONOHA_PROPAGATION_TIMEOUT/CONOHA_POLLING_INTERVAL若你的权威 DNS 解析链较长、传播偏慢可适当增大超时如 120 秒间隔过短可能触发 ConoHa API 限流。区域CONOHA_REGION默认tyo1东京。ConoHa 不同区域使用独立的 API 服务域名选错区域会导致登录或 DNS 查询失败。HTTP 超时CONOHA_HTTP_TIMEOUT默认 30 秒网络质量较差的场景可适当提高。实现原理从认证到记录增删的三步流程为了让你在使用时心中有数这里从源码层面还原 Provider 的完整工作链路。1. 身份认证获取 X-Auth-TokenConoHa API 采用 Keystone v2.0 风格的身份认证。getToken()conoha.go使用TenantID 用户名/密码构造认证请求交给 internal/identity.go 的GetToken()调用POST {identity_base_url}/v2.0/tokens身份服务地址模板为https://identity.%s.conoha.io%s即CONOHA_REGION请求体结构见 internal/types.go 的Auth/PasswordCredentials响应中取出access.token.id作为后续所有 DNS API 调用的X-Auth-Token请求头。2. Present创建 TXT 挑战记录Present()conoha.go按以下顺序操作调用dns01.GetChallengeInfo()根据keyAuth计算出挑战 TXT 记录的内容与_acme-challengeFQDN使用dns01.DefaultClient().FindZoneByFqdn()从 FQDN 反查托管区域auth zoneclient.GetDomainID()调用GET {dns_base_url}/v1/domains遍历区域列表按名称匹配返回区域 IDinternal/client.go构造Record{Name, Type: TXT, Data, TTL}并通过POST /v1/domains/{domain_id}/records创建记录internal/client.go。DNS 服务地址模板为https://dns-service.%s.conoha.iointernal/client.go再次印证CONOHA_REGION的重要性。3. CleanUp删除 TXT 记录证书签发完成后CleanUp()conoha.go负责清理重新登录获取 token解析区域并获取区域 IDGetRecordID()遍历GET /v1/domains/{domain_id}/records返回的记录列表按「名称 类型 数据」三者精确匹配挑战记录internal/client.go调用DELETE /v1/domains/{domain_id}/records/{record_id}删除该记录。这套流程已被单元测试覆盖见 providers/dns/conoha/internal/client_test.go测试使用httptest模拟 ConoHa API并核对请求头X-Auth-Token: secret、请求体 JSON 与响应解析fixtures 存放于 providers/dns/conoha/internal/fixtures。库方式使用Go 代码集成除了 CLI 方式lego 的 Provider 也可以作为 Go 库集成到自己的证书签发服务中import ( github.com/go-acme/lego/v5/challenge/dns01 github.com/go-acme/lego/v5/providers/dns/conoha ) // 从环境变量读取 CONOHA_TENANT_ID / CONOHA_API_USERNAME / CONOHA_API_PASSWORD provider, err : conoha.NewDNSProvider() if err ! nil { // 处理凭证缺失等错误 } // 或通过 Config 结构体编程式配置 config : conoha.NewDefaultConfig() config.TenantID your-tenant-id config.Username your-api-user config.Password your-api-password config.Region tyo1 config.TTL 60 provider, err conoha.NewDNSProviderConfig(config)Config结构体conoha.go暴露了Region、TenantID、Username、Password、TTL、PropagationTimeout、PollingInterval、HTTPClient字段其中HTTPClient可用于注入自定义超时或代理。之后将provider传入 lego 的Certificator即可完成 DNS-01 挑战。常见问题排查conoha: some credentials information are missingCONOHA_TENANT_ID、CONOHA_API_USERNAME、CONOHA_API_PASSWORD三者缺一不可错误信息会直接列出缺失项。conoha: failed to log in多为凭证错误或区域不对。确认CONOHA_REGION默认tyo1与你的 ConoHa 账户区域一致——身份服务identity.region.conoha.io与 DNS 服务dns-service.region.conoha.io都依赖该值。could not find zone for domain确认目标域名确实已托管在 ConoHa DNS 且区域名称与_acme-challenge所在 FQDN 匹配lego 会通过FindZoneByFqdn从公共 DNS 反查权威区域。TTL/传播超时默认传播等待 60 秒、轮询间隔 2 秒若解析链较长可调大CONOHA_PROPAGATION_TIMEOUT。小结ConoHa v2 DNS Provider 是 lego 生态中配置最直观的 Provider 之一三个必填凭证 五个可选参数即可投入生产。掌握其认证流程Keystone token与「找区域 → 建记录 → 匹配删除」的增删链路后无论是 CLI 一键签发还是 Go 库集成都能快速落地自动化证书管理。【免费下载链接】legoLets Encrypt/ACME client and library written in Go项目地址: https://gitcode.com/gh_mirrors/le/lego创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考