Let’s Encrypt 证书 Nginx 部署全流程:申请、配置、自动续期与报错排查
一、问题背景与根因:为什么证书“装上了”却仍然报错
Let’s Encrypt 是 ISRG 运营的免费 DV CA,通过 ACME v2 协议签发证书,固定 90 天有效期,支持多域名 SAN 与通配符(通配符只能走 DNS-01)。先纠正两个常见过时认知:第一,公开信任的 TLS 证书最长有效期受 CA/Browser Forum 基线要求约束,目前上限是 398 天,Let’s Encrypt 的 90 天是刻意设计的短周期,用短寿命倒逼自动化续期;第二,Let’s Encrypt 已于 2025 年 1 月 30 日停止 OCSP 响应服务,并从 2025 年 5 月 7 日起不再在签发的证书中写入 OCSP URL,因此给 LE 证书配置 ssl_stapling on 已无实际收益,Nginx 日志还会给出告警。
部署到 Nginx 后“浏览器正常、程序报错”的根因基本落在五类:
- 证书链不完整:只配了叶子证书
cert.pem而非fullchain.pem。桌面浏览器会自动补链,但 Java、旧版 Android、微信小程序、部分 curl 的 CA bundle 会直接校验失败。 - 私钥不可读或权限过宽:
privkey.pem权限 644 会被 Nginx 告警,应为 600 且属主 root。 - 续期后未 reload:Nginx 只在启动或重载时读取证书文件,续期写入新文件后进程仍持有旧证书。
- HTTP-01 校验失败:80 端口被安全组、CDN 或其他 server 块拦截,
.well-known路径被 rewrite 规则吞掉。 - SNI 与默认 server 错配:多站点共用 443 时,未匹配 SNI 的请求落到第一个 server 块,返回错误证书。
下面按“准备 → 申请 → 配置 → 校验 → 续期 → 排错 → 验证”的顺序给出可直接执行的流程,示例域名为 example.com,系统以 Ubuntu 22.04 / Rocky 9 为准。
二、环境准备与 ACME 客户端选型
Nginx 侧需要满足三个前提:OpenSSL 1.1.1 以上(否则无法启用 TLS 1.3)、Nginx 1.15 以上、80/443 对公网可达。先确认版本与端口占用:
nginx -v
openssl version
ss -lntp | grep -E ':80|:443'
dig +short example.com A
客户端二选一。certbot 与 Nginx 集成最深,适合单机少量站点;acme.sh 是纯 Shell 实现,无 Python 依赖,DNS API 覆盖最全,适合通配符与内网机器。
# Debian / Ubuntu
sudo apt update
sudo apt install -y certbot python3-certbot-nginx openssl
# RHEL / Rocky / AlmaLinux 9
sudo dnf install -y certbot python3-certbot-nginx
# acme.sh(普通用户即可安装)
curl https://get.acme.sh | sh -s email=ops@example.com
source ~/.bashrc
acme.sh --set-default-ca --server letsencrypt
acme.sh --version
注意点:python3-certbot-nginx 插件只在用 --nginx 自动改写配置时需要;采用 webroot 或 DNS 方式时装 certbot 主包即可。acme.sh 从 2021 年起默认 CA 已改为 ZeroSSL,必须显式执行 --set-default-ca --server letsencrypt,否则签发出来的不是 LE 证书。所有申请操作先加 --dry-run(certbot)或 --staging(acme.sh)跑一遍,避免触发生产环境速率限制:每个注册域名每周 50 张、同一组域名每周 5 张重复证书。
另外确认 /etc/nginx/ssl 或 /etc/letsencrypt/live 所在分区可写,以及服务器时间已同步(timedatectl 显示 synchronized: yes),时钟偏差超过 5 分钟会导致 ACME 签名校验失败。
三、申请证书:certbot 与 acme.sh 的四种验证方式
方式 A,certbot 自动改写 Nginx(最快,适合首次部署):
sudo certbot --nginx -d example.com -d www.example.com \
--agree-tos -m ops@example.com --redirect --keep-until-expiring
--redirect 会自动插入 80→443 跳转,证书落在 /etc/letsencrypt/live/example.com/。
方式 B,webroot(配置可控,推荐生产环境):
sudo mkdir -p /var/www/letsencrypt/.well-known/acme-challenge
sudo chown -R www-data:www-data /var/www/letsencrypt
sudo certbot certonly --webroot -w /var/www/letsencrypt -d example.com -d www.example.com --dry-run
sudo certbot certonly --webroot -w /var/www/letsencrypt -d example.com -d www.example.com
对应 Nginx 必须放行校验路径,且位置要放在所有 rewrite 之前(用 ^~ 前缀匹配可阻止正则 location 抢占):
location ^~ /.well-known/acme-challenge/ {
root /var/www/letsencrypt;
default_type text/plain;
}
方式 C,standalone(无 Web 服务或临时停机窗口):
sudo systemctl stop nginx
sudo certbot certonly --standalone -d example.com
sudo systemctl start nginx
方式 D,DNS-01 通配符(内网、无法开放 80 端口、需要 *.example.com):
# acme.sh 手动 DNS
export Ali_Key=your_key Ali_Secret=your_secret
acme.sh --issue --dns dns_ali -d example.com -d '*.example.com'
# 无 DNS API 时用交互模式
acme.sh --issue --dns -d example.com -d '*.example.com' --yes-I-know-dns-manual-mode-enough-go-ahead-please
通配符只能通过 DNS-01 签发,且 *.example.com 不覆盖 example.com 本身,必须同时写两条 -d。签发完成后,证书默认保存在 /etc/letsencrypt/live/example.com/ 或 ~/.acme.sh/example.com_ecc/。
四、Nginx 完整配置示例(TLS 1.2/1.3、HSTS、HTTP/2)
以下配置可直接套用,注意 Nginx 1.25.1 起 listen 443 ssl http2 中的 http2 参数已弃用,改用独立的 http2 on; 指令,否则日志会提示 the "listen ... http2" directive is deprecated。
server {
listen 80;
server_name example.com www.example.com;
location ^~ /.well-known/acme-challenge/ {
root /var/www/letsencrypt;
default_type text/plain;
}
location / {
return 301 https://$host$request_uri;
}
}
server {
listen 443 ssl;
http2 on;
server_name example.com www.example.com;
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
ssl_trusted_certificate /etc/letsencrypt/live/example.com/chain.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers off;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
ssl_session_tickets off;
add_header Strict-Transport-Security max-age=31536000 always;
add_header X-Content-Type-Options nosniff always;
location / {
root /var/www/html;
index index.html;
}
}
逐项说明:ssl_certificate 必须指向 fullchain.pem,cert.pem 只是叶子证书,单独使用必然断链;ssl_trusted_certificate 仅用于 OCSP stapling 的链验证,由于 LE 已停止 OCSP,该行可保留但不会产生 stapling 效果;ssl_session_tickets off 牺牲少量性能换取前向安全;不要引用 1024 位 dhparam 文件,否则报 dh key too small。改完后先执行 nginx -t 校验,再用 nginx -s reload 生效,避免 restart 造成连接中断。若前面挂了 CDN,务必确认回源使用 443 且 SNI 正确。
五、上线前的三项硬校验与方案对比
在 reload 之前,先用 OpenSSL 把证书本身查清楚,三项检查缺一不可:
cd /etc/letsencrypt/live/example.com
# 1. 链是否完整:应输出叶子 + 至少一张中间证书
openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout
# 2. 证书与私钥是否匹配:两行 MD5 必须完全一致
openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa -noout -modulus -in privkey.pem | openssl md5
# 3. 有效期与 SAN 域名
openssl x509 -in fullchain.pem -noout -subject -issuer -dates -ext subjectAltName
四种验证方式的取舍如下表:
| 验证方式 | 适用场景 | 关键参数 | 是否需停 Nginx | 支持通配符 |
|---|---|---|---|---|
| HTTP-01 + webroot | 有公网 80 端口,生产首选 | --webroot -w |
否 | 不支持 |
| HTTP-01 + nginx 插件 | 首次部署、配置简单 | --nginx --redirect |
否 | 不支持 |
| standalone | 无 Web 服务、临时机器 | --standalone |
是(占用 80) | 不支持 |
| DNS-01 | 内网、通配符、80 被封 | --dns dns_ali |
否 | 支持 |
四个文件的作用也要分清,混用是断链的头号原因:
| 文件 | 内容 | 对应 Nginx 指令 |
|---|---|---|
| fullchain.pem | 叶子证书 + 中间证书 | ssl_certificate |
| cert.pem | 仅叶子证书 | 禁止单独使用 |
| chain.pem | 仅中间证书 | ssl_trusted_certificate |
| privkey.pem | 私钥(RSA 2048 或 ECDSA P-256) | ssl_certificate_key |
私钥权限执行 chmod 600 privkey.pem,属主保持 root,Nginx master 进程以 root 启动即可读取,worker 进程降权后不影响。
六、自动续期与 reload 钩子(90 天证书的生命线)
certbot 安装时会自动注册 systemd timer,每天运行两次并带随机延迟,证书剩余 30 天内自动续期。先确认定时器状态并做一次演练:
systemctl list-timers | grep certbot
systemctl status certbot.timer
sudo certbot renew --dry-run
关键在 deploy 钩子:certbot 续期成功后不会自动重载 Nginx,必须自己挂脚本。把可执行脚本放进 renewal-hooks/deploy 目录即可对所有证书生效:
sudo tee /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh >/dev/null <<'EOF'
#!/bin/sh
nginx -t && systemctl reload nginx
EOF
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh
脚本里先 nginx -t 再 reload,可以避免配置有误时把线上打挂。若使用 acme.sh,则在安装证书时用 --reloadcmd 绑定,acme.sh 会把它写进续期任务:
acme.sh --install-cert -d example.com \
--key-file /etc/nginx/ssl/example.com.key \
--fullchain-file /etc/nginx/ssl/example.com.fullchain.pem \
--reloadcmd 'systemctl reload nginx'
用 crontab -l | grep acme 可看到 acme.sh 写入的每日 0 点任务。注意 --install-cert 会把证书复制到指定路径,此后 Nginx 配置必须指向复制后的文件,而不是 ~/.acme.sh 下的源文件,否则续期后路径不一致。最后建议加一条到期监控,剩余天数低于 20 天时告警,防止定时任务静默失败。
七、常见错误排查:从真实报错到修复命令
以下报错均来自实际环境,按现象对照处理:
| 报错信息 | 根因 | 修复 |
|---|---|---|
nginx: [emerg] cannot load certificate "...fullchain.pem": PEM_read_bio_X509_AUX() failed |
路径错、文件是下载页 HTML、或文件被截断 | file fullchain.pem 与 openssl x509 -in fullchain.pem -noout -subject 验证 |
curl: (60) SSL certificate problem: unable to get local issuer certificate |
链不完整,只配了叶子证书 | 改用 fullchain.pem,s_client -showcerts 应输出 2 张以上 |
java.security.cert.CertPathValidatorException: PKIX path building failed |
同上,Java 不自动补链 | 同上,并确认 truststore 含 ISRG Root X1 |
nginx: [warn] "ssl_stapling" ignored, issuer certificate not found for certificate |
未配 ssl_trusted_certificate,或 LE 证书已无 OCSP URL | 补 chain.pem,或直接移除 stapling 相关指令 |
Certbot failed to authenticate some domains ... Timeout during connect (likely firewall problem) |
80 端口不可达、CDN 回源异常、安全组未放行 | curl -I http://example.com/.well-known/acme-challenge/test 自测,或改 DNS-01 |
nginx: [emerg] SSL_CTX_use_PrivateKey_file(...) failed (SSL: error:0A00018A:SSL routines::dh key too small) |
引用了 1024 位 dhparam | openssl dhparam -out /etc/nginx/dhparam.pem 2048 |
nginx: [emerg] PEM_read_bio_PrivateKey() failed ... bad decrypt |
私钥与证书不匹配,或私钥被二次加密 | 用第五节 modulus MD5 比对,必要时重新签发 |
还有一类无报错但“续期后浏览器仍显示旧证书”的情况:先确认 systemctl status certbot.timer 与 ls -l /etc/letsencrypt/live/example.com/ 的时间戳,再检查是否有 CDN 缓存证书、是否 reload 了错误的 Nginx 实例(容器内与宿主机各有一份)。用 openssl s_client -connect 127.0.0.1:443 -servername example.com 直连本机,可以快速区分是 Nginx 问题还是链路缓存问题。
八、效果验证:命令行、评级与到期监控
部署完成后按下面五条命令逐项验证,全部通过再切流量:
# 1. 握手协议、加密套件与链验证结果(应为 0 (ok))
echo | openssl s_client -connect example.com:443 -servername example.com -CAfile /etc/ssl/certs/ca-certificates.crt 2>/dev/null | grep -E 'Protocol|Cipher|Verify return code'
# 2. 证书主题、颁发者、到期时间
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates
# 3. HTTP/2 与 HSTS 响应头
curl -sSI https://example.com | grep -Ei 'HTTP/|strict-transport'
# 4. 剩余天数检查(1728000 秒 = 20 天)
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null | openssl x509 -noout -checkend 1728000 && echo OK || echo RENEW_SOON
# 5. SSL Labs 评级(异步接口,首次需等待)
curl -s 'https://api.ssllabs.com/api/v3/analyze?host=example.com&all=done&publish=off' | grep -o '"grade": *"[A-F+]*"'
预期结果:Verify return code: 0 (ok),Protocol 为 TLSv1.3 或 TLSv1.2,响应头包含 strict-transport-security: max-age=31536000,SSL Labs 评级 A 及以上。若评级掉到 B,通常是仍启用了 TLS 1.0/1.1 或使用了 CBC 套件,回到第四节调整 ssl_protocols 与 ssl_ciphers 即可。
最后把 certbot renew --dry-run 加入发布流程的回归项,并给到期监控配置告警通道。90 天证书的运维重点不在“签一次”,而在“每次都能自动续、续完自动生效”。
常见问题
固定 90 天,不支持延长。公开信任的 TLS 证书有效期上限受 CA/B 论坛约束,目前为 398 天;Let’s Encrypt 刻意采用 90 天短周期推动自动化续期,2025 年起还提供 6 天有效期的 shortlived profile 供高安全场景选择。到期前 30 天 certbot 或 acme.sh 会自动续期,无需人工操作。
单机少量站点、希望自动改写 Nginx 配置的选 certbot,与 Nginx 集成最成熟;需要通配符、内网机器、几十个域名批量管理或没有 Python 环境的选 acme.sh,它的 DNS API 覆盖最全。两者可以共存,但同一张证书不要用两个客户端重复申请,否则会撞上每周 5 张的重复证书限制。
九成是没 reload。Nginx 只在启动或重载时读取证书文件,必须在 renewal-hooks/deploy 里挂 nginx -t && systemctl reload nginx。其次是 CDN 或负载均衡层缓存了证书,或容器内外各有一份 Nginx。用 openssl s_client 直连 127.0.0.1:443 可快速定位是服务端还是链路缓存问题。
可以,改用 DNS-01 验证。用 acme.sh 配合 DNS 服务商 API(如 dns_ali、dns_cf)全自动签发,无需开放任何入站端口,还能顺带申请通配符证书。certbot 也可通过第三方 DNS 插件实现,但生态不如 acme.sh 丰富。注意通配符要同时写 *.example.com 和 example.com 两条 -d。
配置写法完全一致,都是 PEM 格式的 fullchain 加私钥,差别在证书文件命名和路径。技术上主要差异是有效期:付费 DV 最长 398 天,Let’s Encrypt 为 90 天;OV/EV 额外做组织身份审核,浏览器 UI 已不再区别展示。因此除非有合规或保险要求,Nginx 场景用 Let’s Encrypt 加自动续期即可。