云原生运维【免费下载链接】acme-companionAutomated ACME SSL certificate generation for nginx-proxy项目地址https://gitcode.com/gh_mirrors/ac/acme-companion点击查看免费下载本指南面向使用 acme-companion 自动为 nginx-proxy 签发 ACME 证书的开发者完整讲解证书授权Authorization失败时的系统化排查思路先通过DEBUG1与测试证书获取详细的失败原因再逐项排查端口连通性、DNS 解析、IPv6 可达性、CAA 记录、容器配置与卷共享等常见故障源最后给出非调试模式下手动验证挑战文件可达性的实测方法。读完你将掌握一套可直接复制执行的授权失败排查流程并能对照本仓库源码理解每一步排障背后的实现原理。授权Authorization失败排查的起点DEBUG 模式与测试证书当 acme-companion 无法为域名完成授权时第一步永远是尽可能多地获取失败细节。官方排查路径见 docs/Invalid-authorizations.md包含两个动作以DEBUG1环境变量启动 acme-companion 容器打开更详细的错误输出在排查期间使用测试证书参见 docs/Lets-Encrypt-and-ACME.md 中「Test certificates」一节避免测试过程消耗正式签发的速率配额。这两个动作叠加的效果在源码中有直接体现。查看 app/letsencrypt_service.sh当DEBUG为 1 时容器会向acme.sh传入两个关键参数params_base_arr(--log /dev/stderr) # 将 acme.sh 自身日志路由到容器 stderr而非丢弃 params_base_arr(--debug 2) # 开启 acme.sh 2 级调试输出--log /dev/stderr意味着acme.sh 的完整日志会写入容器输出因此执行docker logs acme-companion-container就能看到授权挑战challenge失败背后的完整原因。这对DNS-01 挑战尤其有用——因为 DNS-01 需要 CA 从外部查询你域名的 TXT 记录失败原因记录未传播、DNS 服务商未生效等几乎只能从 acme.sh 日志中读到。另外在 app/letsencrypt_service.sh 中DEBUG 模式下还会打印实际传给acme.sh --issue的完整参数数组[[ ${DEBUG} 1 ]] echo Calling acme.sh --issue with the following parameters : ${params_issue_arr[*]}这可以让你确认挑战类型、key 长度、CA 端点、webroot 等参数是否真的按预期传递。DEBUG变量本身的解析入口位于 app/functions.shDEBUG$(lc ${DEBUG:-})字符串true会被归一化为1。关于测试证书docs/Lets-Encrypt-and-ACME.md 明确在被代理的应用容器上设置LETSENCRYPT_TESTtrue即可签发由不受信任的中间 CA 签名、且不受「每周每域名 5 张」速率限制约束的测试证书。从源码看该变量在 app/letsencrypt_service.sh 中会强制把acme_ca_uri覆盖为 Lets Encrypt v2 staging 端点ACME_CA_TEST_URI同时 app/letsencrypt_service.sh 会把配置目录强制指向staging并把证书目录加_test_前缀保证测试证书与正式证书互不干扰。常见授权失败原因清单与逐项排查以下是 acme-companion 文档归纳的常见授权失败原因。排查时建议按顺序逐项验证多数授权失败都能归结为下面几类。原因一主机 80/443 端口从外部不可达防火墙/过滤Lets Encrypt 的 HTTP-01 挑战要求 CA 能从公网访问你的主机 80和/或 443端口。若端口被防火墙遮蔽或过滤授权必然失败。排查方法从一个公网 IP 与你的主机不同的外部机器上检查端口使用nmap或同类工具nmap -p 80,443 your.domain.tld注意「从外部」这个前提——在主机本机测试无法模拟 CA 视角的网络路径防火墙规则如仅放行内网、云安全组配置错误、ISP 封锁入站 80 端口等只有从外部才能暴露。原因二域名未解析到主机的 IPv4 和/或 IPv6 地址授权请求的域名必须解析到你的主机公网可达的那台。用drill、dig或nslookup检查 A及存在时的 AAAA记录dig A your.domain.tld dig AAAA your.domain.tld确认 A 记录指向你主机的公网 IPv4若配置了 AAAA 记录则必须指向主机的公网 IPv6。任何解析到错误地址旧 IP、CDN 回源地址、内网地址都会让挑战请求落空。原因三有 AAAAIPv6记录但主机或 Docker 实际不可达 IPv6这是一个极易被忽略的坑只要域名带有 AAAA 记录Lets Encrypt 就会优先走 IPv6 发起挑战验证。虽然官方存在 IPv6→IPv4 的回退机制但并不能保证每种情况都生效docs/Lets-Encrypt-and-ACME.md 明确引用 boulder 项目 issue #2770 说明该限制。因此文档结论非常直接若不确定主机与 Docker 的 IPv6 可达性就不要发布 AAAA 记录否则挑战验证可能失败。排查方法在主机上创建一个测试 nginx 容器同时用 IPv4 与 IPv6 从外部 curl 验证youremotedockerhost$ docker run -d -p 80:80 nginx:alpine youlocalcomputer$ curl http://your.domain.tld !DOCTYPE html html head titleWelcome to nginx!/title [...] /html youlocalcomputer$ curl -6 http://your.domain.tld !DOCTYPE html html head titleWelcome to nginx!/title [...] /html若 IPv4 返回 nginx 欢迎页而curl -6失败说明 IPv6 链路不通此时应删除域名上的 AAAA 记录等待 DNS 修改在全球传播TTL 过期后再重新尝试授权。注意curl -6强制走 IPv6本地机器也必须具备 IPv6 连通性否则该测试无效。原因四DNS 服务商对 CAA 记录请求应答错误Lets Encrypt 在签发前会查询域的 CAA 记录官方 CAA 说明。关键点在于Lets Encrypt 并不要求你设置 CAA 记录但要求你的 DNS 服务商能正确应答 CAA 查询——如果服务商对 CAA 请求返回错误Lets Encrypt 将拒绝为该域名签发证书。排查方法文档建议阅读 Lets Encrypt 的 CAA 文档并使用 CAA 测试站点验证你的 DNS 服务商是否对 CAA 查询正确应答。一个典型的服务商故障表现是对不存在 CAA 记录的域名返回 SERVFAIL 或超时而非标准的「无记录」应答。原因五nginx-proxy / nginx / docker-gen / acme-companion 容器配置错误这是最常发生在「组合设置」中的问题。文档给出的排查动作是回读 Basic-usage.md 与 Advanced-usage.md 两份使用指南对照 nginx-proxy 项目的官方文档核对整体部署。其中被特别强调的一点是各容器之间的卷volumes必须共享。acme-companion 通过共享卷把签发的证书写入 nginx-proxy 能读取的位置默认/etc/nginx/certs并通过共享的/usr/share/nginx/html让 HTTP-01 挑战文件可被 nginx 对外提供。从 app/nginx_location.conf 可以看到nginx 侧专门为挑战文件配置了路由location ^~ /.well-known/acme-challenge/ { auth_basic off; auth_request off; allow all; root /usr/share/nginx/html; try_files $uri 404; break; }该 location 片段会被写入/usr/share/nginx/html目录下的挑战文件允许任何人访问。若/usr/share/nginx/html卷未在 nginx-proxy 与 acme-companion 之间正确共享挑战文件将「写不进/读不出」。acme-companion 启动时会主动检查该目录的可写性——app/entrypoint.sh 中的warn_html_directory函数若发现/usr/share/nginx/html不可写会打印Warning: cant access or write to /usr/share/nginx/html directory. This will prevent HTML-01 challenges from working correctly. If you are only using DNS-01 challenges, you can ignore this warning, otherwise check that / directory is declared as a writable volume.也就是说若你只使用 DNS-01 挑战可以忽略该警告此时不需要共享/usr/share/nginx/html正如 docs/Lets-Encrypt-and-ACME.md 所述「如果完全不打算使用 HTTP-01 挑战可以从两个容器上移除该卷」反之这条警告就是 HTTP-01 授权失败的直接线索。此外在独立的 3 容器部署nginx-proxy docker-gen acme-companion中docker-gen 负责根据容器环境变量生成服务数据文件模板见 app/letsencrypt_service_data.tmplacme-companion 依赖该文件/app/letsencrypt_service_data才知道要为哪些容器、哪些域名签发证书app/letsencrypt_service.sh。若 docker-gen 未运行、模板未正确挂载或/var/run/docker.sock未共享acme-companion 将拿不到任何待处理容器表现为「没有任何签发动作」。原因六遗漏VIRTUAL_HOST与ACME_HOST环境变量对被代理的应用容器VIRTUAL_HOST与ACME_HOST两者都必须设置。ACME_HOST上的每个域名必须同时出现在VIRTUAL_HOST上docs/Lets-Encrypt-and-ACME.md 要求ACME_HOST必须能解析到你的主机且通常与VIRTUAL_HOST相同。VIRTUAL_HOST告诉 nginx-proxy 该把哪些域名的请求路由到本容器ACME_HOST告诉 acme-companion 为本容器签发哪些域名的证书。只设其一都会导致行为不完整只有VIRTUAL_HOST则 nginx 正常路由但永远等不到证书只有ACME_HOST则证书签发但 nginx 不路由该域名挑战请求无法到达。对应关系在模板中也能印证app/letsencrypt_service_data.tmpl 只采集设置了ACME_HOST或旧名LETSENCRYPT_HOST的容器。原因七acme-companion 或 nginx.tmpl 版本过旧3 容器部署如果你使用独立的 3 容器部署nginx-proxy / docker-gen / acme-companion 各自独立运行还可能遇到版本不同步问题重新拉取nginxproxy/acme-companion:latest镜像并同步获取 nginx-proxy 项目最新的nginx.tmpl文件。acme-companion 的新功能新环境变量、新挑战支持往往依赖新版 nginx.tmpl 生成的配置反之亦然两者混搭旧版本会造成授权或签发行为异常。非调试模式下验证挑战文件可达性文档特别提醒一个容易误判的细节在非调试模式下挑战文件会在授权流程结束后自动清理无论授权成功还是失败。因此如果你没开 DEBUG 模式授权失败后从外部curl挑战文件路径不会得到任何结果——这不代表挑战文件从未生成而是已被清理。如果你不想开启 DEBUG 模式可以在同一个挑战目录里手动创建一个测试文件用它来验证挑战文件路径从外部IPv4 与 IPv6是否可达youremotedockerhost$ docker exec your-le-container bash -c echo Hello world! /usr/share/nginx/html/.well-known/acme-challenge/hello-world youlocalcomputer$ curl http://yourdomain.tld/.well-known/acme-challenge/hello-world Hello world! youlocalcomputer$ curl -6 http://yourdomain.tld/.well-known/acme-challenge/hello-world Hello world!这个测试利用的正是上面提到的 nginx location 路由app/nginx_location.conf 与 app/functions.sh 中的location ^~ /.well-known/acme-challenge/。若两条curl都能返回Hello world!说明域名解析正确、80 端口从外部可达nginx-proxy 把/.well-known/acme-challenge/正确路由到了共享卷挑战文件目录可写、可读。任何一个环节失败curl都会超时或返回 404从而把问题定位到对应的网络/解析/卷共享层面。注意若你计划验证 IPv6 路径请同样用curl -6测试并确保你的本地机器具备 IPv6 连接。从高级设置回退到基础设置如果你在高级设置Advanced Setup即 3 容器 nginx-proxy docker-gen acme-companion 分离部署下排查困难文档给出的建议是直接回退到基础设置Basic Setupnginx-proxy 官方镜像内嵌 docker-gen 的一体化部署。高级设置并非强制要求——它带来的是模块化与可控性但也引入更多可能的故障点模板版本、docker-gen 配置、额外卷等。先用基础设置跑通授权流程再逐步迁移到高级设置是成本最低的排障策略。排查流程速查一个可复制的行动清单结合全文将授权失败排查归纳为以下可顺序执行的清单以DEBUG1重启 acme-companion并在被代理容器上设LETSENCRYPT_TESTtrue使用测试证书执行docker logs acme-companion-container从 acme.sh 详细日志--log /dev/stderr--debug 2中定位失败环节DNS-01 挑战尤其依赖这一步从外部主机用nmap验证 80/443 端口可达用dig/drill/nslookup核对 A 与 AAAA 记录指向若有 AAAA 记录用测试 nginx 容器 curl/curl -6验证 IPv6 双向可达不确定则删除 AAAA 记录用 CAA 测试工具确认 DNS 服务商能正确应答 CAA 查询回读 docs/Basic-usage.md 与 docs/Advanced-usage.md核对 nginx-proxy/nginx/docker-gen/acme-companion 各容器卷是否正确共享重点/etc/nginx/certs、/usr/share/nginx/html、/var/run/docker.sock确认被代理容器同时设置了VIRTUAL_HOST与ACME_HOST且ACME_HOST⊆VIRTUAL_HOST若为 3 容器部署重新拉取nginxproxy/acme-companion:latest并同步最新nginx.tmpl以上均无法定位时创建测试挑战文件并用curl/curl -6手动验证可达性仍不解决则回退到基础设置。赞分享云原生运维【免费下载链接】acme-companionAutomated ACME SSL certificate generation for nginx-proxy项目地址https://gitcode.com/gh_mirrors/ac/acme-companion点击查看免费下载相关推荐Multipass 故障排查完全指南日志、启动失败与网络问题的定位与修复Multipass 故障排查完全指南日志、启动失败与网络问题的定位与修复 Multipass 在 Linux、macOS 与 Windows 三大平台上均依赖虚拟化开发工具云原生Cleos 故障排查实战指南RPC 端点连接失败与 Missing Authorizations 权限错误的完整诊断Cleos 故障排查实战指南RPC 端点连接失败与 Missing Authorizations 权限错误的完整诊断 本篇技术指南聚焦 EOSIO 生态中区块链从登录失败到完美运行Authelia故障排查完全指南从登录失败到完美运行Authelia故障排查完全指南 作为一款强大的单点登录Single Sign On, SSO多因素认证Multi Factor A后端认证鉴权单点登录身份认证应用安全上一篇探索无线世界的钥匙 —— PortaPack H1 开源硬件项目深度解读下一篇现代出版革命Ghost CMS如何重塑独立创作的技术范式创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
