Docker Letsencrypt Nginx Proxy Companion 证书更新失败问题分析与解决

问题现象

在使用 Docker Letsencrypt Nginx Proxy Companion 项目时，用户遇到了一个典型的 HTTPS 证书验证失败问题。具体表现为：

1. 主域名 nextcloud.mydomain.com 的证书验证正常
2. 子域名 office.mydomain.com 的证书验证失败，返回 400 错误
3. 访问 HTTPS 版本的子域名时出现自签名证书警告
4. 日志显示 ACME 挑战验证失败："Invalid response from http://office.mydomain.com/.well-known/acme-challenge/..."

根本原因分析

经过深入分析，这个问题主要由以下因素导致：

1. Nginx Proxy 版本不兼容：用户使用的是较旧的 1.5-alpine 版本的 nginx-proxy 镜像，与新版本的 acme-companion 存在兼容性问题。

2. ACME 挑战验证失败：Let's Encrypt 的验证服务器无法通过 HTTP 协议访问到子域名的挑战文件，返回了 400 错误状态码。

3. 证书更新机制中断：由于验证失败，导致证书无法自动更新，最终回退到自签名证书状态。

解决方案

解决此问题的步骤如下：

1. 升级 nginx-proxy 镜像：将 nginx-proxy 从 1.5-alpine 版本升级到 1.6-alpine 版本，确保与最新版 acme-companion 兼容。

2. 验证网络连通性：确保验证服务器能够通过 HTTP 80 端口访问到子域名的 /.well-known/acme-challenge/ 路径。

3. 清理旧证书：删除旧的证书文件，强制 acme-companion 重新生成新的证书。

技术细节

在 ACME 协议的工作流程中，Let's Encrypt 会通过 HTTP 请求验证域名的所有权。验证服务器会尝试访问：

http://[你的域名]/.well-known/acme-challenge/[随机令牌]

如果这个请求无法返回正确的响应（包含预期的令牌内容），验证就会失败。常见的失败原因包括：

• 网络访问限制阻止了 80 端口的访问
• Nginx 配置没有正确处理 /.well-known 路径
• 容器间的网络通信问题
• 版本不兼容导致的路径映射错误

最佳实践建议

1. 保持组件版本同步：确保 nginx-proxy 和 acme-companion 使用相互兼容的版本。

2. 定期检查证书状态：设置监控机制，及时发现证书更新失败的情况。

3. 验证网络配置：确保验证服务器能够通过公网访问到容器的 80 端口。

4. 查看详细日志：遇到问题时，启用 acme-companion 的调试日志模式，获取更详细的错误信息。

总结

通过升级 nginx-proxy 到兼容版本，用户成功解决了证书验证失败的问题。这个案例提醒我们，在使用容器化解决方案时，保持各组件的版本兼容性至关重要。同时，理解 ACME 协议的工作原理有助于快速定位和解决证书相关的问题。