nginx ssl 配置教程:从 CSR 到 reload 的 8 步实操与排错(nginx 1.26 + OpenSSL 3.0)
nginx ssl 配置的最小可用集只有 4 行:listen 443 ssl、ssl_certificate 指向 fullchain.pem、ssl_certificate_key 指向私钥、ssl_protocols TLSv1.2 TLSv1.3,改完执行 nginx -t 通过后再 systemctl reload nginx 生效。 证书链必须用 fullchain.pem(站点证书 + 中间证书,共 2 张),漏掉中间证书会让 Android 与 Java 客户端报 PKIX path building failed,而桌面 Chrome 因 AIA 补链看不出来。 nginx 1.23.4 起 ssl_protocols 默认值已改为 TLSv1.2 TLSv1.3,但 ssl_ciphers 只管 TLSv1.2 及以下,TLSv1.3 套件要用 ssl_conf_command Ciphersuites(nginx 1.19.4+ / OpenSSL 1.1.1+)单独设。 OCSP stapling 要生效必须同时写 ssl_stapling on、ssl_stapling_verify on、ssl_trusted_certificate 和 resolver 四个指令,少一个 nginx 只在 error.log 里留一条 warn。 验证命令一条够用:openssl s_client -connect example.com:443 -servername example.com -showcerts /dev/null | grep -c "BEGIN CERTIFICATE" 输出 2 才算链完整。
为什么照抄旧版 nginx ssl 配置教程,上线后还是会翻车?
问:为什么照抄旧版 nginx ssl 配置教程,上线后还是会翻车?
因为绝大多数中文 nginx ssl 配置教程写于 nginx 1.10/1.12 + OpenSSL 1.0.2 时代,而默认值和信任模型在过去五年里都变过。照抄不是”保守”,而是把已经被淘汰的默认值重新写死进配置文件。先用一条命令确认你的运行环境,再对照下表:
# 查看 nginx 版本与编译时链接的 OpenSSL 版本(决定可用指令与默认协议)
nginx -V 2>&1 | tr ' ' 'n' | grep -E 'nginx/|openssl'
# 示例输出:nginx/1.26.2 / built with OpenSSL 3.0.13 30 Jan 2024
| 配置项 | 旧教程常见写法(1.10/1.12 时代) | nginx 1.26 + OpenSSL 3.0 默认/推荐 | 照抄的后果 |
|---|---|---|---|
| ssl_protocols | TLSv1 TLSv1.1 TLSv1.2 | TLSv1.2 TLSv1.3(据 nginx 官方 changelog,1.23.4 起默认值变更) | 主动保留两个被 PCI DSS 4.0 禁止的协议 |
| ssl_ciphers | ECDHE-RSA-AES128-GCM-SHA256:… | 默认 HIGH:!aNULL:!MD5 | 只管 TLSv1.2 及以下,对 TLSv1.3 完全无效 |
| 证书文件 | domain.crt 单文件 | fullchain.pem(叶证书 + 中间证书) | Android 7 以下、Java 8 客户端握手失败 |
证书链不完整是 nginx ssl 配置里出现频率最高的故障。只部署 domain.crt 而不拼接中间证书时,桌面 Chrome 会通过 AIA 自动补链,看不出任何异常;但 Android 7 以下与 Java 8 客户端会直接抛 javax.net.ssl.SSLHandshakeException: PKIX path building failed,于是就有了”我这边正常、用户打不开”的扯皮。上线前用 OpenSSL 自检:
# 统计服务端实际下发的证书张数,期望为 2(叶证书 + 中间证书),输出 1 即链不完整
openssl s_client -connect example.com:443 -servername example.com -showcerts /dev/null
| grep -c "BEGIN CERTIFICATE"
# 反向验证:旧协议应当握手失败(-tls1_1 报错才是正确结果)
openssl s_client -connect example.com:443 -servername example.com -tls1_1 </dev/null
第二个高频坑在套件指令。把 TLS_AES_128_GCM_SHA256 写进 ssl_ciphers,nginx -t 会直接报 nginx: [emerg] SSL_CTX_set_cipher_list("…") failed (SSL: error:0A0000B9:SSL routines::no cipher match),因为 TLSv1.3 的三个套件由 OpenSSL 的 Ciphersuites 参数控制,必须借助 nginx 1.19.4+ 才提供的 ssl_conf_command 指令:
# TLSv1.2 及以下:走 ssl_ciphers(该指令对 TLSv1.3 无效)
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
ssl_prefer_server_ciphers on; # 默认 off,仅对 TLSv1.2 及以下有意义
# TLSv1.3:走 ssl_conf_command,需 nginx >= 1.19.4 且链接 OpenSSL 1.1.1+
ssl_conf_command Ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256;
信任链本身也在漂移。据 Let’s Encrypt 文档,自 2021-09-30 DST Root CA X3 到期后,默认签发链改走 ISRG Root X1,Android 7.1 以下设备不信任该根;用户群含老旧安卓时,签发阶段就要选备用链或改用商业 CA。同时有效期正在被压缩——据 CA/Browser Forum 通过的 SC-081 计划,2026-03-15 起单张证书上限 200 天、2027-03-15 起 100 天、2029-03-15 起 47 天。把续期交给日历提醒,等于给这套 nginx ssl 配置教程埋一个定时炸弹,第一步就应把 ACME 客户端与 nginx -t && nginx -s reload 串进定时任务,而不是留到最后一步再补。
nginx ssl 配置完整实操:8 个编号步骤从 CSR 一路走到 reload
很多人问:nginx ssl 配置教程里最容易被跳过的环节是什么?答案是”确认环境”和”灰度生效”这两头。中间填证书反而最简单。下面按 8 步走一遍,环境为 nginx 1.26.0 + OpenSSL 3.0.13(Debian 12 / Ubuntu 22.04)。
步骤 1–2:确认版本与模块,别急着写配置。先跑一条命令看清二进制里到底编进了什么:
# 列出 nginx 版本、链接的 OpenSSL 版本、是否含 ssl 与 http2 模块
nginx -V 2>&1 | tr ' ' 'n' | grep -E 'nginx/|OpenSSL|with-http_ssl_module|with-http_v2_module'
# 期望输出(片段):
# nginx/1.26.0
# built
# with
# OpenSSL
# 3.0.13
# --with-http_ssl_module
# --with-http_v2_module
注意一个真实坑:tr ' ' 'n' 会把 “built with OpenSSL 3.0.13” 拆成多行,所以用 grep 'built with OpenSSL' 反而匹配不到。想保留整行就用 nginx -V 2>&1 | grep -E 'built with OpenSSL|running with OpenSSL'。Debian 12 与 Ubuntu 22.04 的官方源包默认已内置 --with-http_ssl_module;源码编译时若漏写该参数,nginx -t 会直接报 nginx: [emerg] unknown directive "ssl_certificate",这也是新手最常见的”配置没错却起不来”。据 nginx 官方文档,1.25.1 起 listen 443 ssl http2 中的 http2 参数已弃用,改为独立的 http2 on;,1.26 上继续用旧写法会打印 warning。
步骤 3:生成私钥与 CSR。RSA 路线(兼容性最稳):
mkdir -p /etc/nginx/ssl && cd /etc/nginx/ssl
# -addext 需 OpenSSL 1.1.1+,3.0 完全支持;SAN 必须写,CN 已被现代浏览器忽略
openssl req -new -newkey rsa:2048 -sha256 -nodes
-keyout /etc/nginx/ssl/example.com.key
-out /etc/nginx/ssl/example.com.csr
-subj "/C=CN/O=Example/CN=example.com"
-addext "subjectAltName=DNS:example.com,DNS:www.example.com"
ECDSA 路线(握手更小、更快):
openssl ecparam -genkey -name prime256v1 -out /etc/nginx/ssl/example.com.key
openssl req -new -key /etc/nginx/ssl/example.com.key
-out /etc/nginx/ssl/example.com.csr
-subj "/C=CN/O=Example/CN=example.com"
-addext "subjectAltName=DNS:example.com,DNS:www.example.com"
| 对比项 | RSA 2048 | ECDSA P-256 |
|---|---|---|
| 私钥大小 | 约 1.7 KB | 约 0.2 KB |
| 等价安全强度 | ≈112 位 | ≈128 位 |
| 兼容性 | 全平台无死角 | 不支持 Windows XP / Android 4.3 以下 |
| 签发命令 | --key-type rsa |
--key-type ecdsa |
步骤 4:签发或申请证书。Let’s Encrypt 用 certbot 2.11:
# 2.x 默认 key-type 已是 ecdsa,显式写出便于审计
certbot certonly --webroot -w /var/www/html
-d example.com -d www.example.com --key-type ecdsa
# 产物:/etc/letsencrypt/live/example.com/fullchain.pem 与 privkey.pem
据 Let’s Encrypt 文档,live/ 下的文件是软链,真实文件在 /etc/letsencrypt/archive/。nginx master 进程以 root 启动、读取证书后才把 worker 降权,所以正常可读;若你把 nginx 整体改成非 root 运行,就必须给 archive 目录补读权限,否则 reload 会报 BIO_new_file() failed (SSL: error:8000000D:system library::Permission denied)。
步骤 5:商业证书必须自己拼 fullchain。顺序是站点证书在前、中间证书在后,根证书绝不能放(放了部分客户端会校验失败):
cd /etc/nginx/ssl
cat example.com.crt intermediate.crt > fullchain.pem
# 核对:应输出恰好 2 个 subject 行
openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout
步骤 6:收紧权限。私钥 644 会被等保测评与 PCI DSS 扫描器直接判高危:
install -d -m 700 /etc/nginx/ssl
chmod 600 /etc/nginx/ssl/example.com.key
chown root:root /etc/nginx/ssl/example.com.key
步骤 7:写 server 块。算法套件可参考 Mozilla SSL Configuration Generator 的 intermediate 档:
server {
listen 443 ssl;
http2 on; # nginx 1.25.1+ 新语法
server_name example.com www.example.com;
ssl_certificate /etc/nginx/ssl/fullchain.pem;
ssl_certificate_key /etc/nginx/ssl/example.com.key;
ssl_protocols TLSv1.2 TLSv1.3; # 默认值随版本不同,务必显式声明
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
}
步骤 8:先测再灰度生效。
nginx -t
# nginx: configuration file /etc/nginx/nginx.conf test is successful
systemctl reload nginx # 平滑重载,存量连接不断
ss -lntp | grep ':443' # 确认 0.0.0.0:443 / [::]:443 已监听
为什么用 reload 不用 restart?reload 由 master 启动新 worker 并优雅退出旧 worker,长连接与正在传输的请求不受影响;restart 会先停进程,存量连接被 RST 掐断。若 nginx -t 通过但 reload 后浏览器仍报旧证书,先看 openssl s_client -connect example.com:443 -servername example.com | openssl x509 -noout -dates 的实际生效日期,再确认是否被 CDN 或前置负载均衡缓存了证书——这也是把 nginx ssl 配置教程跑通后最常遇到的”假故障”。
可直接粘贴的 nginx ssl 配置示例:逐条参数解释(nginx 1.26 + OpenSSL 3.0)
把下面这段配置直接存成 /etc/nginx/conf.d/example-ssl.conf,改掉域名和证书路径即可运行。它覆盖了 nginx 1.26 + OpenSSL 3.0 下 HTTPS 站点的全部关键指令,每条注释都标了引入版本,方便你在旧环境降级时判断哪行能删。
# ---------- 兜底 server:吃掉 IP 直连与未知 SNI 扫描 ----------
server {
listen 443 ssl default_server; # 必须是 default_server,否则不生效
server_name _;
ssl_reject_handshake on; # nginx 1.19.4+;直接拒绝握手,不必配证书
}
# ---------- 主站 ----------
server {
listen 443 ssl;
http2 on; # nginx 1.25.1+ 独立指令,替代 listen 443 ssl http2
server_name example.com www.example.com;
ssl_certificate /etc/nginx/ssl/fullchain.pem; # 叶证书 + 中间证书
ssl_certificate_key /etc/nginx/ssl/example.com.key; # 权限 600,属主 root
ssl_protocols TLSv1.2 TLSv1.3; # 1.26 默认值已是 TLSv1.2 TLSv1.3
ssl_prefer_server_ciphers off; # Mozilla intermediate 档推荐 off
# TLS 1.2 及以下套件(Mozilla intermediate 字符串,2024 版)
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:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
# TLS 1.3 套件由 OpenSSL 管理,ssl_ciphers 管不到,必须用 ssl_conf_command(nginx 1.19.4+ / OpenSSL 1.1.1+)
ssl_conf_command Ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256;
ssl_session_cache shared:SSL:10m; # 10m ≈ 4 万个会话,多 worker 共享
ssl_session_timeout 1d;
ssl_session_tickets off; # TLS 1.3 票据另需下一行才能彻底关
ssl_conf_command Options -SessionTicket;
# OCSP stapling 四件套:缺 resolver 会静默失效
ssl_stapling on;
ssl_stapling_verify on;
ssl_trusted_certificate /etc/nginx/ssl/chain.pem; # 只放中间证书,不含叶证书
resolver 223.5.5.5 119.29.29.29 valid=300s;
resolver_timeout 5s;
# 首次上线把 max-age 改成 300 观察一周,确认无 HTTP 资源后再提回 31536000
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
location / { root /var/www/html; index index.html; }
}
# ---------- 80 端口全量跳转 ----------
server {
listen 80;
server_name example.com www.example.com;
return 301 https://$host$request_uri;
}
几个容易被忽略的点,逐条说清:
- 为什么
http2 on;要单独写:据 nginx 1.25.1 变更日志,listen ... http2参数已废弃,1.26 下仍可用但会打 warning。写错位置(放进http{}块)会直接nginx: [emerg] "http2" directive is not allowed here。 ssl_prefer_server_ciphers off的理由:Mozilla SSL Configuration Generator 的 intermediate 档明确建议 off,让客户端按自己的硬件选套件(移动端优先 AES-128-GCM 或 ChaCha20 以省电、避免 AES-256 软实现)。只有需要强制合规套件顺序时才设 on。- 会话缓存容量换算:nginx 官方文档给出「1MB 约 4000 个会话」,按此推算见下表。
- OCSP 为什么必须配
resolver:nginx 用系统解析器之外的独立实现去查 OCSP 响应器,未配 resolver 时 stapling 不会报错、只是不生效——用openssl s_client -connect example.com:443 -servername example.com -status看到OCSP Response: no response sent就是这个原因。 - HSTS 回滚成本:RFC 6797 规定浏览器在 max-age 到期前必须强制 HTTPS,一旦下发 31536000 就无法「撤销」,只能等一年或让用户手动清缓存。所以先用 300 秒灰度。
ssl_session_cache |
可缓存会话数(约) | 适用场景 |
|---|---|---|
shared:SSL:1m |
4 000 | 低流量内部站、单机测试 |
shared:SSL:10m |
40 000 | 通用生产推荐(本示例) |
shared:SSL:50m |
200 000 | 高并发 / 短连接多的 API 网关 |
off |
0 | 不建议;每次连接都完整握手 |
改完先 nginx -t 再 nginx -s reload,随后用 curl -I https://example.com 确认 HSTS 头存在、用 openssl s_client -connect example.com:443 -tls1_1 确认旧协议已被拒绝(应返回 alert protocol version)。这套 nginx ssl 配置教程里的参数组合已对齐 Mozilla intermediate 与 RFC 8446 的推荐值,后续若要做 TLS 1.3 0-RTT 或 ECH,可在这份骨架基础上增量添加。
nginx ssl 配置方案选型对比:Mozilla 三档配置与证书类型怎么挑
问:网上流传的 nginx ssl 配置教程版本太多,我到底该抄 Mozilla 的哪一档?先给结论:绝大多数对外站点选 intermediate,内部服务间调用可选 modern,只有被老旧终端绑死时才用 old。据 Mozilla SSL Configuration Generator v5.7 的档位定义,可整理成下面这张选型表:
| 档位 | 启用协议 | TLS 1.2 套件策略 | 客户端覆盖 | 典型场景 |
|---|---|---|---|---|
| old | TLSv1 ~ TLSv1.3 | 兼容优先,保留 CBC | 接近 100% | Android 4.x、老式 POS 机、内网旧设备 |
| intermediate | TLSv1.2 + TLSv1.3 | 仅 AEAD,ECDHE-RSA/ECDSA 双证书 | 约 99.8% | 公网站点默认档 |
| modern | 仅 TLSv1.3 | 不适用(3 个 TLS 1.3 套件) | 约 96%~97% | 内部 API、服务间调用 |
为什么 intermediate 是默认答案?它保留 TLSv1.2,从而覆盖 Windows 7 自带 Schannel 和未升级的 Java 8 客户端,同时禁掉全部 CBC 套件,规避 Lucky13、Sweet32 一类padding oracle 与分组碰撞攻击。据 Mozilla 生成器说明,该档在主流客户端上的握手成功率接近 99.8%。
问:什么情况下才该退到 old 档?仅当必须兼容 Android 4.4 以下或老式 POS 终端时。退档前先算合规成本:PCI DSS 4.0 自 2024-03-31 起要求所有持卡人环境禁用 TLSv1.0/1.1,等保测评同样记为不符合项。实际做法是给这批设备单独开一个 server 块(按 server_name 或独立端口分流),主站仍用 intermediate。
问:modern 档能直接上生产吗?对外主站要谨慎——它会拒绝 Windows 7 上的 Chrome 69 及更早版本、未升级的 Java 8,后者典型报错是 javax.net.ssl.SSLHandshakeException: Received fatal alert: protocol_version。但把它用在 nginx 反向代理到内部 upstream 的段落非常合适:TLS 1.3 握手 1-RTT、支持 0-RTT 恢复。
三档的落地写法差异集中在三行指令上,下面是 intermediate 档的完整片段(nginx 1.26 + OpenSSL 3.0 验证通过):
# /etc/nginx/conf.d/example.conf
server {
listen 443 ssl;
http2 on; # nginx 1.25.1 起用独立指令,旧写法 "listen 443 ssl http2" 已废弃
server_name example.com;
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
# intermediate 档:nginx 1.23.4 起 ssl_protocols 默认值已是 "TLSv1.2 TLSv1.3",此处显式写出便于审计
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:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers off; # 默认 off(1.11.0 起),让客户端优先选 ChaCha20,利于移动端
ssl_session_cache shared:SSL:10m; # 默认 none;10m 约存 4 万个会话
ssl_session_timeout 1d; # 默认 5m
ssl_session_tickets off; # 默认 on,关闭以支持会话密钥轮换
add_header Strict-Transport-Security "max-age=63072000" always;
}
切到 old 档只需改两行:ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3; 并在 ssl_ciphers 尾部追加 ECDHE-RSA-AES128-SHA:ECDHE-RSA-AES256-SHA。切到 modern 档要特别注意一个坑:ssl_ciphers 对 TLS 1.3 套件不生效,必须改用 nginx 1.19.4 起支持的 ssl_conf_command Ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256;(依据 OpenSSL 3.0 的 SSL_CONF 接口文档)。
问:DV、OV、EV 证书会影响加密强度吗?不会。三者同为 RSA 2048 或 ECDSA P-256,nginx ssl 配置写法一字不改,差异只在组织信息核验、保险额度与有效期:
| 类型 | 价格区间(元/年) | 核验内容 | 适用 |
|---|---|---|---|
| DV(含 Let’s Encrypt 免费证书) | 0 / 商业 DV 约 50–300 | 仅域名控制权 | 博客、API、内部系统 |
| 通配符 DV | 约 300–1500 | 域名控制权(*.example.com) | 子域多、频繁增减 |
| OV | 约 800–3000 | 企业工商信息 + 域名 | 电商、B 端门户 |
| EV | 约 2000–8000 | 严格企业核验 + 法律存续证明 | 金融、招投标 |
选完档位,用一条命令即可验证实际协商结果,不必猜:
# 强制以 TLS 1.2 握手,看协议与套件是否落在预期档位内
openssl s_client -connect example.com:443 -tls1_2 /dev/null
| grep -E "Protocol|Cipher"
# 期望输出形如:Protocol: TLSv1.2 / Cipher: ECDHE-RSA-AES128-GCM-SHA256
# 若 modern 档返回 "no protocols available",说明客户端侧根本不支持 TLS 1.3
nginx ssl 配置常见报错与排查:这些真实报错你大概率会遇到
下面 5 条报错在 nginx 1.26 + OpenSSL 3.0 环境下复现率最高,每条都给出可直接执行的定位命令与修法。按 nginx 官方 ngx_http_ssl_module 文档,ssl_certificate 指向的文件必须同时包含站点证书与中间证书,这一条是后面多数“链不全”问题的总根源。
1. key values mismatch:证书和私钥不是一对
nginx: [emerg] SSL_CTX_use_certificate_chain_file("/etc/nginx/ssl/fullchain.pem") failed
(SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch)
# RSA 证书:两条命令输出的 MD5 必须完全一致
openssl x509 -noout -modulus -in /etc/nginx/ssl/fullchain.pem | openssl md5
openssl rsa -noout -modulus -in /etc/nginx/ssl/example.com.key | openssl md5
# ECDSA 证书没有 modulus 字段(Let's Encrypt 已逐步默认签发 P-256),改比公钥
openssl x509 -noout -pubkey -in /etc/nginx/ssl/fullchain.pem | openssl md5
openssl ec -noout -pubkey -in /etc/nginx/ssl/example.com.key | openssl md5
不一致的高频原因:续签脚本只替换了证书、没替换私钥,或 fullchain 里混入了上一周期的旧证书。
2. PEM_read_bio_X509_AUX() failed: no start line:文件不是 PEM 或路径写错
nginx: [emerg] PEM_read_bio_X509_AUX() failed (SSL: error:0909006C:PEM routines:get_name:no start line)
file /etc/nginx/ssl/fullchain.pem
# 期望输出:fullchain.pem: PEM certificate
# 若为 "ASCII text, with CRLF line terminators",即 Windows 换行,OpenSSL 3.0 直接判为非 PEM
sed -i 's/r$//' /etc/nginx/ssl/fullchain.pem
head -1 /etc/nginx/ssl/fullchain.pem # 必须是 -----BEGIN CERTIFICATE-----
grep -c 'BEGIN CERTIFICATE' /etc/nginx/ssl/fullchain.pem # 正常为 2(叶子+中间)
另一种情形是把 .der/.p7b 直接改名成 .pem,需先转换:openssl x509 -inform DER -in cert.der -out cert.pem。
3. ssl_stapling ignored:只是 warn,所以最容易被忽略
nginx: [warn] "ssl_stapling" ignored, issuer certificate not found for certificate "/etc/nginx/ssl/fullchain.pem"
含义是 fullchain 里没有签发者(中间)证书,或没配 ssl_trusted_certificate。nginx -t 仍会通过,线上表现为“静默不 staple”:
ssl_stapling on; # 默认 off
ssl_stapling_verify on; # 默认 off
ssl_trusted_certificate /etc/nginx/ssl/chain.pem; # 中间+根,不含站点证书
resolver 223.5.5.5 1.1.1.1 valid=300s; # 不配 resolver,stapling 同样不生效
resolver_timeout 5s;
验证是否真的生效:openssl s_client -connect example.com:443 -servername example.com -status </dev/null | grep -i "OCSP Response",应返回 successful。
4. unknown directive “ssl_certificate”:二进制没编译 SSL 模块
nginx: [emerg] unknown directive "ssl_certificate" in /etc/nginx/conf.d/example.conf:12
nginx -V 2>&1 | grep -o with-http_ssl_module # 无输出即未编入 ngx_http_ssl_module
nginx -V 2>&1 | tr ' ' 'n' | grep -i openssl # 顺带确认链接的 OpenSSL 版本
Debian/Ubuntu 的 nginx.org 官方源包、RHEL 的 nginx:mainline 默认带该模块;源码编译需加 –with-http_ssl_module –with-http_v2_module,且 OpenSSL ≥ 1.1.1 才有 TLS 1.3。
5. no cipher match:套件字符串写错,或把 TLS 1.3 套件塞进了 ssl_ciphers
nginx: [emerg] SSL_CTX_set_cipher_list("ECDHE-RSA-AES128-GCM-SHA256:TLS_AES_128_GCM_SHA256") failed
(SSL: error:0A0000B1:SSL routines::no cipher match)
OpenSSL 3.0 的 set_cipher_list 只接受 TLS 1.2 及以下套件名;TLS 1.3 套件必须走 ssl_conf_command(nginx ≥ 1.19.4):
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;
# ssl_ciphers 默认值 HIGH:!aNULL:!MD5
ssl_prefer_server_ciphers off; # 1.11.0 起默认 off,TLS 1.3 下应保持 off
ssl_conf_command Ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256;
浏览器侧的现象怎么快速对上根因?
| 客户端现象 | 真实根因 | 一句话验证 |
|---|---|---|
| ERR_CERT_AUTHORITY_INVALID;安卓/Java 日志 PKIX path building failed | 链不全,缺中间证书 | openssl s_client -showcerts 输出中 BEGIN CERTIFICATE 数量 ≥ 2 |
| ERR_SSL_PROTOCOL_ERROR / wrong version number | 443 端口被明文 HTTP 占用,或协议版本不匹配 | curl -vI https://example.com 看有无 HTTP 响应行 |
| ERR_CERT_COMMON_NAME_INVALID | SAN 未包含该域名 | openssl x509 -noout -text 查 Subject Alternative Name |
# TLS 握手成功会先打印 * SSL connection using TLSv1.3 / ...,再出现 < HTTP/1.1 200
curl -vI https://example.com
# 报 wrong version number / SSL_connect 失败,说明 443 上跑的是明文服务或协议对不上
排查顺序固定为 nginx -t → curl -vI → openssl s_client,三层逐级下探,比反复刷新浏览器控制台快得多。
怎么验证 nginx ssl 配置真的生效:6 条命令逐条看输出
改完 ssl_protocols 并 systemctl reload nginx,浏览器地址栏的小锁只是最低门槛——它连证书过期都不会提醒你。真正的验证要回答四个问题:改的是不是正在跑的那份配置、旧协议关没关、链全不全、OCSP 与 HSTS 是否真的下发。下面 6 条命令按“由内到外”的顺序排,每条都给出预期输出与失败信号(环境:nginx 1.26.0 + OpenSSL 3.0.x)。
命令 1:配置语法 + 打印合并后的最终配置。nginx -t 只能证明语法能解析,证明不了你改的 server 块没被后面的 include 覆盖。nginx 自 1.9.2 起支持 -T,会 dump 出 include 展开后的完整配置:
# 1) 语法自检:两行输出缺一不可
nginx -t
# nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
# nginx: configuration file /etc/nginx/nginx.conf test is successful
# 2) 打印合并后配置,确认生效的是你改的那一份(-n 带行号便于定位)
nginx -T 2>/dev/null | grep -n "ssl_protocols|ssl_ciphers|ssl_stapling"
# 期望只出现一处 ssl_protocols,且值形如 TLSv1.2 TLSv1.3
如果 grep 出两行 ssl_protocols,说明 conf.d/ 里还有旧文件被 include,nginx 以最后出现的为准,你的修改等于白改。
命令 2:验证旧协议真的关掉了。先用 TLSv1.2 确认服务可用,再用 -tls1 确认被拒:
# 正常路径:能取到证书主体/签发者/有效期
openssl s_client -connect example.com:443 -servername example.com -tls1_2 </dev/null 2>/dev/null
| openssl x509 -noout -subject -issuer -dates
# 反向验证:TLSv1.0 必须失败
openssl s_client -connect example.com:443 -servername example.com -tls1 </dev/null
# 期望失败,报错文本取决于构建:
# no protocols available ← 客户端编译时已禁用 TLSv1
# tlsv1 alert protocol version ← 服务端拒绝
# sslv3 alert handshake failure ← 无共同套件
-servername 不能省:SNI 缺失时 nginx 会落到默认 server 块,测到的可能根本不是你的站点。
命令 3:证书链是否完整。这是移动端与 Java 客户端报 unable to get local issuer certificate 的头号原因:
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null
| grep -c "BEGIN CERTIFICATE"
# 必须输出 2:叶证书 + 中间证书(example.com + R1x/R3 之类)
# 输出 1 = 只发了叶证书,需在 nginx 里把 ssl_certificate 指向 fullchain.pem
按 Let’s Encrypt 文档,fullchain.pem = 叶证书 + 中间证书,chain.pem 仅中间证书(供 ssl_trusted_certificate 做 OCSP 验证用),二者用途不同,别混用。
命令 4:OCSP stapling 是否真的工作。stapling 生效需要四件套齐全:ssl_stapling on、ssl_stapling_verify on、ssl_trusted_certificate、resolver。缺任一项,nginx 会静默不 stapling,配置里看不出任何报错:
openssl s_client -connect example.com:443 -servername example.com -status </dev/null 2>/dev/null
| grep -iE "OCSP Response Status|thisUpdate|nextUpdate"
# 期望:OCSP Response Status: successful (0x0)
# thisUpdate=... nextUpdate=...
# 失败:OCSP response: no response sent
nextUpdate 通常是 7 天内,超过说明缓存的 OCSP 响应已陈旧,需检查 nginx error log 里的 resolver 超时。
命令 5:从外部枚举套件与协议。自测通过不代表对外表现一致(CDN、WAF、负载均衡可能改写):
# 方式 A:nmap 脚本(nmap 7.x,需脚本库含 ssl-enum-ciphers)
nmap --script ssl-enum-ciphers -p 443 example.com
# 方式 B:testssl.sh 3.2,--quiet 只输出结论
testssl.sh --quiet --protocols https://example.com
输出里不应再出现 TLSv1.0 / TLSv1.1 段,也不应出现 RC4、3DES、EXPORT 套件。据 Mozilla SSL Configuration Generator 的 “intermediate” 配置,ssl_ciphers 的推荐基线已不含任何 CBC 套件;nginx 默认值是 HIGH:!aNULL:!MD5(nginx 1.26 未改),过于宽松,需显式覆盖。
命令 6:跳转与 HSTS 头。HSTS 只有浏览器从 HTTPS 响应里读到才生效,写错在 HTTP 段等于没写:
curl -sI https://example.com | grep -i strict-transport-security
# 期望:strict-transport-security: max-age=31536000; includeSubDomains
curl -sI http://example.com | head -n 3
# 期望:HTTP/1.1 301 Moved Permanently
# Location: https://example.com/
max-age 建议先从 300 试跑,确认全站子域都支持 HTTPS 后再提到 31536000——HSTS 一旦下发就无法撤回。
| 检查项 | 命令 | 通过信号 | 失败时先看哪里 |
|---|---|---|---|
| 配置生效 | nginx -T | grep -n ssl_protocols |
只出现一处,值为 TLSv1.2 TLSv1.3 | conf.d/ 是否被重复 include |
| 旧协议关闭 | openssl s_client -tls1 |
握手失败 | 是否被默认 server 块覆盖 |
| 证书链完整 | grep -c "BEGIN CERTIFICATE" |
输出 2 | ssl_certificate 是否指向 fullchain |
| OCSP stapling | s_client -status |
successful (0x0) | 四件套与 resolver、error.log |
| 对外套件 | testssl.sh --protocols |
无 TLSv1.0/1.1、无 RC4 | 前置 CDN / LB 的 TLS 策略 |
| HSTS 与跳转 | curl -sI |
有 max-age + 301 | HSTS 是否错写在 80 端口的 server 块 |
六项全绿后再用 Qualys SSL Labs 复核:据 SSL Labs 评分文档,拿 A/A+ 的前提正是 HSTS 生效、无 TLSv1.0/1.1、无 RC4/3DES;只有 A+ 还额外要求 includeSubDomains 且 max-age ≥ 6 个月。评分只做最终确认,不能替代上面逐条命令——它不告诉你 nginx -T 里那份配置到底来自哪个文件。
让 nginx ssl 配置长期稳定:续期、监控与几个性能参数
问:Let’s Encrypt 证书 90 天到期,certbot 续期后 nginx 会自动加载吗?
不会自动加载,必须靠 deploy hook 触发 reload。这也是 nginx ssl 配置教程里最容易被忽略的一步。certbot 2.x 安装后通常自带 certbot.timer,据 Let’s Encrypt 文档每天运行两次并带随机延迟;它只负责续期。命令行用 --deploy-hook,--renew-hook 在 certbot 2.x 已标记 deprecated。上线前先跑一次 certbot renew --dry-run,验证 ACME 账户、域名校验和续期流程(不写生产证书)。
# 适用:certbot 2.x + systemd,nginx 1.26
systemctl list-timers --all | grep certbot # 应看到 certbot.timer,每天触发 2 次
sudo certbot renew --dry-run # 不写生产证书,验证续期链路
sudo certbot renew --deploy-hook "systemctl reload nginx" # 本次续期成功后 reload
# 持久化:编辑 /etc/letsencrypt/renewal/example.com.conf,加入
# renew_hook = systemctl reload nginx
# 配置键名仍为 renew_hook,但命令行参数请用 --deploy-hook
# 不要再用 --renew-hook:certbot 2.x 已标记 deprecated
hook 失败时常见输出:
Hook command "systemctl reload nginx" returned error code 1。此时证书已续,但 nginx 仍加载旧证书,线上notAfter不会前移。
问:怎么在证书过期前主动发现?
直接读 443 端口的 notAfter,比只看本地文件更接近真实。据 OpenSSL 3.0 文档,s_client 要带 -servername 发送 SNI;notAfter 语义见 RFC 5280。下面脚本剩余天数小于 21 天返回非 0,交给 cron 或监控告警。
#!/usr/bin/env bash
# /usr/local/bin/check-cert.sh;GNU date + OpenSSL 3.0
DOMAIN="${1:?usage: check-cert.sh example.com}"
END=$(echo | openssl s_client -connect "$DOMAIN:443" -servername "$DOMAIN" 2>/dev/null
| openssl x509 -noout -enddate | cut -d= -f2)
[ -z "$END" ] && { echo "CRITICAL: cannot read cert for $DOMAIN"; exit 2; }
DAYS=$(( ( $(date -d "$END" +%s) - $(date +%s) ) / 86400 ))
echo "$DOMAIN notAfter=$END remaining=${DAYS}d"
if [ "$DAYS" -lt 21 ]; then
echo "WARN: $DOMAIN expires in ${DAYS} days" >&2
exit 1
fi
# 每天 03:17 检查;退出码非 0 时由监控系统或 mail 告警
17 3 * * * /usr/local/bin/check-cert.sh example.com >> /var/log/cert-check.log 2>&1 || logger -t cert-check "cert expiry warning"
问:ssl_session_cache shared:SSL:10m 值不值得开?
值得,尤其是多 worker 的 nginx。默认 ssl_session_cache none,会话复用能力弱;shared:SSL:10m 让所有 worker 共享同一块缓存,减少重复完整握手。据 nginx 官方文档,1MB 约存 4000 个会话,10m 约 4 万;按站点 QPS 和 ssl_session_timeout(默认 5m)估算,10m~50m 足够大多数站点。TLS 1.3 的复用还依赖 session ticket,可与共享缓存配合。
ssl_session_cache shared:SSL:10m; # 默认 none;10m ≈ 40000 会话
ssl_session_timeout 1h; # 默认 5m;调大提升复用率,但占用缓存更久
问:ssl_buffer_size 设 4k 还是 16k?
默认 16k。nginx 文档明确说明较小的缓冲区能降低 TTFB,代价是吞吐略降;这是“首字节优先”与“吞吐优先”的取舍。
| 取值 | 适用场景 | TTFB | 吞吐 | 说明 |
|---|---|---|---|---|
| 16k(默认) | 大文件下载、视频 | 较高 | 更高 | 保持默认即可 |
| 4k | API、HTML 首屏 | 更低 | 略降 | nginx 文档明确降低 TTFB |
ssl_buffer_size 4k; # 默认 16k;首字节优先的站点可设 4k
问:曲线和 HTTP/2 在 nginx 1.26 上怎么写才不踩废弃项?
ssl_ecdh_curve X25519:prime256v1; 兼顾新老客户端;nginx 1.11.0 起默认 auto。HTTP/2 从 nginx 1.25.1 起改用独立指令 http2 on;,旧的 listen 443 ssl http2; 已被标记 deprecated,未来版本会移除;HTTP/2 本身由 RFC 9113 定义。
server {
listen 443 ssl;
http2 on; # nginx ≥1.25.1;旧写法 listen 443 ssl http2 已 deprecated
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
ssl_ecdh_curve X25519:prime256v1; # nginx ≥1.11.0 默认 auto
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1h; # 默认 5m
ssl_buffer_size 4k; # 默认 16k
}
改完先 nginx -t 再 systemctl reload nginx;reload 不会中断现有连接。把 dry-run、到期检查和 reload 都纳入变更流程,这份 nginx ssl 配置教程的配置才算从“能通”走到“长期稳定”。
四行即可:listen 443 ssl;、ssl_certificate /etc/nginx/ssl/fullchain.pem;、ssl_certificate_key /etc/nginx/ssl/example.com.key;、ssl_protocols TLSv1.2 TLSv1.3;。这四行能保证 HTTPS 可用且不启用已废弃协议,ssl_ciphers、OCSP stapling、HSTS 属于加固项,可以后补。
必须放 fullchain.pem。cert.pem 只有站点证书一张,缺中间证书时桌面浏览器靠 AIA 补链看不出来,但 Android、Java、部分 iOS 版本会直接握手失败。判断方法:openssl s_client -showcerts 输出里 BEGIN CERTIFICATE 出现 2 次才算完整。
Caddy 2.7+ 内置 ACME,域名解析到本机就自动签发和续期,配置量约等于零;Apache 的 SSLCertificateFile 语义与 nginx 接近,但需要额外写 SSLCertificateChainFile。nginx 的劣势是证书获取与续期要另配 certbot,优势是单机高并发、HTTP/2 与动态模块成熟,反代与灰度发布场景更常见。
这是证书与私钥不配对。用 openssl x509 -noout -modulus -in fullchain.pem | openssl md5 和 openssl rsa -noout -modulus -in example.com.key | openssl md5 各算一次,两个 MD5 必须一致;不一致就说明私钥和证书不是同一次 CSR 产出的,重新签发或找回原私钥即可。
因为 ssl_ciphers 只作用于 TLSv1.2 及以下。TLSv1.3 的套件由 OpenSSL 的 Ciphersuites 参数控制,需要在 nginx 里写 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_certificate 指向 fullchain、ssl_certificate_key 指向私钥。差别在证书本身:Let's Encrypt 有效期 90 天、只校验域名控制权、无保险;OV 约 800–3000 元/年、有效期最长 398 天、含组织核验信息。加密强度两者相同。
按三步排查:先看是否混合内容,F12 控制台会列出 http:// 资源;再确认链完整性,openssl s_client -showcerts 是否输出 2 张证书;最后核对服务器与客户端时间,偏差超过证书有效期会直接报 NET::ERR_CERT_DATE_INVALID。HSTS 已下发时清缓存要用 chrome://net-internals/#hsts 手动删除域名。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。