跳到主要内容
Nginx

Let’s Encrypt 证书部署 Nginx 完整教程:申请、配置、续期与排错

问题背景与根因:为什么证书签发了,Nginx 仍报链错误

Let’s Encrypt 是免费 DV 证书,当前单张证书有效期仍为 90 天,通过 ACME 协议由 certbot、acme.sh 等客户端自动申请和续期。Nginx 部署失败通常不是证书没签发,而是证书链、SNI、文件路径或 reload 环节出问题。最常见根因是只部署了叶子证书 cert.pem,没有把中间证书合并进 fullchain.pem;桌面浏览器有时会通过 AIA 补拉中间证书,所以看起来正常,但 curl、Java、微信小程序、旧 Android 会报 unable to get local issuer certificate。

第二个根因是证书与私钥不匹配,续期后仍指向旧文件;第三个根因是 80 端口被 301 到 HTTPS,ACME HTTP-01 的 /.well-known/acme-challenge/ 请求被重定向或返回 404;第四个根因是 server_name 与 SNI 不一致,Nginx 返回默认站点证书。排查时先执行 openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null,看返回链中是否至少包含站点证书和中间证书,并检查 Verify return code 是否为 0。

有效期也要更新认知:网上常见的公共 TLS 证书最长 398 天已过时。按 CA/B Forum SC-081,2026-03-15 起最长 200 天,2027-03-15 起 100 天,2029-03-15 起 47 天;Let’s Encrypt 当前仍签发 90 天证书,建议剩余 30 天左右续期。另需注意 Let’s Encrypt 已停止 OCSP 服务,不要再为它配置 ssl_stapling 并期待 OCSP 响应。

准备证书文件:fullchain、私钥、权限与格式核对

Nginx 使用 PEM 格式,生产配置应指向 fullchain.pem(站点证书+中间证书合并),私钥使用 privkey.pem 或 install-cert 生成的文件。只部署 cert.pem 会丢失中间证书,导致部分客户端链验证失败。CSR 只用于向 CA 申请证书,部署阶段不需要上传 CSR。使用 certbot 时建议让 Nginx 直接读取 /etc/letsencrypt/live/example.com/ 下的文件,避免复制后续期不同步;使用 acme.sh 时由 install-cert 复制到统一目录,并配置 reloadcmd。

sudo install -d -m 700 /etc/nginx/ssl
sudo ln -sf /etc/letsencrypt/live/example.com/fullchain.pem /etc/nginx/ssl/example.com.fullchain.pem
sudo ln -sf /etc/letsencrypt/live/example.com/privkey.pem /etc/nginx/ssl/example.com.key
sudo chmod 600 /etc/letsencrypt/archive/example.com/privkey*.pem
openssl crl2pkcs7 -nocrl -certfile /etc/nginx/ssl/example.com.fullchain.pem | openssl pkcs7 -print_certs -noout
openssl x509 -in /etc/nginx/ssl/example.com.fullchain.pem -noout -subject -issuer -dates

核对证书与私钥是否匹配:RSA 证书可比较模数,ECDSA 证书比较公钥哈希。两条命令输出一致才说明匹配;不一致时不要 reload,先重新 install-cert 或修正路径。私钥权限建议 600、属主 root,Nginx master 进程以 root 启动时可读取,worker 进程不需要直接读私钥。

openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa -noout -modulus -in example.com.key | openssl md5
openssl x509 -in fullchain.pem -noout -pubkey | openssl sha256
openssl pkey -in example.com.key -pubout | openssl sha256

完整实操一:certbot + Nginx 插件自动部署

certbot 的 Nginx 插件适合单机标准场景,会自动完成 HTTP-01 校验、写入 443 配置并添加 80 跳转。Ubuntu/Debian 先安装插件,RHEL 系使用 dnf 安装同名包。执行前确保 80 和 443 已放行、server_name 已解析到本机,且没有其他进程占用 80。命令中的 –redirect 会添加 HTTP 到 HTTPS 跳转,–no-eff-email 表示不订阅 EFF 邮件。

sudo apt update
sudo apt install -y certbot python3-certbot-nginx
sudo nginx -t
sudo certbot --nginx -d example.com -d www.example.com --redirect --agree-tos -m admin@example.com --no-eff-email
sudo certbot certificates
sudo certbot renew --dry-run
systemctl list-timers | grep certbot

如果插件修改后的配置不符合你的模板,可改用 certbot certonly --webroot -w /var/www/letsencrypt -d example.com -d www.example.com,再手动把 ssl_certificate 指向 /etc/letsencrypt/live/example.com/fullchain.pem。续期由 systemd timer 或 cron 触发,建议加 deploy-hook:certbot renew --deploy-hook 'systemctl reload nginx'。遇到速率限制时先用 –dry-run 或 staging 环境验证,不要反复真实申请。

完整实操二:acme.sh + webroot 手动部署

acme.sh 适合非 root、面板环境、多域名和多服务器分发。注意 acme.sh 默认 CA 可能不是 Let’s Encrypt,申请时要显式加 –server letsencrypt。webroot 模式要求 Nginx 在 80 端口把 /.well-known/acme-challenge/ 指向可写目录,并且该 location 必须放在 301 跳转之前。下面以 ECDSA P-256 证书为例,RSA 证书去掉 –keylength ec-256 和 install-cert 的 –ecc。

curl https://get.acme.sh | sh -s email=admin@example.com
source ~/.bashrc
sudo mkdir -p /var/www/letsencrypt
sudo chown -R www-data:www-data /var/www/letsencrypt
acme.sh --issue --server letsencrypt -d example.com -d www.example.com -w /var/www/letsencrypt --keylength ec-256
sudo mkdir -p /etc/nginx/ssl
acme.sh --install-cert -d example.com --ecc --key-file /etc/nginx/ssl/example.com.key --fullchain-file /etc/nginx/ssl/example.com.fullchain.pem --reloadcmd 'nginx -t && systemctl reload nginx'
acme.sh --list
crontab -l | grep acme.sh

RHEL/CentOS 上把 www-data 换成 nginx。install-cert 会把证书复制到指定路径,并在续期成功后执行 reloadcmd,因此 Nginx 配置应指向 install-cert 的目标文件,而不是 ~/.acme.sh 下的临时文件。手动演练续期可用 acme.sh --renew -d example.com --force,生产环境不建议频繁 force,以免触发 CA 速率限制。

Nginx 配置示例:TLS 1.2/1.3、HTTP 跳转与续期钩子

下面配置同时保留 ACME HTTP-01 校验路径和 80 跳转,443 启用 TLS 1.2/1.3。Nginx 1.25.1 及以上推荐用 http2 on;旧版本可改成 listen 443 ssl http2。ssl_ciphers 主要影响 TLS 1.2,TLS 1.3 套件由 OpenSSL 默认策略控制。HSTS 建议在确认全站及子域都支持 HTTPS 后再加 includeSubDomains,preload 更要谨慎。

server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;
    location ^~ /.well-known/acme-challenge/ {
        root /var/www/letsencrypt;
        default_type text/plain;
        try_files $uri =404;
    }
    location / {
        return 301 https://$host$request_uri;
    }
}
server {
    listen 443 ssl;
    listen [::]:443 ssl;
    http2 on;
    server_name example.com www.example.com;
    ssl_certificate     /etc/nginx/ssl/example.com.fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/example.com.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305';
    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; includeSubDomains' always;
    location / {
        root /var/www/html;
        index index.html;
    }
}

改完先执行 nginx -t,通过后再 systemctl reload nginx。不要为 Let’s Encrypt 配置 ssl_stapling on,否则可能看到 no OCSP responder URL 警告;需要吊销状态时可关注 CRL 方案。若使用商业 CA 且其提供 OCSP,再按 CA 文档单独开启 stapling。

方案对比:certbot、acme.sh、面板与商业证书怎么选

单机 Nginx 优先 certbot –nginx,省去手写配置;需要非 root、多环境分发或自定义 reload 时选 acme.sh;面板用户可直接用面板内置 Let’s Encrypt;对 OV/EV、赔付和技术支持有要求再考虑商业证书。无论哪种方案,Nginx 都必须部署 fullchain,并保证续期后 reload。公共证书有效期上限正在缩短,自动化续期比手工换证更重要。

r>

方案 申请方式 证书位置 续期机制 适用场景
certbot –nginx 自动改 Nginx 配置 /etc/letsencrypt/live/ systemd timer/cron 单机标准 Nginx
certbot certonly webroot/standalone /etc/letsencrypt/live/ deploy-hook reload 自定义配置模板
acme.sh 脚本 + webroot/DNS ~/.acme.sh 及 install-cert 目标 cron + reloadcmd 非 root、多服务器、面板
面板/商业证书 图形化或控制台 面板指定目录 面板任务 运维弱、需 OV/EV 支持

有效期规则也要纳入选型:2026-03-15 起公共 TLS 证书最长 200 天,2027-03-15 起 100 天,2029-03-15 起 47 天;Let’s Encrypt 当前为 90 天。证书越短,越依赖 certbot renew –dry-run、acme.sh 日志和 reloadcmd 的可靠性。商业证书即使有效期更长,也不能替代自动部署和监控。

常见错误排查:真实报错与修复命令

1. curl: (60) SSL certificate problem: unable to get local issuer certificate:服务端链不完整,九成是 ssl_certificate 指向了 cert.pem。改成 fullchain.pem,并用 openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout 确认包含中间证书。

2. nginx: [emerg] PEM_read_bio_X509_AUX(…) failed (SSL: error:0480006C:PEM routines::no start line):文件不是 PEM、路径错、下载成 DER/CRLF 或空文件。用 file fullchain.pem 和 head -1 fullchain.pem 检查是否以 —–BEGIN CERTIFICATE—– 开头。

3. nginx: [emerg] SSL_CTX_use_PrivateKey_file(…) failed:证书与私钥不匹配或私钥权限不可读。用前文的 modulus/pubkey 哈希比对,确认 install-cert 的 key-file 与 fullchain-file 来自同一张证书。

4. Invalid response from http://example.com/.well-known/acme-challenge/…: 404:webroot 路径不对、location 被 301 截获、目录权限不可读或 Cloudflare 代理拦截。用 curl -I http://example.com/.well-known/acme-challenge/test 验证,确保 challenge location 在 redirect 之前。

5. Problem binding to port 80: Could not bind to IPv4 or IPv6.:80 被 Apache、Nginx 或面板占用。停掉占用进程,或改用 webroot 模式复用现有 Nginx。另见 too many certificates already issued for exact set of domains,说明触发速率限制,应改用 staging 或等待窗口。

6. nginx: [warn] ssl_stapling ignored, no OCSP responder URL in the certificate:Let’s Encrypt 已停止 OCSP,删除 ssl_stapling on/ssl_stapling_verify on 即可,不影响正常 HTTPS。

效果验证:从 openssl 到 SSL Labs 与续期演练

先验证链和协议版本。Verify return code 应为 0 (ok),Protocol 应为 TLSv1.3 或 TLSv1.2,链中证书数量至少为 2。再用 curl 模拟普通客户端,最后用 SSL Labs 看整体评级。若 curl 正常但 Java 报错,仍要回查 fullchain 和中间证书顺序。

openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | grep -E 'Verify return code|Protocol|Cipher'
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | grep -c 'BEGIN CERTIFICATE'
curl -vI https://example.com 2>&1 | grep -E 'SSL certificate verify|subject:|issuer:'
curl --tlsv1.2 -I https://example.com

续期演练必须做:certbot 执行 sudo certbot renew --dry-run;acme.sh 检查 crontab 和 ~/.acme.sh/acme.sh.log,并用 acme.sh --list 看下次续期时间。最后打开 https://www.ssllabs.com/ssltest/analyze.html?d=example.com,确认证书链、协议和 HSTS 均符合预期。生产变更后建议同时检查 nginx -T | grep -E 'ssl_certificate|server_name',避免配置被其他 include 覆盖。

常见问题

Let’s Encrypt 当前仍为 90 天,建议剩余 30 天左右续期。公共 TLS 证书最长有效期已不是 398 天:2026-03-15 起为 200 天,2027-03-15 起 100 天,2029-03-15 起 47 天。实际以 CA 签发和 CA/B 规则为准。

填 fullchain.pem,即站点证书加中间证书;只填 cert.pem 会导致部分客户端报 unable to get local issuer certificate。私钥填 privkey.pem 或 install-cert 生成的 key 文件,权限建议 600。

续期只更新文件,Nginx 不会自动读取新文件;需执行 nginx -t && systemctl reload nginx。certbot 的 nginx 插件和 acme.sh 的 –reloadcmd 应配置 reload,并检查配置路径是否指向 live 目录或 install-cert 目标。

检查 80 端口、/.well-known/acme-challenge/ 的 location 是否在 301 之前、root 是否指向 webroot、目录权限是否可读;用 curl -I http://example.com/.well-known/acme-challenge/test 验证。Cloudflare 代理需先关闭或放行。

不需要。Let’s Encrypt 已停止 OCSP 服务,配置 ssl_stapling on 可能得到 no OCSP responder URL 警告;保持关闭即可,证书链和 CRL 不影响常规 HTTPS。若用商业 CA 再按其 OCSP 地址配置。

内容审核

长期从事 SSL/TLS 证书部署与 HTTPS 运维,负责本站证书选型、安装配置与故障排查内容的编写与审核。