Loading... # acme.sh 通配符证书验证失败排查复盘 # 一、事件概述 ## 1. 事件背景 在主机 root@156.226.176.52 上使用 acme.sh 签发 op123.ren 及其多子域通配符证书时，DNS 验证失败，报错提示在 _acme-challenge.n9e.op123.ren 处未找到 TXT 记录。 ## 2. 影响范围 ### A. 影响功能 无法为以下域名签发或续期证书：op123.ren、*.op123.ren、*.ngrok.op123.ren、*.tools.op123.ren、*.atzlinux.op123.ren、*.api.op123.ren、*.mcp.op123.ren、*.n9e.op123.ren。 ### B. 影响时长 自执行命令至根因确认并给出修复方案为止。 ### C. 严重程度 证书无法签发会导致上述域名无法使用有效的 HTTPS，属配置类问题，修复后即可恢复。 ## 3. 执行命令与报错 执行命令为： ```bash /root/.acme.sh/acme.sh --issue -d op123.ren -d "*.op123.ren" \ -d "*.ngrok.op123.ren" -d "*.tools.op123.ren" -d "*.atzlinux.op123.ren" \ -d "*.api.op123.ren" -d "*.mcp.op123.ren" -d "*.n9e.op123.ren" \ --dns dns_tencent --challenge-alias sddts.cn --force ``` 报错摘要： - Invalid status. Verification error details: No TXT record found at _acme-challenge.n9e.op123.ren - Removing DNS records 时仅删除了 _acme-challenge.sddts.cn 的 TXT 记录 - 伴随 libcurl error code 3 等次要错误 # 二、事件时间线 ## 1. 问题发生 用户执行上述 acme.sh 命令，使用腾讯云 DNS API（dns_tencent）与挑战别名（challenge-alias sddts.cn），期望在 sddts.cn 所在 DNS 写入一条 TXT 完成所有域名验证。 ## 2. 问题定位 通过分析报错与 acme.sh 官方文档可知： - 使用 --challenge-alias 时，acme.sh 只会把验证用 TXT 写在 _acme-challenge.sddts.cn - Let's Encrypt 仍会按域名逐个查询 _acme-challenge.<域名> - 因此必须在 op123.ren 的 DNS 中，为每个参与签发的（子）域名预先配置 CNAME：_acme-challenge.<该域名> 指向 _acme-challenge.sddts.cn 报错指向 _acme-challenge.n9e.op123.ren，说明该名的 CNAME 缺失或指向错误。 ## 3. 根因确认 用户执行 dig 验证： ```bash dig _acme-challenge.n9e.op123.ren CNAME +short ``` 返回结果为：_acmhe-challenge.sddts.cn.（多了一个字母 h）。正确目标应为 _acme-challenge.sddts.cn.。CNAME 目标拼写错误，导致 Let's Encrypt 跟随 CNAME 后查询的是 _acmhe-challenge.sddts.cn 的 TXT，而 acme.sh 实际写入的是 _acme-challenge.sddts.cn，因此验证失败。 ## 4. 解决方案 在 op123.ren 的 DNS 中，将 _acme-challenge.n9e.op123.ren 的 CNAME 目标从 _acmhe-challenge.sddts.cn. 修改为 _acme-challenge.sddts.cn.，等待解析生效后重新执行 acme.sh 签发命令。 # 三、问题分析 ## 1. 直接原因 Let's Encrypt 在查询 _acme-challenge.n9e.op123.ren 时，通过 CNAME 被指向 _acmhe-challenge.sddts.cn，在该处无法获得 acme.sh 写入的 TXT（TXT 实际在 _acme-challenge.sddts.cn），因此报「No TXT record found at _acme-challenge.n9e.op123.ren」。 ## 2. 根本原因（5 Whys 分析） ### A. 为什么会出现这个问题？ CNAME 记录的目标主机名配置错误，写成了 _acmhe-challenge.sddts.cn 而非 _acme-challenge.sddts.cn。 ### B. 为什么没有在首次配置时发现？ 多子域、多 CNAME 时，易在手工添加或复制时产生拼写错误，且 DNS 配置后未逐条用 dig 校验 CNAME 目标是否正确。 ### C. 为什么其他子域可能未报错？ 若其他子域（如 op123.ren、ngrok、tools 等）的 _acme-challenge 的 CNAME 已正确指向 _acme-challenge.sddts.cn，则仅 n9e.op123.ren 会验证失败，与报错仅指向 n9e 一致。 ## 3. 深层反思 - 使用 DNS alias 模式时，每个域名/子域都依赖一条正确的 CNAME，漏配或写错任一条都会导致该域名验证失败。 - 建议在批量配置 CNAME 后，用脚本或逐条 dig 检查每条 _acme-challenge.<子域> 的 CNAME 是否指向 _acme-challenge.sddts.cn.。 # 四、解决方案 ## 1. 临时方案 修改 _acme-challenge.n9e.op123.ren 的 CNAME 目标为 _acme-challenge.sddts.cn.，等待 TTL 生效后重跑 acme.sh 命令。 ## 2. 永久方案 ### A. 配置清单 对使用 --challenge-alias sddts.cn 的证书，确保 op123.ren 的 DNS 中存在以下 CNAME（目标均为 _acme-challenge.sddts.cn.）： | 主机记录（或等效） | 类型 | 目标 | |-------------------|------|------| | _acme-challenge | CNAME | _acme-challenge.sddts.cn. | | _acme-challenge.ngrok | CNAME | _acme-challenge.sddts.cn. | | _acme-challenge.tools | CNAME | _acme-challenge.sddts.cn. | | _acme-challenge.atzlinux | CNAME | _acme-challenge.sddts.cn. | | _acme-challenge.api | CNAME | _acme-challenge.sddts.cn. | | _acme-challenge.mcp | CNAME | _acme-challenge.sddts.cn. | | _acme-challenge.n9e | CNAME | _acme-challenge.sddts.cn. | ### B. 验证方法 签发前可用下列命令确认 CNAME 是否正确： ```bash dig _acme-challenge.n9e.op123.ren CNAME +short # 应返回: _acme-challenge.sddts.cn. ``` ## 3. 预防措施 - 新增子域时，同步在 DNS 中为该子域添加 _acme-challenge.<子域> 的 CNAME 记录。 - 使用文档或清单列出所有需 CNAME 的子域，避免漏配或拼写错误。 - 重要变更后使用 dig 或脚本批量校验 CNAME 目标。 # 五、经验总结 ## 1. 做得好的地方 - 报错信息明确指向 _acme-challenge.n9e.op123.ren，便于缩小范围。 - 结合 acme.sh 官方 DNS alias 文档可快速理解「每个域名需独立 CNAME」的机制。 - 通过 dig 直接发现 CNAME 目标拼写错误（acmhe vs acme），定位根因。 ## 2. 需要改进的地方 - 初次配置多子域 CNAME 时未逐条校验，导致错误在签发时才暴露。 - 可考虑在文档或运维流程中固化 CNAME 清单与校验步骤。 ## 3. 流程优化建议 - 将「acme.sh + challenge-alias」所需 CNAME 列表与校验命令写入内部运维文档或 Runbook。 - 证书续期或新增子域后，增加一次 dig 抽查或脚本校验，确保所有 _acme-challenge 的 CNAME 指向正确。 # 六、参考资料 1. [acme.sh DNS alias mode](https://github.com/acmesh-official/acme.sh/wiki/DNS-alias-mode) 2. [acme.sh 官方仓库](https://github.com/acmesh-official/acme.sh) 最后修改：2026 年 03 月 02 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏