跳到主要内容
Nginx

JoySSL 证书 Nginx 部署实战:从证书链到 TLS 1.3 的完整配置与排错指南

一、问题背景与根因:证书装上了,为什么客户端仍报错

Nginx 部署 SSL 证书不是把文件放进目录就结束。最常见根因有四类:第一,只部署了站点叶子证书,没有把中间证书合并为 fullchain.pem,浏览器可能靠 AIA 补链正常,但 curl、Java、微信小程序、部分 Android 客户端会直接报 unable to get local issuer certificate。第二,证书与私钥不匹配,Nginx 启动时报 key values mismatch。第三,证书有效期规则变化:公开信任 TLS 证书单张有效期上限为 398 天,Let’s Encrypt 为 90 天,JoySSL 免费 DV 通常 90 天,付费产品也不会超过 398 天上限,续期后忘记 reload 就会继续使用旧证书。第四,TLS 协议与套件过时,例如仍只开 TLSv1.0/1.1,或 cipher 只配 RSA 套件而证书是 ECC。

排查先从证书本身开始。把 CA 控制台下载的 Nginx/PEM 包解压,确认 fullchain.pem 内包含站点证书和中间证书,顺序是叶子在前、中间在后,不要放根证书。可用下面命令查看链:

openssl crl2pkcs7 -nocrl -certfile example.com_fullchain.pem | openssl pkcs7 -print_certs -noout
openssl x509 -in example.com_fullchain.pem -noout -subject -issuer -dates -ext subjectAltName

如果 issuer 显示的是中间 CA 而不是根 CA,说明链文件正常。再用 openssl s_client 模拟客户端验证:

openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | grep 'Verify return code'

返回 0 (ok) 才说明服务端链完整。若返回 20 (unable to get local issuer certificate),优先检查 ssl_certificate 是否误指向叶子证书。SNI 多站点场景还要确认每个 server 块都配置了对应证书,否则默认虚拟主机证书会串站。另一个容易忽略的点是系统时间,date -u 偏差超过证书有效期会直接导致 certificate has expired。把根因定位清楚,再进入文件准备和配置,能少走很多弯路。

二、准备证书文件:PEM、私钥与权限

JoySSL 控制台下载的 Nginx 格式包通常包含 fullchain.pem 和私钥文件。生产目录建议统一放在 /etc/nginx/ssl,不要放在网站根目录。操作如下:

sudo mkdir -p /etc/nginx/ssl
sudo install -m 600 /path/to/example.com_fullchain.pem /etc/nginx/ssl/example.com_fullchain.pem
sudo install -m 600 /path/to/example.com.key /etc/nginx/ssl/example.com.key
sudo chown root:root /etc/nginx/ssl/example.com_fullchain.pem /etc/nginx/ssl/example.com.key
sudo chmod 700 /etc/nginx/ssl

权限原则:私钥 600,属主 root;Nginx master 以 root 启动后可读,worker 继承文件描述符。若用非 root 容器运行 Nginx,需要把属主改为容器内用户,或挂载时保留可读权限。接着验证证书与私钥是否匹配。RSA 证书可用模数比对:

openssl x509 -in /etc/nginx/ssl/example.com_fullchain.pem -noout -modulus | openssl md5
openssl rsa -in /etc/nginx/ssl/example.com.key -noout -modulus | openssl md5

两条命令输出的 MD5 必须一致。ECC 证书不要用 rsa 子命令,改用公钥比对:

openssl x509 -in /etc/nginx/ssl/example.com_fullchain.pem -noout -pubkey | openssl md5
openssl pkey -in /etc/nginx/ssl/example.com.key -pubout | openssl md5

同时检查有效期和 SAN:openssl x509 -in … -noout -dates -ext subjectAltName。确认域名包含 example.com 和 www.example.com,避免证书名不匹配。若证书链文件里混入根证书,通常不影响 Nginx,但会增加握手包体积,建议只保留叶子+中间。续期时不要覆盖错文件:先备份旧文件,再 install 新 fullchain 和 key,最后 nginx -t 并 reload。公开信任证书有效期上限 398 天,Let’s Encrypt 90 天,JoySSL 免费 DV 通常 90 天,建议在到期前 30 天完成续期。

三、Nginx 完整配置示例:443、跳转与 TLS 参数

以下配置兼容 Nginx 1.25.1 及以上版本的 http2 on 写法;旧版本把 listen 443 ssl; 改为 listen 443 ssl http2; 并删除 http2 on;。不要同时保留旧版 ssl on;,该指令已废弃。

server {
    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;

    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_trusted_certificate /etc/nginx/ssl/example.com_fullchain.pem;

    add_header Strict-Transport-Security 'max-age=31536000; includeSubDomains' always;

    location / {
        root /var/www/example.com;
        index index.html;
    }
}

server {
    listen 80;
    server_name example.com www.example.com;
    return 301 https://$host$request_uri;
}

关键参数说明:ssl_ciphers 只对 TLSv1.2 生效,TLSv1.3 套件由 OpenSSL 默认策略管理;如果证书是 ECC,套件中必须包含 ECDSA 项,否则可能出现 no shared cipher。ssl_prefer_server_ciphers off 让客户端优先选择更现代的套件。ssl_session_tickets off 降低会话票据密钥管理风险,配合 shared:SSL:10m 可缓存约 4 万个会话。OCSP stapling 需要 Nginx 能解析 ocsp 域名并出站访问 80/443,ssl_trusted_certificate 指向完整链文件即可。HSTS 头不要在调试阶段直接加 includeSubDomains,确认所有子域都支持 HTTPS 后再开,否则回退困难。

如果站点是反向代理,把 location 改为 proxy_pass http://127.0.0.1:8080; 并补充 proxy_set_header Host $host; 等头。配置写完后不要急着重启,先执行 nginx -t 校验语法,再用 nginx -T | grep -A5 ssl_certificate 确认加载的是新文件路径。只有修改监听端口、加载新模块等场景才需要 restart,普通证书替换 reload 即可。

四、校验、平滑重载与回滚

配置修改后按固定流程操作:备份、校验、重载、观察日志。先备份当前配置和证书:

sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak.$(date +%F)
sudo cp /etc/nginx/conf.d/example.com.conf /etc/nginx/conf.d/example.com.conf.bak.$(date +%F)
sudo nginx -t

nginx -t 返回 syntax is ok 和 test is successful 才继续。若报 nginx: [emerg] cannot load certificate … Permission denied,用 namei -l 检查路径每一级权限:

namei -l /etc/nginx/ssl/example.com.key
sudo -u nginx test -r /etc/nginx/ssl/example.com.key && echo readable

在 CentOS/RHEL 上还要检查 SELinux 上下文,正确命令是:

sudo chcon -t httpd_sys_content_t /etc/nginx/ssl/example.com_fullchain.pem /etc/nginx/ssl/example.com.key
sudo restorecon -Rv /etc/nginx/ssl

然后平滑重载:sudo systemctl reload nginx,或 sudo nginx -s reload。reload 会启动新 worker 并优雅关闭旧 worker,不会断开现有连接;restart 才会短暂中断。重载后检查监听和日志:

ss -lntp | grep ':443'
sudo tail -n 50 /var/log/nginx/error.log
sudo journalctl -u nginx --since '5 min ago' --no-pager

如果重载失败,Nginx 会保留旧配置继续服务,此时不要反复 reload。按报错修复后再次 nginx -t。需要回滚时把备份文件覆盖回来,再 reload。验证新证书是否真正生效,不能只看浏览器,使用:

openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null | openssl x509 -noout -dates -subject -issuer

输出中的 notAfter 应是新证书日期。若日期没变,说明配置路径指向旧文件、reload 未成功,或前面还有 CDN/负载均衡层缓存了旧证书。多层架构要逐层检查,先源站再边缘节点。

五、证书类型、链文件与有效期对比表

部署前先分清文件角色。Nginx 的 ssl_certificate 应指向 fullchain.pem,即站点证书+中间证书;ssl_certificate_key 指向私钥。根证书不应放进服务端链文件,它只应存在于客户端信任库。对比如下:

对比项 仅叶子证书 fullchain.pem 根证书
文件内容 站点证书 站点证书+中间证书 根 CA 证书
浏览器表现 可能靠 AIA 补链正常 推荐,链完整 不应放入服务端
curl/Java/小程序 常报 unable to get local issuer certificate 正常 增加包体积,无必要
Nginx 用法 错误做法 ssl_certificate 客户端信任库

证书类型和有效期也要心里有数。DV 只验证域名控制权,签发快,适合个人站和 API;OV 额外验证组织信息,适合企业门户;EV 在浏览器地址栏的视觉优势已弱化,按合规需求选择。算法上 RSA 2048 兼容性最好,ECC P-256 握手更快、包更小,但极老客户端可能不支持。公开信任 TLS 证书单张有效期上限为 398 天,这是 CA/B Forum 规则,不是某家 CA 的营销策略;Let’s Encrypt 为 90 天,JoySSL 免费 DV 通常 90 天,付费证书按产品签发但同样不得超过 398 天。

项目 建议值 说明
TLS 协议 TLSv1.2 TLSv1.3 禁用 TLSv1.0/1.1
RSA 密钥 2048 位以上 兼容性优先
ECC 密钥 P-256 现代客户端优先
证书有效期 ≤398 天 Let’s Encrypt 90 天
续期提前量 30 天 免费 DV 建议 15 天

如果使用 CDN,源站和 CDN 边缘证书是两套证书,续期要分别处理。JoySSL 控制台下载时选择 Nginx/PEM 格式,不要拿 IIS 的 .pfx 直接改后缀。多域名站点优先用 SAN 证书,避免为每个域名单独维护 server 块和续期任务。

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

下面这些报错在 Nginx 部署 SSL 时出现频率最高,按报错关键词定位即可。

1. nginx: [emerg] SSL_CTX_use_PrivateKey(…) failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch) 表示证书与私钥不匹配。用第二节的 modulus 或 pubkey MD5 比对,不一致就重新从 CA 下载匹配的私钥,不要手工拼接。

2. curl: (60) SSL certificate problem: unable to get local issuer certificate 表示服务端链不完整。检查 ssl_certificate 是否指向 fullchain.pem;用 openssl s_client -showcerts 看返回了几张证书,正常至少两张。修复后 reload,再用 curl -I https://example.com 验证。

3. nginx: [emerg] cannot load certificate … No such file or directory 路径拼写错误或文件未同步。用 nginx -T | grep ssl_certificate 看实际加载路径,用 ls -l 逐级确认。容器部署常见于挂载路径与配置路径不一致。

4. SSL: error:0A00018A:SSL routines::dh key too small 或 no shared cipher 说明协议/套件与证书算法不匹配。ECC 证书要包含 ECDSA 套件;不要只配 ECDHE-RSA。用 openssl s_client -tls1_2 和 -tls1_3 分别测试,确认不是客户端只支持旧协议。

5. certificate has expired 续期后未 reload、配置仍指向旧文件,或系统时间错误。执行 date -u 和 openssl x509 -noout -dates 对比;确认 notAfter 后 reload。若使用容器,注意镜像内旧证书被覆盖。

6. nginx: [warn] the ‘ssl’ directive is deprecated 删除 ssl on;,改用 listen 443 ssl;。这个警告不影响启动,但会在升级后变成错误。

排查顺序建议:先 nginx -t 看语法,再 openssl s_client 看链,再 curl 看应用层,最后看 error.log。不要一上来就改 cipher,多数问题出在链文件和路径。

七、效果验证与到期监控

部署完成后做三层验证:证书链、协议版本、应用访问。证书链验证:

echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | grep 'Verify return code'
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates

返回 Verify return code: 0 (ok) 表示链验证通过。协议验证分别强制 TLSv1.2 和 TLSv1.3:

curl -I --tlsv1.2 --tls-max 1.2 https://example.com
curl -I --tlsv1.3 https://example.com
openssl s_client -connect example.com:443 -servername example.com -tls1_2 </dev/null 2>/dev/null | grep 'Protocol'

应用层验证用 curl -I https://example.com,检查 HTTP/2 是否生效可加 –http2。浏览器开发者工具的 Security 面板能看到协议、密钥交换和证书链。外部评级可用 SSL Labs,但不要频繁扫描生产站点。多域名站点逐个执行 openssl s_client -servername,避免 SNI 串证。

到期监控不要依赖人工记忆。用 openssl 的 checkend 做定时任务,返回 0 表示在指定秒数内仍有效:

if openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null | openssl x509 -noout -checkend 1209600; then
  echo '证书 14 天内不会过期'
else
  echo '证书即将过期,请续期并 reload nginx'
fi

把这段放进 cron 每天执行,或接入 Zabbix/Prometheus blackbox_exporter 的 probe_ssl_earliest_cert_expiry 指标。续期后按“备份→install 新文件→nginx -t→reload→openssl 验证”的顺序操作。公开信任证书有效期上限 398 天,Let’s Encrypt 90 天,JoySSL 免费 DV 通常 90 天,建议提前 30 天续期;免费证书可提前 15 天。最后检查 HSTS 头是否只在你确认全站 HTTPS 后启用:curl -sI https://example.com | grep -i strict-transport-security。

常见问题

配置 fullchain.pem 和私钥文件:ssl_certificate 指向包含站点证书与中间证书的 fullchain.pem,ssl_certificate_key 指向 .key。不要只配叶子证书,否则 curl、Java、小程序可能报 unable to get local issuer certificate。根证书不要放进服务端链文件。


多数是证书链不完整。浏览器可借助 AIA 自动补链,Java 和小程序通常严格校验服务端返回的链。把 ssl_certificate 改为 fullchain.pem,确保包含中间证书,再 reload。可用 openssl s_client -showcerts 检查返回证书数量,正常至少两张。


公开信任 TLS 证书单张有效期上限为 398 天;Let’s Encrypt 为 90 天;JoySSL 免费 DV 通常 90 天,付费证书按产品签发但不得超过 398 天。到期前 30 天续期,续期后必须 nginx -t 并 reload,否则可能继续使用旧证书。


不需要。先执行 nginx -t 校验语法,再 systemctl reload nginx 或 nginx -s reload 平滑重载,现有连接不会中断。只有修改监听端口、加载新模块或更换二进制等场景才需要 restart。重载后务必用 openssl s_client 确认新证书日期已生效。


RSA 证书分别对证书和私钥执行 modulus 后取 MD5,两条结果一致即匹配;ECC 证书用 openssl x509 -pubkey 与 openssl pkey -pubout 分别取 MD5 比对。若不匹配,Nginx 会报 key values mismatch,需重新下载匹配的私钥,不要手工拼接。


先确认 ssl_stapling on、ssl_stapling_verify on 和 ssl_trusted_certificate 指向完整链文件;再检查 Nginx 能否解析 OCSP 域名并出站访问 80/443。用 openssl s_client -connect example.com:443 -servername example.com -status 查看是否返回 OCSP response。若网络受限,可关闭 stapling,不影响证书基本信任。

内容审核

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