Nginx 部署 SSL 证书完整教程:fullchain、TLS 1.3 与 HTTPS 故障排查
问题背景与根因:HTTPS 部署失败的四个高频原因
很多站点在 Nginx 上启用 HTTPS 后出现浏览器证书错误、curl 报错或跳转异常。根因通常不是证书没签发,而是部署细节:1)只上传站点证书,缺中间证书,导致部分客户端报 unable to get local issuer certificate;2)已写 listen 443 ssl,但 ssl_certificate 路径错或配置块未加载;3)仍启用 TLS 1.0/1.1,或使用 HIGH:!aNULL:!MD5 这类宽泛套件,被安全扫描扣分;4)Nginx 1.25.1 后 listen ... http2 语法废弃,重载出现 warning。先做基线检查:openssl x509 -in example.com.fullchain.pem -noout -subject -issuer -dates 看主题、签发者、有效期;openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 看证书链。若 Verify return code 非 0,优先补链。还要确认有效期规则:公开信任证书最长 398 天,Let’s Encrypt 为 90 天,必须自动续期。下面按“证书准备→上传→配置→跳转→验证→排错”完整落地。
证书文件准备:fullchain、私钥与有效期规则
CA 签发后通常给:example.com.crt(站点证书)、example.com.key(私钥)、intermediate.crt(中间证书)。Nginx 的 ssl_certificate 必须指向 fullchain:站点证书在前,中间证书在后,顺序不能反。拼接命令:cat example.com.crt intermediate.crt > example.com.fullchain.pem。检查链数量:grep -c 'BEGIN CERTIFICATE' example.com.fullchain.pem,一般至少 2。私钥不能带密码,Nginx 启动不会交互输入;若带密码,用 openssl rsa -in example.com.key -out example.com.key.nopass 去掉密码。核对证书与私钥匹配:openssl x509 -noout -modulus -in example.com.fullchain.pem | openssl md5 与 openssl rsa -noout -modulus -in example.com.key | openssl md5 输出应一致。有效期:openssl x509 -in example.com.fullchain.pem -noout -dates。公开信任 CA 证书最长 398 天,Let’s Encrypt 为 90 天;不要手工续期,用 certbot/acme.sh 定时任务。CSR 可用 openssl req -new -newkey rsa:2048 -nodes -keyout example.com.key -out example.com.csr -subj '/CN=example.com' 生成。若用 ECDSA,openssl ecparam -genkey -name prime256v1 -out example.com.key。注意:ssl_certificate 用 fullchain,ssl_trusted_certificate 用中间证书链文件,二者不要混用。
上传证书并设置权限:目录 700、私钥 600
上传到 /etc/nginx/ssl/,不要放网站根目录。执行:sudo mkdir -p /etc/nginx/ssl、sudo chmod 700 /etc/nginx/ssl、sudo chown root:root /etc/nginx/ssl、sudo install -m 644 example.com.fullchain.pem /etc/nginx/ssl/、sudo install -m 600 example.com.key /etc/nginx/ssl/、sudo install -m 644 example.com.chain.pem /etc/nginx/ssl/、ls -l /etc/nginx/ssl。期望 fullchain 和 chain 为 -rw-r--r--,key 为 -rw-------,目录 drwx------。Nginx master 以 root 打开证书后传给 worker,私钥 600 且属主 root 仍可读;不要改成 644。SELinux 系统需打标签:sudo semanage fcontext -a -t httpd_sys_content_t '/etc/nginx/ssl(/.*)?' 然后 sudo restorecon -Rv /etc/nginx/ssl,否则可能报 Permission denied。AppArmor 同理检查 /etc/apparmor.d/usr.sbin.nginx。上传后静态校验:openssl x509 -in /etc/nginx/ssl/example.com.fullchain.pem -noout -subject -issuer -dates;openssl pkey -in /etc/nginx/ssl/example.com.key -noout -check。若私钥有密码,openssl pkey 会提示输入,Nginx reload 会失败。确认 SAN 包含域名:openssl x509 -in /etc/nginx/ssl/example.com.fullchain.pem -noout -ext subjectAltName。缺 SAN 时浏览器报 NET::ERR_CERT_COMMON_NAME_INVALID。最后备份旧配置和证书,便于回滚。
Nginx 443 配置完整示例:TLS 1.2/1.3、HSTS、OCSP Stapling
推荐配置如下(Nginx 1.25.1+ 使用 http2 on; 新语法):
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_trusted_certificate /etc/nginx/ssl/example.com.chain.pem;
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;
ssl_stapling on;
ssl_stapling_verify on;
resolver 1.1.1.1 8.8.8.8 valid=300s;
resolver_timeout 5s;
add_header Strict-Transport-Security 'max-age=31536000; includeSubDomains' always;
add_header X-Content-Type-Options 'nosniff' always;
add_header X-Frame-Options 'SAMEORIGIN' always;
location / {
root /var/www/example.com;
index index.html;
}
}
说明:ssl_certificate 必须 fullchain;ssl_trusted_certificate 用中间证书链,供 OCSP 验证。TLS 1.3 套件由 OpenSSL 自动协商,不需要写进 ssl_ciphers。HSTS 先短时间测试,确认全站 HTTPS 后再加 includeSubDomains,不要贸然 preload。若 Nginx 低于 1.25.1,把 http2 on; 改为 listen 443 ssl http2;,否则报 unknown directive "http2"。OCSP 需要能访问 CA 的 OCSP 地址;内网无外网可关闭 stapling,避免超时。
HTTP 301 跳转与 IPv6 监听:避免跳转循环
80 端口配置:
server {
listen 80;
listen [::]:80;
server_name example.com www.example.com;
return 301 https://$host$request_uri;
}
要点:$request_uri 保留原始路径和查询串;$host 取请求 Host 头,若担心 Host 头攻击,可写死域名:return 301 https://example.com$request_uri;。如果 CDN 或负载均衡在 Nginx 前面且已做 HTTPS,源站不能再 301,否则循环;此时用 X-Forwarded-Proto 判断:if ($http_x_forwarded_proto = 'http') { return 301 https://$host$request_uri; }。避免 return 301 https://$host:443$request_uri 造成 :443 重复。检查跳转:curl -I http://example.com/path?x=1 应返回 301 且 Location: https://example.com/path?x=1。若跳到 https://example.com:80,说明端口变量写错。IPv6 要加 listen [::]:80 和 [::]:443,否则 AAAA 记录解析到 IPv6 时连接失败。若使用 default_server,确保未知 Host 不会跳到错误站点。配置后 nginx -t 会检查重复 listen。
协议与套件对比表格:旧配置 vs 推荐配置
| 项目 | 旧写法/常见错误 | 推荐写法 | 说明 |
|---|---|---|---|
| HTTP/2 | listen 443 ssl http2; | listen 443 ssl; http2 on; | Nginx 1.25.1+ 新语法,旧写法 warning |
| 协议 | ssl_protocols TLSv1 TLSv1.1 TLSv1.2; | ssl_protocols TLSv1.2 TLSv1.3; | TLS 1.0/1.1 已淘汰,PCI DSS 不允许 |
| 套件 | ssl_ciphers HIGH:!aNULL:!MD5; | 明确 ECDHE-AESGCM/CHACHA20 列表 | 避免 CBC/3DES,TLS 1.3 自动协商 |
| 证书文件 | 只配站点证书 | fullchain + chain | 缺中间证书导致链不完整 |
| 会话票据 | 默认开启 | ssl_session_tickets off; | 降低前向保密风险 |
| HSTS | 不配置或 max-age=60 | max-age=31536000; includeSubDomains | 先测试,确认全站 HTTPS |
| OCSP | 不配置 | ssl_stapling on; verify on; | 需 resolver 和 chain 文件 |
旧配置不一定立刻报错,但会在 SSL Labs 评分、浏览器兼容和安全审计中暴露。HIGH:!aNULL:!MD5 仍可能包含 CBC 套件;推荐明确 GCM/CHACHA20。证书有效期规则也影响运维:398 天上限、Let’s Encrypt 90 天,续期后必须 reload。对比测试可用 openssl ciphers -v 'ECDHE+AESGCM:ECDHE+CHACHA20' 查看套件。表格中 http2 on 需 Nginx 1.25.1+;若用旧版,保留旧语法但接受 warning。不要同时写 http2 on; 和 listen ... http2,会重复。
生效与验证:nginx -t、openssl s_client、curl 与 SSL Labs
执行:sudo nginx -t、sudo systemctl reload nginx、curl -I http://example.com、curl -I https://example.com、curl -vI https://example.com 2>&1 | grep -E 'SSL|TLS|HTTP/2'、openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null、echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -noout -subject -issuer -dates。期望:nginx -t 输出 syntax is ok 和 test is successful;HTTP 返回 301,HTTPS 返回 200;openssl s_client 中 Verify return code: 0 (ok);证书链至少 2 张。检查 TLS 版本:openssl s_client -connect example.com:443 -tls1_2 应成功,-tls1_1 应失败。检查 HSTS:curl -sI https://example.com | grep -i strict-transport-security。检查 HTTP/2:curl -I --http2 https://example.com 返回 HTTP/2 200。SSL Labs 访问 https://www.ssllabs.com/ssltest/analyze.html?d=example.com,目标 A/A+;若显示 Chain issues: Incomplete,回到 fullchain。OCSP:openssl s_client -connect example.com:443 -status </dev/null | grep -A2 'OCSP Response'。最后设置监控:openssl x509 -checkend 2592000 -noout -in /etc/nginx/ssl/example.com.fullchain.pem 返回 0 表示 30 天内不过期。
常见错误排查:真实报错与修复命令
1. nginx: [emerg] PEM_read_bio_X509_AUX(...) failed (SSL: error:... no start line):证书不是 PEM 或路径错。用 file /etc/nginx/ssl/example.com.fullchain.pem 和 openssl x509 -in ... -noout -subject 验证,重新导出 PEM,别用 DER。
2. nginx: [emerg] no "ssl_certificate" is defined for the "listen ... ssl" directive:443 块缺证书或配置未 include。用 nginx -T | grep -n 'ssl_certificate' 查实际加载,在对应 server 加证书或删掉多余 ssl。
3. curl: (60) SSL certificate problem: unable to get local issuer certificate:链不完整。用 openssl s_client -showcerts 若只看到 1 张,执行 cat site.crt intermediate.crt > fullchain.pem 后 reload,顺序不能反。
4. nginx: [emerg] SSL_CTX_use_PrivateKey(...) failed (SSL: error:... key values mismatch):证书与私钥不匹配。比较 modulus md5,换回匹配 key 或重新签发。
5. nginx: [warn] the "listen ... http2" directive is deprecated, use the "http2" directive instead:Nginx 1.25.1+ 改为 listen 443 ssl; http2 on;。
6. certificate has expired 或 SSL_ERROR_RX_RECORD_TOO_LONG:过期或 HTTP 打 HTTPS 端口。用 openssl x509 -enddate 检查并续期 reload;检查是否误用 curl -I http://example.com:443。另有 bad password read 表示私钥有密码,需去密码。
常见问题
是。只配站点证书时,部分客户端缺中间证书会报 unable to get local issuer certificate。fullchain 顺序为站点证书在前、中间证书在后,可用 grep -c ‘BEGIN CERTIFICATE’ 检查至少 2 张。ssl_trusted_certificate 另指向 chain 文件。
公开信任 CA 签发的 TLS 证书最长 398 天;Let’s Encrypt 为 90 天。应使用 certbot 或 acme.sh 自动续期,并在续期后 reload Nginx。可用 openssl x509 -enddate -noout 检查到期时间。
listen 443 ssl 的 server 块必须直接或继承 ssl_certificate 与 ssl_certificate_key;若配置未 include、server_name 不匹配或证书路径写错都会报。用 nginx -T | grep ssl_certificate 查实际加载。
常见于 CDN 或负载均衡已终止 HTTPS,源站又 301。检查 X-Forwarded-Proto,仅在 http 时跳转;或让源站只监听 80 给代理。用 curl -I 查看 Location 是否指向 https 且无重复 :443。
改为 listen 443 ssl; 加 http2 on;。旧写法 listen 443 ssl http2; 会提示 deprecated warning。若版本低于 1.25.1,继续用旧写法,否则 unknown directive http2。
运行 openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null,看 Verify return code 是否为 0,并统计 BEGIN CERTIFICATE 数量。也可用 SSL Labs 看 Chain issues。若报 unable to get local issuer certificate,补中间证书。