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

tls 配置生成器怎么用?Nginx/Apache 从生成到验证的完整步骤

tls 配置生成器 — tls 配置生成器怎么用?Nginx/Apache 从生成到验证的完整步骤
核心结论

直接使用 Mozilla SSL Configuration Generator(ssl-config.mozilla.org),选择 Nginx 1.26/OpenSSL 3.0 与 Intermediate 档,可生成启用 TLS 1.2/1.3、禁用 TLS 1.0/1.1 的配置;生成后必须替换证书路径并用 nginx -t、openssl s_client 验证。 公开站点优先 Intermediate,兼顾较旧客户端;仅明确只服务新客户端时考虑 Modern;Old 档含 TLS 1.0/1.1,不应作为新部署默认。 Nginx 1.26 示例关键参数:ssl_protocols TLSv1.2 TLSv1.3;ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:...';ssl_prefer_server_ciphers off;ssl_session_cache shared:SSL:10m。 证书链用 fullchain.pem,私钥权限 600;OCSP stapling 需 ssl_trusted_certificate 与可用 resolver,否则日志出现 ssl_stapling ignored。 验证至少跑 openssl s_client -tls1_2、-tls1_3 与 curl -I,确认 Verify return code: 0 (ok)、HTTP 200、HSTS 头存在。

为什么 tls 配置生成器不能一复制就上线?

不能。tls 配置生成器给出的是一段”看起来能跑”的文本,它默认你已经具备若干前提:编译期链接了足够新的 OpenSSL、证书文件是完整链、续期后有钩子重载进程。任何一条不成立,配置都能通过 nginx -t,却在真实客户端上握手失败。先看第一个前提。

问:怎么确认服务器到底支持哪些指令?
答:不要猜,直接读编译信息。Nginx 1.9.11 起支持 -V 输出详细参数:

# 拆分空格后过滤,避免一行输出难以阅读
nginx -V 2>&1 | tr ' ' 'n' | grep -E 'nginx|openssl'
# 典型输出:
# nginx/1.26.0
# built with OpenSSL 3.0.13 30 Jan 2024 (running with OpenSSL 3.0.13 30 Jan 2024)

若实际是 OpenSSL 1.0.2(CentOS 7 默认),ssl_protocols TLSv1.3 会直接报 invalid value "TLSv1.3",ssl_conf_command 也不存在——它是 Nginx 1.19.4 + OpenSSL 1.1.1 才引入的。Apache 同理,用 httpd -V 与 apachectl -M | grep ssl 确认模块版本。

问:Modern / Intermediate / Old 到底怎么选?
据 Mozilla SSL Configuration Generator 页面,三档面向不同客户端覆盖范围,不是”越新越好”:

档位 启用协议 客户端范围 适用判断
Modern 仅 TLS 1.3 OpenSSL 1.1.1+、Chrome 70+、Firefox 63+ 内部服务、API 网关,可放弃旧客户端
Intermediate TLS 1.2 + 1.3 Android 4.4+、IE 11、Java 8+ 绝大多数公网站点的默认选择
Old TLS 1.0 / 1.1 / 1.2 / 1.3 IE 8、Android 2.3 等 不满足 PCI DSS 现行基线,仅遗留系统

问:为什么配好了浏览器能开,Java 客户端却报错?
生成器只给指令,不给证书链。Nginx 的 ssl_certificate 必须指向包含中间证书的 fullchain.pem,而不是域名证书本身;只写 leaf 证书时,部分 Android 与 Java 客户端会抛 unable to get local issuer certificate。校验方式:

# 链中应出现 2 个及以上证书(leaf + intermediate)
openssl crl2pkcs7 -nocrl -certfile /etc/letsencrypt/live/example.com/fullchain.pem 
  | openssl pkcs7 -print_certs -noout

问:还有哪些东西生成器不写?
OCSP stapling 需要 resolver 与 ssl_trusted_certificate 才能生效;HSTS 的 max-age=31536000 必须等全站 HTTPS 验证通过后再加,否则回滚成本极高;HTTP→HTTPS 跳转、HTTP/2 的 listen 443 ssl http2 也都不在核心输出里。此外据 Let’s Encrypt 文档,证书有效期 90 天,certbot 2.10.0 需要显式钩子,否则续期后 Nginx 进程仍加载旧证书:

# --deploy-hook 仅在证书真正更新后触发,不会每次都重载
certbot renew --deploy-hook 'systemctl reload nginx'

最后一个坑在发行版层面:Debian/Ubuntu 常在 openssl.cnf 写入 CipherString = DEFAULT:@SECLEVEL=2,导致 1024 位 RSA 与 SHA-1 签名证书被直接拒绝。用 openssl version -d 定位配置目录,再决定是调档还是更换证书,而不是盲目复制生成器的兼容档。

按步骤操作:从版本确认到重载生效

下面按真实执行顺序走一遍。每一步都给出可直接复制的命令,并在关键处说明”为什么”这么做。

第一步:先记录版本,别凭印象填生成器。生成器的输出随版本变化(Nginx 1.26 起默认启用 TLSv1.3 相关指令、OpenSSL 3.x 的 cipher 名称与 1.1.1 有差异),版本填错会拿到在当前环境里直接报 unknown directive 的片段。

# 一次性采集四个版本号,输出可直接对照生成器下拉框
nginx -V 2>&1 | tr ' ' 'n' | grep -E 'nginx|openssl'
apachectl -v
openssl version
certbot --version

# 典型输出(Nginx 把 OpenSSL 版本编进 -V 里,注意这里是编译时版本)
# nginx/1.26.0
# built with OpenSSL 3.0.13 30 Jan 2024
# Apache/2.4.62 (Unix)
# OpenSSL 3.0.13 30 Jan 2024
# certbot 2.11.0

注意 nginx -V 显示的是编译期 OpenSSL,openssl version 显示的是系统库,两者不一致时以生成器要填的那个为准——Mozilla SSL Configuration Generator 要的是”你实际用于 TLS 握手的库版本”,Nginx 静态编译时就是前者。据 Mozilla 服务器端 TLS 指南,Intermediate 配置面向”大多数通用服务器”,兼容 Firefox 27、Chrome 31、Android 4.4.2 及以上,这也是它成为默认推荐的原因。

第二步:打开 ssl-config.mozilla.org 生成片段。Server Software 选 Nginx,Version 选 1.26.0,OpenSSL 选 3.0.13,Profile 选 Intermediate,勾选 HTTP/2(若你已在用)。复制出的 server { listen 443 ssl; ... } 段落先不要覆盖 80 端口那个 server 块——80 块后面还要用来做跳转。

第三步:备份并替换证书路径。

# 带日期后缀备份,出问题可秒回滚
cp /etc/nginx/conf.d/example.conf /etc/nginx/conf.d/example.conf.bak.$(date +%F)

# 生成片段里的占位路径需替换为 Let's Encrypt 实际路径
# ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;   # 含中间证书,必须用 fullchain 而非 cert.pem
# ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

用 fullchain.pem 而不是 cert.pem 是关键:缺中间证书时桌面浏览器常能靠缓存蒙混过关,但 Android 与部分 Java 客户端会直接报 unable to get local issuer certificate。

第四步:证书权限与 SELinux。

chmod 600 /etc/letsencrypt/live/example.com/privkey.pem
chown root:root /etc/letsencrypt/live/example.com/privkey.pem
# nginx -V 显示 --user=nginx 时,worker 进程以 nginx 用户运行,需确认其可读:
namei -l /etc/letsencrypt/live/example.com/privkey.pem
# SELinux 启用(getenforce 返回 Enforcing)时补一步:
restorecon -Rv /etc/letsencrypt

权限设 600 且属主 root 后,master 进程以 root 读取证书没问题,但若你把 ssl_certificate 放在非标准目录且 worker 需直接读,就会撞上 Permission denied。

第五步:语法检查后 reload,不要 restart。

nginx -t                 # 必须看到 syntax is ok / test is successful 两行
systemctl reload nginx   # reload 平滑加载,不断开现有连接

# Apache 对应命令
apachectl configtest     # 输出 Syntax OK
systemctl reload httpd

失败时不要 restart:reload 失败旧进程仍在服务,restart 则会把老配置一起带走。先 tail -f /var/log/nginx/error.log 定位行号,常见报错 nginx: [emerg] cannot load certificate ... BIO_new_file() failed 基本都是路径写错或权限不足。

第六步:补跳转与续期钩子。

# 80 端口 server 块内加入强制跳转
server {
    listen 80;
    server_name example.com;
    return 301 https://$host$request_uri;
}

# 续期演练(不消耗速率限制),并挂 deploy hook 自动 reload
certbot renew --dry-run
certbot renew --deploy-hook "systemctl reload nginx"

据 Let’s Encrypt 文档,证书有效期 90 天,官方建议在剩余 30 天内续期,certbot 的 systemd timer 默认每天跑两次并带随机延迟。deploy hook 只在证书真正更新时触发,因此不会每天无谓 reload。至此,一个由 tls 配置生成器产出、经版本校准与实测验证的配置才算闭环。

Nginx、Apache 与 OpenSSL 的可复制示例(含参数)

拿到 tls 配置生成器 输出的片段,第一件事该做什么?先核对本机版本,因为同一条指令在不同版本里默认值和语义都变过。例如 Nginx 从 1.25.1 起把 HTTP/2 从 listen 443 ssl http2 拆成独立的 http2 on;,旧写法在 1.26 会报 [warn] the "listen ... http2" directive is deprecated;Nginx 1.23.4 起 ssl_protocols 的默认值才变成 TLSv1.2 TLSv1.3。下面的示例按 Nginx 1.26 + OpenSSL 3.0 与 Apache 2.4.59 编写。

# /etc/nginx/conf.d/example.com.conf —— Nginx 1.26
server {
    listen 443 ssl;                  # 1.25.1+ 不再在 listen 里写 http2
    http2 on;
    server_name example.com;

    ssl_certificate         /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key     /etc/letsencrypt/live/example.com/privkey.pem;
    ssl_trusted_certificate /etc/letsencrypt/live/example.com/chain.pem;  # 只用于 OCSP 校验,不下发给客户端

    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;        # 默认 off;Mozilla SSL Configuration Generator 亦推荐 off
    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=31536000' always;  # always 需 Nginx ≥1.7.5
}

OCSP stapling 为什么常配了却不生效?九成是 resolver 指向了不可达的 DNS。Nginx 需要自己解析 OCSP 响应地址,若内网 DNS 不递归外网,error.log 会持续输出 ssl_stapling ignored 一类告警(如 OCSP responder timed out),握手仍成功但响应未装订。把 resolver 改成可达的递归服务器即可:

# 仍写在 server{} 内
resolver 1.1.1.1 8.8.8.8 valid=300s;   # valid 控制缓存时长,默认遵循响应 TTL
resolver_timeout 5s;                    # 默认 30s
ssl_stapling on;                        # 默认 off
ssl_stapling_verify on;
ssl_trusted_certificate /etc/letsencrypt/live/example.com/chain.pem;
# Apache 2.4.59:SSLStaplingCache 必须放全局,不能写进 <VirtualHost>
SSLStaplingCache shmcb:/run/httpd/ssl_stapling(32768)

<VirtualHost *:443>
    ServerName example.com
    SSLEngine on
    SSLCertificateFile    /etc/letsencrypt/live/example.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem

    SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1
    SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384
    SSLHonorCipherOrder off    # 默认 off
    SSLSessionTickets off      # 默认 on(2.4.11+)
    SSLUseStapling on          # 默认 off
    Header always set Strict-Transport-Security "max-age=31536000"  # 需 mod_headers
</VirtualHost>
能力 Nginx 指令 / 默认值 Apache 指令 / 默认值
协议版本 ssl_protocols,默认 TLSv1.2 TLSv1.3 SSLProtocol,默认 all -SSLv3
套件列表 ssl_ciphers,默认 HIGH:!aNULL:!MD5 SSLCipherSuite,默认 DEFAULT
会话票据 ssl_session_tickets,默认 on SSLSessionTickets,默认 on
OCSP 装订 ssl_stapling,默认 off SSLUseStapling,默认 off

怎么证明配置真的生效?用 s_client 分别打 1.2 和 1.3,看三行输出:

# TLS 1.2
openssl s_client -connect example.com:443 -servername example.com -tls1_2 </dev/null 
  | grep -E 'Protocol|Cipher|Verify return code'
# 期望:Protocol  : TLSv1.2
#       Cipher    : ECDHE-RSA-AES128-GCM-SHA256
#       Verify return code: 0 (ok)

# TLS 1.3
openssl s_client -connect example.com:443 -servername example.com -tls1_3 </dev/null 
  | grep -E 'Protocol|Cipher|Verify return code'
# 期望:Protocol  : TLSv1.3
#       Cipher    : TLS_AES_256_GCM_SHA384 或 TLS_CHACHA20_POLY1305_SHA256

注意 Verify return code: 0 (ok) 校验的是本机信任库,若服务端漏发中间证书会变成 21 (unable to verify the first certificate)。另外据 OpenSSL 3.0 文档,TLS 1.3 的套件由 Ciphersuites(SSL_CTX_set_ciphersuites)控制,不受 ssl_ciphers / SSLCipherSuite 影响,所以生成器里那串 ECDHE 套件只对 TLS 1.2 有效;若 -tls1_3 直接报 ssl handshake failure,说明服务端关掉了 1.3。证书侧用 Let’s Encrypt 签发并验证自动续期(有效期 90 天,certbot 2.10.0 默认在到期前 30 天续期):

sudo certbot certonly --webroot -w /var/www/html 
  -d example.com -d www.example.com 
  --deploy-hook 'systemctl reload nginx'   # 仅在新证书落地时触发重载

sudo certbot renew --dry-run               # 演练,不写盘、不触发 hook

最后做一次整体回归:nginx -t 或 apachectl configtest 通过后重载,再用上面的两条 s_client 命令确认协议、套件与证书链三者同时符合预期。

Modern、Intermediate、Old 与生成器方案怎么选?

问:Mozilla SSL Configuration Generator 里的 Modern、Intermediate、Old 三档到底差在哪,我的站点该选哪一档?

据 Mozilla SSL Configuration Generator(当前配置版本 5.7)页面说明,三档的差异集中在协议下限与密码套件集合上,而不是“安全等级”这种模糊说法。三档的实际取舍如下:

档位 启用的协议 目标客户端(Mozilla 口径) 典型用途 代价
Modern TLS 1.3、TLS 1.2 Firefox 63、Chrome 70、Edge 75、Android 10+ 等较新客户端 内部 API、可控客户端、服务间 mTLS 兼容面窄,旧设备直接握手失败
Intermediate TLS 1.3、TLS 1.2 Firefox 27、Chrome 31、IE 11(Win7)、Android 4.4+ 公开网站的事实默认档 需同时保留 ECDHE-RSA 与 ECDHE-ECDSA 套件
Old TLS 1.3 / 1.2 / 1.1 / 1.0 遗留嵌入式设备、老 POS、旧 Java 6/7 仅为兼容存量硬件 TLS 1.0/1.1 已被 RFC 8996 弃用,PCI DSS 不合规

问:那“默认 Intermediate”是不是一句口号?怎么用数据确认?

公开站点确实应默认 Intermediate;只有在访问日志显示 0.5% 以上客户端仍为 Android 7 以下或旧 Java 时,才需要保留 TLS 1.2 与 RSA 证书;仅当你能确认所有客户端都支持 TLS 1.3,才切到 Modern。判定方式是给 Nginx 加一条带 $ssl_protocol 的日志,而不是凭感觉:

# /etc/nginx/nginx.conf(http 块内),Nginx 任意在维护版本均支持
log_format tls '$remote_addr $ssl_protocol "$http_user_agent"';
access_log /var/log/nginx/tls.log tls;

# 统计各协议版本占比(字段 2 即 $ssl_protocol)
awk '{print $2}' /var/log/nginx/tls.log | sort | uniq -c | sort -rn
# 输出示例:
#  48213 TLSv1.3
#   3102 TLSv1.2
#      7 TLSv1.1   ← 仍有 1.1 流量时不要急着删 TLSv1.2 之前的兼容策略

问:生成器、nginxconfig.io、Certbot、手写基线,工具怎么选?

方案 产出物 优势 需要注意 适合
Mozilla SSL Configuration Generator Nginx/Apache/HAProxy 的 TLS 指令片段 有 RFC 与浏览器版本依据,可作为基线 需手工替换证书路径,不含 server 块与跳转 首次建立基线
nginxconfig.io 完整 server 块、HTTP→HTTPS 跳转、gzip 等 开箱可用,选项覆盖广 选项多,生成后必须逐项复核 快速搭站
Certbot --nginx 直接改写现有配置并配置续期 与 Let’s Encrypt 自动化闭环 依赖 nginx 插件与现有配置结构,可能覆盖手改内容 Let’s Encrypt 自动签发
手写基线 自维护 conf 片段 完全可控、可纳入 Git 与合规审计 需自行跟踪 cipher 与套件变化 有等保/PCI 要求的团队

无论用哪个 tls 配置生成器,生成后都要替换证书路径并确认证书链完整(fullchain.pem 而非 cert.pem)。以 Intermediate 为例(Nginx ≥1.20、OpenSSL ≥1.1.1):

# /etc/nginx/conf.d/tls.conf
ssl_protocols TLSv1.2 TLSv1.3;          # Intermediate 不含 TLS 1.0/1.1
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;          # Nginx 1.11.0 起即为默认值,显式写出便于审计
ssl_session_cache shared:MozSSL:10m;    # Mozilla 推荐 10m
ssl_session_timeout 1d;
ssl_session_tickets off;
ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

问:cipher 顺序还要不要自己排?TLS 1.3 的套件能改吗?

不能。Nginx 1.26 的默认值就是 ssl_prefer_server_ciphers off,交由客户端按自身偏好选择,这符合现代实践;而 TLS 1.3 的 TLS_AES_128_GCM_SHA256、TLS_AES_256_GCM_SHA384、TLS_CHACHA20_POLY1305_SHA256 由 OpenSSL 在握手层固定,ssl_ciphers 只影响 TLS 1.2 及以下,无法靠它增删 1.3 套件——这也是 Modern 档看起来“配置很短”的原因。

问:OCSP stapling 开还是不开?

开启可减少客户端额外请求,但它依赖 resolver 与 CA 的 OCSP 响应器;部分 CA 正在调整 OCSP 支持,部署前请查 CA 官方文档。若日志持续出现以下告警,先关闭 stapling 并保留完整证书链即可:

nginx: [warn] "ssl_stapling" ignored, no OCSP responder URL in the certificate
# 或:ssl_stapling ignored, issuer certificate not found(缺 chain.pem)
ssl_stapling on;
ssl_stapling_verify on;
ssl_trusted_certificate /etc/letsencrypt/live/example.com/chain.pem;
resolver 1.1.1.1 8.8.8.8 valid=300s;    # 缺少 resolver 时 stapling 不会生效
resolver_timeout 5s;

问:HSTS 的 max-age 一上来就写一年吗?

不要。首次上线用 300 秒灰度,确认所有子域都已 HTTPS 后再升到 31536000;includeSubDomains 与 preload 尤其谨慎——preload 提交到 hstspreload.org 后,从浏览器内置列表移除的周期以月计。

add_header Strict-Transport-Security "max-age=300" always;   # 第一周灰度
# 子域全部 HTTPS 后改为:
# add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

常见报错与排查:从 nginx -t 到握手失败

把 tls 配置生成器(例如 Mozilla SSL Configuration Generator)输出的片段贴进生产环境后,报错通常集中在四类:版本不支持、证书与私钥不配对、权限或 SELinux 拦截、证书链不完整。下面按真实报错原文逐条排查,命令可直接复制。

问:nginx -t 报 unknown directive "ssl_conf_command",是配置写错了吗?

不是写错,是版本不够。ssl_conf_command 由 nginx 1.19.4 引入(见 nginx CHANGES),且要求编译时链接 OpenSSL 1.1.1+;CentOS 7 的 1.16.1、Ubuntu 20.04 仓库的 1.18.0 都会直接拒绝。先确认版本与链接库:

# 查看 nginx 版本及编译时链接的 OpenSSL
nginx -V 2>&1 | tr ' ' 'n' | grep -E '^nginx/|OpenSSL'
# 旧环境典型输出:nginx/1.18.0 ... OpenSSL 1.1.1f
# 方案 A:整行删除 ssl_conf_command,回退到 ssl_ciphers
# 方案 B:升级到 nginx 1.26.0(2024-04 发布 stable)

若只是想让 TLS 1.3 套件生效,nginx ≥1.19.4 的等价写法是 ssl_conf_command Ciphersuites TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256;;低版本无法识别,只能删。

问:X509_check_private_key:key values mismatch 到底是证书问题还是私钥问题?

都不是,是两者不配对。完整报错为 SSL_CTX_use_PrivateKey_file(...) failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch)。据 OpenSSL 文档,该校验在加载阶段完成,所以 nginx -t 就会失败。RSA 用模数比对:

openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa  -noout -modulus -in privkey.pem  | openssl md5
# 两行 (stdin)= 后的值必须完全一致,否则换回正确私钥

ECDSA/Ed25519 没有 modulus,改比对公钥指纹:

openssl x509 -in fullchain.pem -pubkey -noout | openssl pkey -pubin -outform der | openssl md5
openssl pkey -in privkey.pem -pubout -outform der | openssl md5

问:路径没错、nginx -t 也过,worker 启动却报 Permission denied?

报错 SSL_CTX_use_certificate_chain_file(...) failed (SSL: error:0200100D:system library:fopen:Permission denied)。master 以 root 读配置,worker 以 nginx/www-data 运行;Let’s Encrypt 的 /etc/letsencrypt/live 是 0700 符号链接到 archive,最容易踩坑:

namei -l /etc/letsencrypt/live/example.com/fullchain.pem  # 逐级看权限
chmod 755 /etc/letsencrypt /etc/letsencrypt/{live,archive}
chmod 600 /etc/letsencrypt/archive/example.com/privkey*.pem
getenforce                                   # SELinux 是否为 Enforcing
restorecon -Rv /etc/letsencrypt              # 恢复 cert_t 上下文
# 仅用于定位,勿长期:setenforce 0

问:客户端报 verify error:num=20:unable to get local issuer certificate,链怎么补?

num=20 表示服务器只发了 leaf。Nginx 的 ssl_certificate 必须指向 fullchain.pem,而不是 cert.pem——据 Let’s Encrypt 文档,cert.pem 仅含站点证书。Apache 2.4.8+ 允许把链直接并入 SSLCertificateFile,SSLCertificateChainFile 自 2.4.8 起已废弃但仍兼容:

# Apache 2.4.8+
SSLCertificateFile    /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
# 旧写法:SSLCertificateChainFile .../chain.pem
# 验证链是否真的发出(期望 ≥2)
openssl s_client -connect example.com:443 -servername example.com -showcerts /dev/null | grep -c 'BEGIN CERTIFICATE'

问:'ssl_stapling' ignored, issuer certificate not found 需要处理吗?

需要。OCSP stapling 要用完整链验证签名,缺 issuer 时 nginx 只给 warn 并静默降级。补 trusted certificate 并保证 resolver 可达:

ssl_stapling on;
ssl_stapling_verify on;
ssl_trusted_certificate /etc/letsencrypt/live/example.com/chain.pem;
resolver 1.1.1.1 8.8.8.8 valid=300s;  # valid 覆盖 DNS TTL
resolver_timeout 5s;                  # 默认 30s

问:curl: (35) error:0A000410:SSL routines::sslv3 alert handshake failure 是协议还是套件问题?

是双方没有交集,需分别定位:

openssl s_client -connect example.com:443 -servername example.com -tls1_2 </dev/null
openssl s_client -connect example.com:443 -servername example.com -tls1_3 </dev/null
openssl s_client -connect example.com:443 -servername example.com -tls1_2 
  -cipher 'ECDHE-RSA-AES128-GCM-SHA256' </dev/null   # 指定套件复现

只有 -tls1_2 失败,查 ssl_ciphers 是否含该客户端套件;只有 -tls1_3 失败,多为 ssl_conf_command Ciphersuites 写错或 OpenSSL 过旧。据 Mozilla SSL Configuration Generator,Intermediate 档位仍保留 TLS 1.2;给老设备单独开 API 入口,比全局降级更安全。

报错关键字 根因 一条定位命令 修复
unknown directive ‘ssl_conf_command’ nginx < 1.19.4 或 OpenSSL < 1.1.1 nginx -V 删该行或升级 1.26.0
key values mismatch 证书与私钥不配对 modulus 管道比对 md5 换正确 privkey.pem
fopen:Permission denied worker 无读权限 / SELinux namei -l + getenforce 755/600 + restorecon
num=20 unable to get local issuer 只部署 leaf s_client -showcerts 改用 fullchain.pem
ssl_stapling ignored 缺 issuer 链 看 nginx error.log chain.pem + resolver
sslv3 alert handshake failure 协议/套件无交集 s_client -tls1_2 / -tls1_3 调整 ciphers 或分入口

改完统一回归,确认链完整且校验通过再上线:

nginx -t && systemctl reload nginx
openssl s_client -connect example.com:443 -servername example.com -verify_return_error </dev/null
# 期望末尾:Verify return code: 0 (ok)

怎么确认 tls 配置生成器结果真的生效?

Q:配置改完、nginx -t 也提示 ok,是不是就说明 tls 配置生成器给的那套参数已经生效了?

不是。nginx -t 只证明语法能被解析,不证明你期望的协议版本、证书链、HSTS 真的在 443 端口上对外呈现。据 Mozilla SSL Configuration Generator 的说明,生成器输出的是”建议模板”,最终是否落地要靠握手层验证。按下面五层顺序查,任何一层不符合都能直接定位到配置行。

第一层:进程与端口是否真的加载了新配置

# Nginx 1.18+ / systemd 发行版通用;reload 而非 restart 才能平滑生效
sudo nginx -t                      # 期望:syntax is ok / test is successful
sudo systemctl reload nginx
systemctl status nginx --no-pager | head -3   # 期望:Active: active (running)
ss -lntp | grep ':443'             # 期望:LISTEN 0 511 0.0.0.0:443 users:(("nginx",pid=...,fd=...))

若 ss 输出里没有 nginx,说明 listen 443 ssl; 写在了未启用的 server 块,或被别的 default_server 抢占。

第二层:证书链、签发者与剩余有效期

# OpenSSL 1.1.1 / 3.x 通用
openssl s_client -connect example.com:443 -servername example.com -showcerts /dev/null 
  | openssl x509 -noout -subject -issuer -dates
# 期望:subject=CN = example.com
#       issuer=... O = Let's Encrypt, CN = R11   (RSA 为 R10/R11,ECDSA 为 E5/E6)
#       notAfter 距今 ≤ 90 天(Let's Encrypt 文档规定的证书有效期上限)

若 issuer 显示的是根证书名或 CN = example.com 自签,说明 ssl_certificate 里漏拼了中间证书,必须用 fullchain.pem。

第三层:协议版本是否被限制到你写的那几个

# 分别强制 1.2 / 1.3,看协商结果
for v in tls1_2 tls1_3; do
  echo "== $v =="
  openssl s_client -connect example.com:443 -servername example.com -$v /dev/null 
    | grep -E 'Protocol|Cipher|Verify return code'
done
# 期望:Protocol : TLSv1.2 / TLSv1.3;Cipher 为 ECDHE-* 或 TLS_AES_*;Verify return code: 0 (ok)

# 反向验证:旧协议必须失败
openssl s_client -connect example.com:443 -servername example.com -tls1_1 </dev/null
# 期望:alert protocol version / handshake failure / no protocols available
# 若握手成功 → ssl_protocols 里仍含 TLSv1.1(Nginx 默认值仅 TLSv1.2 TLSv1.3,Apache 需显式 SSLProtocol -all +TLSv1.2 +TLSv1.3)

第四层:HTTP 层响应头与跳转

curl -sI https://example.com | grep -iE '^HTTP|strict-transport-security'
# 期望:HTTP/2 200 与 strict-transport-security: max-age=31536000(RFC 6797 定义的 HSTS)
curl -sI http://example.com | grep -iE '^HTTP|^location'
# 期望:301 与 Location: https://example.com/

第五层:外部扫描与 OCSP 装订

./testssl.sh --severity HIGH example.com      # testssl.sh 3.x,重点看 certificate / protocol / HSTS 三段
curl -s "https://api.ssllabs.com/api/v3/analyze?host=example.com&publish=off&all=done" | jq '.endpoints[].grade'
openssl s_client -connect example.com:443 -servername example.com -status /dev/null 
  | grep -A2 'OCSP Response Status'
# 期望:OCSP Response Status: successful (0x0)
# 出现 "no response sent" → 查 ssl_stapling on / ssl_trusted_certificate / resolver 是否可达
验证层 判定信号 不符合时的首个排查点
进程端口 active (running) + 443 有 nginx 监听 server 块是否被 default_server 覆盖
证书链 issuer 为 R11/E6,notAfter ≤ 90 天 是否误用 cert.pem 而非 fullchain.pem
协议 TLSv1.2/1.3 可连,TLSv1.1 报 handshake failure ssl_protocols / SSLProtocol
HTTP 头 200 + HSTS,HTTP 301 到 HTTPS add_header 是否被内层 location 覆盖
OCSP successful (0x0) resolver 与 ssl_trusted_certificate

这五层全部通过,才算 tls 配置生成器的结果真正落地;只跑 nginx -t 就收工,是线上最常见的”配置看着对、握手其实没变”的成因。

不建议直接复制。生成器只提供协议、cipher 与 session 等指令,证书路径、域名、OCSP resolver、HSTS 和跳转仍需按站点补齐;复制后至少执行 nginx -t、openssl s_client -tls1_2/-tls1_3 与 curl -I 验证。

Mozilla 生成器是静态基线,按 Nginx/OpenSSL 版本输出片段,不申请证书也不续期;Certbot 的 –nginx 插件会改现有 server 块并安装续期任务,适合 Let's Encrypt 自动化。生产上可先用生成器定基线,再用 certbot certonly –webroot 与 deploy hook 管理证书。

多数公开网站选 Intermediate,保留 TLS 1.2/1.3 并兼顾较旧客户端;Modern 更适合内部 API、明确只服务新客户端的场景。若日志中仍有 Android 7 以下或旧 Java 客户端,不要直接上 Modern。

这是证书与私钥不匹配。分别对 fullchain.pem 和 privkey.pem 计算 modulus 并比对,值不同就重新从 Let's Encrypt live 目录取同一套文件;确认 ssl_certificate 与 ssl_certificate_key 指向同一域名的 fullchain 与 privkey。

生成器只给 TLS 参数,证书链由 ssl_certificate 指向的文件决定。Nginx 应把 ssl_certificate 指向 fullchain.pem(leaf+intermediate),Apache 2.4.8+ 可把链放进 SSLCertificateFile,或使用 SSLCertificateChainFile 指向 chain.pem。

OCSP stapling 在 resolver 可达、链完整时可加,能减少客户端额外请求;若日志持续出现 ssl_stapling ignored,先排查 DNS 与 ssl_trusted_certificate。HSTS 建议先 max-age=300 验证,再升到 31536000,includeSubDomains 要等所有子域都支持 HTTPS。

先执行 nginx -V 看是否链接 OpenSSL 1.1.1+,再确认 ssl_protocols 含 TLSv1.3、listen 443 ssl 已启用且中间设备没有降级。TLS 1.3 的套件由 OpenSSL 控制,ssl_ciphers 只影响 TLS 1.2 及以下。


本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

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