Let's Encrypt - LetsEncrypt故障排查

发布时间:2026-05-02 08:00

一、前言 干了10年运维，Let's Encrypt 这玩意儿用得多了，从最初的 ACME 协议配置到后期的自动续期，少说碰到过几十种报错。dns解析失败、端口占用、权限问题、nginx 配置冲突，每一种都能让你折腾半天。今天把踩过的坑整理成实战手册，遇到问题直接查，少走弯路。 二、操作步骤

步骤1：确认 Certbot 安装状态与版本

检查 certbot 是否已安装，以及当前版本信息。不同系统安装方式不同，先确认工具链完整。 **CentOS/RHEL (EL7+)：** ```bash sudo yum install certbot python2-certbot-nginx certbot --version ``` 预期输出： ``` certbot 1.28.0 ``` **Ubuntu：** ```bash sudo apt update sudo apt install certbot python3-certbot-nginx certbot --version ``` 预期输出： ``` certbot 2.0.0 ``` 版本号可能略有差异，但只要能返回版本信息就说明安装正常。如果提示 command not found，说明 certbot 未安装或路径问题，先把安装搞定再往下走。

步骤2：验证域名 DNS 解析是否生效

Let's Encrypt 验证域名所有权依赖 DNS 解析，解析不到就报 unauthorized。这步很多人跳过，以为是其他问题。 ```bash nslookup your-domain.com # 或者 dig your-domain.com A +short ``` 预期输出： ``` your-domain.com canonical name = cloudfront.net. Address: 52.85.XXX.XXX ``` 如果返回 NXDOMAIN 或空，说明 DNS 还没生效，或者记录配错了。泛证书（*.your-domain.com）也需要对应 wildcard 记录。检查域名 registrar 或 DNS provider 的配置，确保 A 记录指向你的服务器 IP。

步骤3：检查 80 端口是否被占用

HTTP 验证方式需要 80 端口空闲，如果 nginx、apache 或其他服务占用了，certbot 会直接报错。 ```bash sudo ss -tlnp | grep ':80' # 或 sudo netstat -tlnp | grep ':80' ``` 预期输出（无输出表示端口空闲）： ``` LISTEN 0 128 *:80 *:* 12345/nginx: worker ``` 如果有 nginx 在监听，停了它再跑 certbot： ```bash # CentOS/RHEL sudo systemctl stop nginx # Ubuntu sudo systemctl stop nginx ``` ⚠️ **警告**：如果服务器正在跑生产网站，停 nginx 会导致短暂中断。建议使用 --webroot 模式或先测试完成再恢复。

步骤4：执行证书申请（standalone 模式）

standalone 模式临时启动验证服务，适合首次申请且没有 web 服务器的场景。 ```bash sudo certbot certonly --standalone -d your-domain.com -d www.your-domain.com ``` 预期输出： ``` Saving debug log to /var/log/letsencrypt/letsencrypt.log Requesting a certificate for your-domain.com and www.your-domain.com Successfully received certificate. Certificate is saved at: /etc/letsencrypt/live/your-domain.com/fullchain.pem Certificate chain is saved at: /etc/letsencrypt/live/your-domain.com/chain.pem ``` 如果报以下错误： ``` An authentication error occurred... Details: There were too many requests of API requests ``` 说明请求频率超限，等几分钟再试或者用 staging 环境测试： ```bash sudo certbot certonly --standalone -d your-domain.com --staging ```

步骤5：配置 Nginx 使用 SSL 证书

证书申请成功后，修改 nginx 配置指向证书路径。 ```bash sudo vim /etc/nginx/conf.d/your-domain.com.conf ``` 添加/修改 server 块： ```nginx server { listen 443 ssl http2; server_name your-domain.com www.your-domain.com; ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem; ssl_session_timeout 1d; ssl_session_cache shared:SSL:50m; # 安全加固 ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256; ssl_prefer_server_ciphers off; root /var/www/html; index index.html; } ``` 验证配置并重载： ```bash # CentOS/RHEL sudo nginx -t && sudo systemctl reload nginx # Ubuntu sudo nginx -t && sudo systemctl reload nginx ``` 预期输出： ``` nginx: the configuration file /etc/nginx/nginx.conf syntax is ok nginx: configuration file /etc/nginx/nginx.conf test is successful ```

步骤6：设置自动续期与定时任务

Let's Encrypt 证书有效期 90 天，必须设置自动续期。certbot 安装后通常自带 timer，但需要确认状态。 ```bash # 查看续期定时器状态 sudo systemctl status certbot-renew.timer ``` 预期输出： ``` ● certbot-renew.timer - This is the timer... Loaded: loaded (/usr/lib/systemd/system/certbot-renew.timer; enabled; vendor preset: enabled) Active: active (waiting) ``` 如果状态是 inactive，手动启用： ```bash sudo systemctl enable certbot-renew.timer sudo systemctl start certbot-renew.timer ``` 测试续期命令dry-run： ```bash sudo certbot renew --dry-run ``` 预期输出： ``` ** DRY RUN: simulate 'certbot renew' output 佳跃 renew result: success ** DRY RUN: simulate 'certbot renew' output The following certs are due for renewal: /etc/letsencrypt/live/your-domain.com/fullchain.pem (expires 2024.03.15) ``` ⚠️ **警告**：自动续期后需要重载 nginx。如果使用其他 web server，需额外配置 post-hook： ```bash sudo certbot renew --deploy-hook "systemctl reload nginx" ```

步骤7：排查续期失败的常见原因

续期失败通常不是 certbot 本身的问题，而是环境变化。常见原因及排查： **检查1：cron/systemd 日志** ```bash # 如果用 cron sudo cat /var/log/cron | grep certbot # 如果用 systemd sudo journalctl -u certbot-renew -n 50 ``` **检查2：证书路径是否还存在** ```bash sudo ls -la /etc/letsencrypt/renewal/ cat /etc/letsencrypt/renewal/your-domain.com.conf ``` 如果 renewal 配置文件丢失，需要重新生成： ```bash sudo certbot certonly --webroot -w /var/www/html -d your-domain.com -d www.your-domain.com --deploy-hook "systemctl reload nginx" ``` **检查3：防火墙是否阻止了 80/443** ```bash sudo firewall-cmd --list-all # 或 sudo iptables -L -n | grep -E '80|443' ``` 三、常见问题FAQ **Q1: 续期时报 "Account registered does not match" 或认证失败怎么办？** 这通常是 certbot 客户端版本升级导致的兼容问题。旧版本创建的账户信息在新版可能不识别。解决方案：备份后删除旧配置，清理缓存，重新申请。 ```bash # 备份 sudo cp -r /etc/letsencrypt /etc/letsencrypt.bak # 删除问题账户和缓存 sudo rm -rf /etc/letsencrypt/accounts/* sudo rm -rf /var/lib/certbot/* # 重新注册 sudo certbot register --email admin@your-domain.com --agree-tos ``` **Q2: nginx 重载后 SSL 不生效，浏览器还是旧证书？** 八成是 nginx 缓存或者浏览器缓存没清。先确认 nginx 加载的是新证书： ```bash # 检查实际加载的证书 sudo openssl s_client -connect your-domain.com:443 -servername your-domain.com 2>/dev/null | openssl x509 -noout -dates ``` 如果证书时间没变，说明配置没生效。再检查一遍配置路径是否正确： ```bash sudo nginx -T | grep ssl_certificate ``` 最后清除浏览器缓存，或者用隐私模式访问确认。 **Q3: DNS-01 验证方式配置失败，泛域名证书申请不了？** dns-01 模式需要 DNS provider 提供 API 接口来自动添加 TXT 记录。常见的 Cloudflare、阿里云 DNSPod 都有插件： ```bash # Cloudflare 插件 sudo certbot plugins | grep cloudflare # 安装 cloudflare 插件（需要 python3-certbot-dns-cloudflare 包） sudo yum install python3-certbot-dns-cloudflare # Ubuntu: sudo apt install python3-certbot-dns-cloudflare # 配置 API token sudo vim /etc/letsencrypt/cloudflare.ini # 写入：dns_cloudflare_api_token = YOUR_CLOUDFLARE_TOKEN sudo chmod 600 /etc/letsencrypt/cloudflare.ini # 申请泛域名 sudo certbot certonly --dns-cloudflare --dns-cloudflare-credentials /etc/letsencrypt/cloudflare.ini -d your-domain.com -d *.your-domain.com ``` 如果你的 DNS provider 不在 certbot 官方支持列表里，就得手动加 TXT 记录然后等生效，验证完成后再删掉。或者换用支持 API 的 DNS provider。 四、总结 核心要点：Let's Encrypt 故障排查的核心思路是「验证链」——从 DNS 解析、端口占用、验证方式、到证书配置、续期机制，每一步都可能出问题。遇到报错先看日志，certbot 的 debug log 在 /var/log/letsencrypt/letsencrypt.log，基本能定位到具体环节。记住三个关键点：① 确保域名解析先通；②standalone 模式需要 80 端口空闲；③ 续期后必须 reload web server。 延伸阅读：Certbot 官方文档 https://eff-certbot.readthedocs.io/ ；Let's Encrypt 测试环境 https://letsencrypt.org/docs/staging-environment/ （用 staging 环境测试避免频率限制）；Mozilla SSL Configuration Generator https://ssl-config.mozilla.org/ （生成安全加固后的 SSL 配置模板）。