跳到主要内容
安装配置教程

nginx ssl 配置教程:从 CSR 到 reload 的 8 步实操与排错(nginx 1.26 + OpenSSL 3.0)

nginx ssl 配置教程 — 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 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

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