Nginx 配置 SSL 证书完整教程:fullchain 部署、TLS 1.3 与 HTTPS 排错实战
一、问题背景与根因:为什么配了证书浏览器仍提示不安全
把证书路径填进 Nginx 并不等于 HTTPS 可用。线上最常见的四类现象是:浏览器显示「您的连接不是私密连接」,错误码 NET::ERR_CERT_AUTHORITY_INVALID;命令行 curl 报 curl: (60) SSL certificate problem: unable to get local issuer certificate;Android 7 以下或 Java 客户端握手直接失败,而 Chrome 访问同一站点却正常;SSL Labs 评级只有 B。它们分别对应证书链缺失、私钥不匹配、协议过旧和配置未生效。
根因集中在以下几点:
- 证书链不完整:只部署了站点证书,没带中间证书。桌面浏览器会通过证书里的 AIA 地址自动补链,所以「本机能开」,但移动端、Java、Python requests、部分 IoT 设备没有补链能力,直接握手失败。
- 私钥与证书不配对:续期时只换了证书没换私钥,或从两台机器各拷了一份。
- 证书过期:目前公共 CA 签发的 TLS 证书最长有效期被限制为 398 天(自 2020-09-01 起由 Apple/Chrome 强制),Let’s Encrypt 免费证书有效期为 90 天,必须做自动续期,靠人工续期几乎必然漏掉。
- 协议与套件过旧:TLS 1.0/1.1 已被 Chrome 98+、Safari 15.4+、Firefox 等移除,配置里保留
ssl_protocols TLSv1 TLSv1.1既拿不到评级加分,还可能因套件协商失败导致握手报错。 - SNI 与端口:一个 IP 承载多站点时,不支持 SNI 的老客户端会拿到默认站点证书;安全组或防火墙未放行 443,或 SELinux 禁止 nginx 读取证书文件。
- 未真正 reload:
nginx -t校验失败时nginx -s reload不会生效,master 进程继续用旧配置跑,看起来「改了没用」。
动手前先用一条命令确认现状:
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null
| openssl x509 -noout -subject -issuer -dates
输出中的 issuer 若显示的是中间 CA 名称而非根 CA,且有效期已过,基本可以确定问题方向。下面按「准备文件 → 写配置 → 校验 → 排错 → 验证」的顺序完整走一遍。
二、证书文件准备:fullchain、私钥与校验命令
CA 签发后通常给出三个文件:example.com.crt(站点证书)、example.com.key(私钥)、intermediate.crt 或 ca_bundle.crt(中间证书)。Nginx 的 ssl_certificate 需要的是站点证书在前、中间证书在后的 fullchain 文件;根证书不要放进去,放了会让握手包变大,个别客户端还会报链过长。
拼接与检查:
cat example.com.crt intermediate.crt > example.com.fullchain.pem
# 查看链里到底有几张证书,正常应为 2 张
openssl crl2pkcs7 -nocrl -certfile example.com.fullchain.pem
| openssl pkcs7 -print_certs -noout
# 校验证书链(root.crt 为对应根证书)
openssl verify -CAfile root.crt -untrusted intermediate.crt example.com.crt
# 查看有效期与 SAN 域名
openssl x509 -noout -dates -subject -ext subjectAltName -in example.com.fullchain.pem
证书与私钥是否匹配,用 modulus 指纹比对,两行输出的 MD5 必须完全一致:
openssl x509 -noout -modulus -in example.com.fullchain.pem | openssl md5
openssl rsa -noout -modulus -in example.com.key | openssl md5
# ECDSA 私钥改用:
openssl ec -noout -text -in example.com.key | head -n 3
文件落盘后收紧权限,私钥泄露等于证书作废:
mkdir -p /etc/nginx/ssl && chmod 700 /etc/nginx/ssl
cp example.com.fullchain.pem example.com.key /etc/nginx/ssl/
chown root:root /etc/nginx/ssl/*
chmod 600 /etc/nginx/ssl/example.com.key
chmod 644 /etc/nginx/ssl/example.com.fullchain.pem
如果拿到的不是 PEM 格式(如 .pfx、.der、二进制 .cer),先转换再部署:
openssl pkcs12 -in cert.pfx -nodes -out all.pem # pfx 拆包
openssl x509 -inform DER -in cert.cer -out cert.pem # DER 转 PEM
CentOS/RHEL 还需确认 SELinux 上下文,否则 nginx 读不到文件:restorecon -Rv /etc/nginx/ssl。证书文件命名建议固定为 example.com.fullchain.pem,续期脚本只需覆盖同名文件,配置无需改动。
三、完整实操步骤:从上传到平滑生效
下面按顺序执行,每步都可直接复制。假设站点为 example.com,证书已按上一节整理为 fullchain 与 key。
步骤 1:备份现有配置,出问题可 30 秒回滚:
cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak.$(date +%F)
nginx -v # 记录版本,决定 http2 写法
步骤 2:上传证书(在本地机器执行):
scp example.com.fullchain.pem example.com.key root@SERVER_IP:/etc/nginx/ssl/
步骤 3:写入站点配置 /etc/nginx/conf.d/example.com.conf,内容见下一节配置示例。注意 nginx.conf 的 http{} 块里要有 include /etc/nginx/conf.d/*.conf;,否则文件不生效。
步骤 4:先校验再 reload,顺序不能反:
nginx -t
# 输出 syntax is ok / test is successful 才继续
systemctl reload nginx # 或 nginx -s reload
步骤 5:放行端口并确认监听:
ss -lntp | grep ':443'
firewall-cmd --add-service=https --permanent && firewall-cmd --reload # CentOS
ufw allow 443/tcp # Ubuntu
步骤 6:配置自动续期。Let’s Encrypt 只有 90 天有效期,用 systemd timer 比 cron 更可靠:
certbot renew --dry-run
systemctl list-timers | grep certbot
printf '#!/bin/shnsystemctl reload nginxn' > /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh
chmod +x /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh
步骤 7:确认新配置真的生效,别被浏览器缓存骗了,看进程启动时间最直接:
systemctl status nginx | grep Active
ps -o lstart= -p $(cat /run/nginx.pid)
curl -sI https://example.com | head -n 1
若 nginx -t 报错,不要 reload,也不要重启,直接按报错关键字查第六节,或先用备份覆盖回去。生产环境更稳妥的做法是先在 8443 端口挂新证书验证可用,再切正式配置。
四、配置示例:生产可用的 443 站点块
完整片段如下,包含 HTTP 301 跳转、TLS 1.2/1.3、OCSP Stapling、HSTS 与会话复用:
server {
listen 80;
listen [::]:80;
server_name example.com www.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
listen [::]:443 ssl;
http2 on; # nginx ≥ 1.25.1;旧版本见下表
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;
ssl_stapling on;
ssl_stapling_verify on;
ssl_trusted_certificate /etc/nginx/ssl/example.com.fullchain.pem;
resolver 223.5.5.5 1.1.1.1 valid=300s;
resolver_timeout 5s;
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
root /var/www/example.com;
index index.html;
}
几个容易踩坑的参数:
ssl_ciphers只对 TLS 1.2 及以下生效;TLS 1.3 套件由 OpenSSL 控制,需要时用ssl_conf_command Ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256;(要求 nginx ≥ 1.19.4 且 OpenSSL ≥ 1.1.1)。ssl_prefer_server_ciphers off是当前推荐值,把套件选择权交给客户端,移动端兼容性更好。ssl_stapling依赖ssl_trusted_certificate与可用resolver,缺一不可,否则日志出现"ssl_stapling" ignored警告。- HSTS 首次上线建议先把
max-age设为 300 秒验证,确认全站与子域都能走 HTTPS 后再调成 31536000;一旦下发includeSubDomains,任何子域走 HTTP 都会被浏览器直接拒绝。 - ECC 证书把
ssl_certificate指向 ECDSA 证书即可;RSA+ECC 双证书需在同一个 server 块写两对ssl_certificate/ssl_certificate_key,nginx ≥ 1.11.0 支持。
五、对比表格:部署组合与版本语法
表 1:同一张 DV 证书,仅改变部署内容后的实际表现:
| 部署内容 | 中间证书 | 桌面浏览器 | Android/Java 客户端 | SSL Labs |
|---|---|---|---|---|
| 仅 example.com.crt | 缺失 | 多数正常(AIA 自动补链) | 握手失败,报 unable to get local issuer certificate | 链不完整,通常 B |
| fullchain.pem(站点+中间) | 完整 | 正常 | 正常 | A / A+ |
| fullchain + key 权限 644 | 完整 | 正常 | 正常 | 可握手,但私钥任意用户可读 |
| fullchain + 根证书 | 多余 | 一般正常 | 个别客户端报链过长 | 握手包增大,无收益 |
| 自签证书 | — | 红色警告 | 直接失败 | 无法评级 |
表 2:nginx 版本与 HTTP/2 写法(写错会直接启动失败):
| nginx 版本 | 正确写法 | 错误写法及后果 |
|---|---|---|
| < 1.9.5 | 不支持 HTTP/2 | 写 http2 报 unknown directive |
| 1.9.5 – 1.25.0 | listen 443 ssl http2; |
写 http2 on; 报 unknown directive "http2" |
| ≥ 1.25.1 | listen 443 ssl; + http2 on; |
listen ... http2 触发 deprecated 警告 |
表 3 用一句话概括有效期规则:公共 CA 签发的证书最长 398 天,Let’s Encrypt 为 90 天(剩余 30 天自动续期),自签或内部 CA 可自定义但需随内网 PKI 统一轮换。凡是宣称「十年有效期」的证书,基本都是自签,浏览器不会信任。
六、常见错误排查:真实报错与处理
按 nginx -t 的报错关键字对号入座,再结合 tail -50 /var/log/nginx/error.log。
1. 权限或 SELinux 导致读不到证书
nginx: [emerg] cannot load certificate "/etc/nginx/ssl/example.com.fullchain.pem":
BIO_new_file() failed (SSL: error:0200100D:system library:fopen:Permission denied)
处理:确认私钥 chmod 600 且属主正确;ps aux | grep nginx 看 worker 运行用户;CentOS 上执行 restorecon -Rv /etc/nginx/ssl 或 chcon -t httpd_config_t /etc/nginx/ssl/* 后重新 nginx -t。
2. 证书与私钥不匹配
nginx: [emerg] SSL_CTX_use_PrivateKey("/etc/nginx/ssl/example.com.key") failed
(SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch)
处理:用第二节的 modulus MD5 比对;Let’s Encrypt 的 live/ 目录是软链,拷贝时必须 cp -L 跟随真实文件,否则拿到的可能是上一代证书。
3. 文件不是 PEM 格式
nginx: [emerg] PEM_read_bio_X509_AUX() failed
(SSL: error:0909006C:PEM routines:get_name:no start line)
处理:file example.com.pem 若显示 DER/Binary,用 openssl x509 -inform DER -in a.cer -out a.pem 转换;也可能是上传时被网关改写成了 HTML 错误页,head -n 1 看首行是否为 -----BEGIN CERTIFICATE-----。
4. 客户端报证书链不完整
curl: (60) SSL certificate problem: unable to get local issuer certificate
处理:确认 ssl_certificate 指向 fullchain 而非单证书,用 openssl s_client -showcerts 数返回的证书数量,应为 2 张。
5. OCSP Stapling 警告
nginx: [warn] "ssl_stapling" ignored, issuer certificate not found for certificate
处理:补齐 ssl_trusted_certificate,确保 resolver 能解析 OCSP 地址;纯内网无外网 DNS 时直接关闭 stapling。
6. 重复的 listen 参数
nginx: [emerg] duplicate listen options for 0.0.0.0:443 in /etc/nginx/conf.d/a.conf:12
处理:同一端口只能声明一次 ssl/http2 选项,检查是否两个 server 块都写了 listen 443 ssl http2;,保留一个。
7. 域名不匹配:浏览器报 NET::ERR_CERT_COMMON_NAME_INVALID,说明 SAN 里没有当前域名。通配符 *.example.com 不覆盖 example.com 本身,也不覆盖 a.b.example.com,需重新签发或补 SAN。
七、效果验证:五步确认 HTTPS 真正可用
配置生效后按下面顺序验证,全部通过再删回滚备份。
1. 端口与跳转:
ss -lntp | grep ':443'
curl -sI http://example.com | head -n 3
# 期望:HTTP/1.1 301 Moved Permanently 与 Location: https://example.com/
2. 证书链与有效期,Verify return code 必须为 0:
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null
| openssl x509 -noout -subject -issuer -dates
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null
| grep -E "Verify return code|Protocol|Cipher"
3. 协议降级测试,TLS 1.1 必须握手失败,证明旧协议确实被禁用:
openssl s_client -connect example.com:443 -servername example.com -tls1_1 </dev/null
# 期望:alert protocol version / handshake failure
4. 安全响应头:
curl -sI https://example.com | grep -i -E "strict-transport|server"
# 期望:strict-transport-security: max-age=31536000; includeSubDomains
5. 第三方扫描:本地跑 testssl.sh --fast example.com,或提交 SSL Labs,目标 A 及以上且 Certificate Paths 显示 Chain issues: None。再用手机 4G 网络访问一次,排除内网 DNS 与防火墙差异。
最后盯日志确认没有握手错误堆积:tail -f /var/log/nginx/error.log | grep -i ssl。正常业务下不应持续出现 SSL_do_handshake() failed;若大量出现并伴随 unsupported protocol,说明仍有老客户端在用 TLS 1.0,需要评估兼容策略或推动客户端升级。
常见问题
不建议。桌面浏览器会通过 AIA 自动补链,看起来正常;但 Android、Java、Python requests 等客户端没有补链能力,会直接握手失败。请始终把站点证书与中间证书拼成 fullchain 部署,根证书不要放进去。
公共 CA 签发的 TLS 证书最长 398 天,2020 年 9 月起由主流浏览器强制;Let’s Encrypt 免费证书为 90 天,建议剩余 30 天时自动续期。宣称十年有效的多为自签证书,浏览器不会信任。
先跑 nginx -t,校验失败时 reload 会被拒绝,master 继续使用旧配置。根据报错修正后再次 reload,并用 ps -o lstart= -p $(cat /run/nginx.pid) 确认进程启动时间已更新。
分别计算 modulus 的 MD5:openssl x509 -noout -modulus -in cert.pem | openssl md5 与 openssl rsa -noout -modulus -in key.pem | openssl md5,两者一致才匹配。ECDSA 证书改用 openssl ec -noout -text 对比公钥。
该写法要求 nginx 1.25.1 及以上;1.9.5 到 1.25.0 应写成 listen 443 ssl http2;,更低版本不支持 HTTP/2。用 nginx -v 确认版本后按文中表格选择对应写法。
是。Chrome 98+、Safari 15.4+、Firefox 等已移除对 TLS 1.0/1.1 的支持,保留它们只会增加降级风险,也拿不到 SSL Labs 高分。仅在有明确老旧设备需求时临时例外,并记录原因。