跳到主要内容
错误排查

Nginx upstream SSL 握手失败排查:证书链、SNI 与 proxy_ssl_verify 配置指南

upstream ssl握手失败 — Nginx upstream SSL 握手失败排查:证书链、SNI 与 proxy_ssl_verify 配置指南
核心结论

upstream SSL 握手失败不是单一证书问题:在 Nginx 1.25.3 中先看 error.log 的 SSL_do_handshake 报错码,再用 openssl s_client -connect 后端:443 -servername 域名 -verify_return_error 复现,多数案例集中在证书链不完整、SNI 未开启、协议/套件不匹配和时钟偏差四类。 Nginx 的 proxy_ssl_verify 默认是 off,proxy_ssl_server_name 默认也是 off;要校验后端证书需同时配置 proxy_ssl_verify on、proxy_ssl_trusted_certificate 和 proxy_ssl_name。 报错 unable to get local issuer certificate 时,把后端完整链(叶子证书+中间证书)写入 /etc/nginx/ssl/upstream_ca.pem,或让后端发送中间证书;openssl s_client 返回 Verify return code: 0 (ok) 才算通过。 验证生效用 nginx -t && nginx -s reload 后执行 curl -v --resolve 域名:443:后端IP https://域名/health,并确认 error.log 不再出现 SSL_do_handshake() failed。

upstream SSL 握手失败是什么原因?先分清 Nginx 与后端谁在报错

先把链路切开。浏览器 → Nginx 是一段 TLS;Nginx → 后端 443 是另一段 TLS,后者才是本节说的 upstream SSL 握手失败:TCP 三次握手已完成,Nginx 作为 TLS 客户端(client hello)与后端 TLS 服务端在 HTTP 请求发出之前协商失败。据 Nginx 官方 ngx_http_proxy_module 文档,两条链路的指令、证书、信任库完全不共用,把浏览器侧的证书问题套到 upstream 上是最常见的排查跑偏。

报错长这样,注意 upstream: 字段指向内网地址,说明失败发生在 Nginx 出站方向:

2024/05/12 10:21:33 [error] 8123#0: *1043 SSL_do_handshake() failed
(SSL: error:0A000086:SSL routines::certificate verify failed)
while SSL handshaking to upstream, client: 203.0.113.7, server: example.com,
request: "GET /api/v1/orders HTTP/1.1",
upstream: "https://10.0.3.21:443/api/v1/orders", host: "example.com"

客户端只会看到 502 Bad Gateway,而后端应用日志往往一条请求都没有——TLS 层就断了,HTTP 根本没到业务代码。判断”谁在报错”最快的办法是在 Nginx 主机上以相同身份复现,OpenSSL 文档指出 -verify_return_error 会让证书校验失败直接终止握手,正好等价于 proxy_ssl_verify on 的行为:

# 在 Nginx 主机执行,模拟 Nginx 出站握手(注意 -servername 才是 SNI)
openssl s_client -connect 10.0.3.21:443 
  -servername api.internal.example.com 
  -verify_return_error 
  -CAfile /etc/ssl/certs/ca-certificates.crt </dev/null
# 关键输出:Verify return code: 0 (ok)
# 20 = unable to get local issuer certificate(缺中间证书/私有 CA 未信任)
# 10 = certificate has expired;62 = hostname mismatch(SAN 不含该名字)

很多人第一反应是”校验太严”,其实 Nginx 1.25.3 里几个关键开关的默认值相当宽松,握手失败大多不是校验引起的,而是后端主动发 alert 或协议协商不上:

指令 1.25.3 默认值 作用与踩坑点
proxy_ssl_verify off 默认不校验证书,此时”证书链缺中间证书”不会报错,只有 on 才暴露
proxy_ssl_server_name off 默认不发 SNI,后端若按 SNI 选证书会回 unrecognized_name alert
proxy_ssl_verify_depth 1 链上多一层中间证书即报 unable to get issuer certificate
proxy_ssl_session_reuse on 会话复用导致改配置后仍报旧错,排查时先关掉
proxy_ssl_name $proxy_host 既是 SNI 也是证书名校验对象,proxy_pass 写 IP 时必然 hostname mismatch
location /api/ {
    proxy_pass https://10.0.3.21:443;      # 后端改 HTTPS 后这里必须是 https://
    proxy_ssl_server_name on;              # 默认 off,必须显式打开
    proxy_ssl_name api.internal.example.com;   # 默认 $proxy_host,此处是 IP 会校验失败
    proxy_ssl_verify on;                   # 默认 off
    proxy_ssl_verify_depth 3;              # 默认 1,链较深时不够
    proxy_ssl_trusted_certificate /etc/nginx/trust/private-ca.pem;  # 私有 CA 链
    proxy_ssl_session_reuse off;           # 排查期间临时关闭
}

根因可归为六类,按出现频率排序:后端证书链缺中间证书、证书过期或 SAN 不含 proxy_ssl_name、后端依赖 SNI 而 Nginx 未发、协议版本被后端禁用(例如后端只允许 TLSv1.2/1.3,而 Nginx 链接的 OpenSSL 1.0.2 讲不了 TLS 1.3)、加密套件不匹配、后端要求 mTLS 客户端证书。典型触发场景与之对应:proxy_pass 仍写 http:// 而端口改成 443;K8s Ingress 后端用自签名证书;私有 CA 未导入 Nginx 信任库;Nginx 与后端系统时间偏差超过 300 秒导致 certificate has expired。证书路径校验规则见 RFC 5280,TLS 1.3 握手与 alert 语义见 RFC 8446,Let’s Encrypt 文档也明确强调服务端必须下发完整链(叶子 + 中间证书),这三点是定位 upstream SSL 握手失败最可靠的外部依据。

upstream SSL 握手失败怎么排查?6 步实操流程

问:Nginx 报 upstream SSL 握手失败,第一步该做什么?答:先别改配置,先把错误码从日志里挖出来——SSL_do_handshake() failed 只是结论,括号里的 8 位错误码才是线索。

  1. 第 1 步:定位日志与错误码。Nginx 的 upstream 握手失败一律落在 error.log 的 [error] 级别,用关键词过滤比翻全文件快得多:

    grep -n "SSL_do_handshake|upstream SSL" /var/log/nginx/error.log | tail -50
    # 典型输出(注意括号里的 OpenSSL 错误码):
    # 2024/05/11 10:22:31 [error] 812#812: *107 SSL_do_handshake() failed
    #   (SSL: error:0A000086:SSL routines::certificate verify failed)
    #   while SSL handshaking to upstream, client: 203.0.113.9,
    #   server: example.com, request: "GET /api/v1/orders HTTP/1.1",
    #   upstream: "https://10.0.0.12:443/api/v1/orders"
    

    拿到码后立刻用 OpenSSL 自带的解码器确认含义,别靠猜:

    openssl errstr 0A000086   # → error:0A000086:SSL routines::certificate verify failed
    openssl errstr 0A000410   # → tlsv1 alert unknown ca(后端拒绝了我们的信任链)
    openssl errstr 0A00010B   # → wrong version number(多半是 https:// 打到了明文端口)
    
    错误码 openssl errstr 解读 最常见根因 对应步骤
    0A000086 certificate verify failed 后端只发叶子证书缺中间证书;CA 未写入 proxy_ssl_trusted_certificate;主机名校验不匹配 第 4、5、6 步
    0A000410 tlsv1 alert unknown ca 后端不认可 Nginx 信任的 CA,或后端要求双向 TLS 而 Nginx 未配客户端证书 第 4 步
    0A00010B wrong version number proxy_pass https:// 指向了 HTTP 端口,或协议版本无交集 第 2、3 步
  2. 第 2 步:确认 Nginx 与 OpenSSL 版本。版本决定可用协议与默认值,nginx -V 是唯一可信来源(注意是大写 V,小写只输出简短版本号):

    nginx -V 2>&1 | tr ' ' 'n' | grep -E 'nginx version|built with OpenSSL'
    # nginx version: nginx/1.25.3
    # built with OpenSSL 3.0.11 19 Sep 2023
    

    若显示 OpenSSL 1.0.2,则编译期不支持 TLS 1.3,配置里写 proxy_ssl_protocols TLSv1.3 会直接导致协议协商失败。据 Nginx 官方文档,proxy_ssl_protocols 自 1.23.4 起默认值为 TLSv1.2 TLSv1.3,更早版本默认包含已废弃的 TLSv1/TLSv1.1。

  3. 第 3 步:从 Nginx 所在主机复现握手。绕过 Nginx 直接和后端对话,才能区分是网络问题还是配置问题。-servername 模拟 SNI,-CAfile 模拟 Nginx 的信任库,-verify_return_error 让校验失败时立即中断而非静默继续:

    openssl s_client -connect 10.0.0.12:443 
      -servername api.internal.example.com 
      -CAfile /etc/nginx/ssl/upstream_ca.pem 
      -verify_return_error -tls1_2 </dev/null
    # 关注三行:Protocol : TLSv1.2 / Verify return code: 0 (ok) / 是否出现 alert
    

    再把 -tls1_2 换成 -tls1_3 对比:只在某一个版本下失败,说明前后端协议集不重叠,属于第 2 步的版本问题。

  4. 第 4 步:检查证书链完整性与有效期。后端只配了叶子证书、漏发中间证书,是 upstream 校验失败的头号原因(浏览器能自动补链,Nginx 不会)。导出并逐张核对:

    openssl s_client -connect 10.0.0.12:443 -servername api.internal.example.com 
      -showcerts /dev/null 
      | openssl x509 -noout -dates -subject -issuer -ext subjectAltName
    # notBefore=Apr  1 00:00:00 2024 GMT
    # notAfter=Jun 30 00:00:00 2024 GMT
    # subject=CN = api.internal.example.com
    # X509v3 Subject Alternative Name: DNS:api.internal.example.com
    

    确认 notBefore/notAfter 覆盖当前时间、SAN 含目标域名;若 issuer 不是自签根,说明链没发全,需让后端补上中间证书。

  5. 第 5 步:对齐 SNI 与校验主机名。只写 proxy_pass https://10.0.0.12:443 时,Nginx 默认不发送 SNI(proxy_ssl_server_name 默认 off),且 proxy_ssl_name 默认取 $proxy_host——这里就是那个 IP,于是后端返回默认站点证书,校验必然失败。

  6. 第 6 步:补齐校验配置并 reload。

    location /api/ {
        proxy_pass https://10.0.0.12:443;
        proxy_ssl_server_name on;                     # 默认 off,开启后才发 SNI
        proxy_ssl_name api.internal.example.com;      # 默认 $proxy_host(此处为 IP),必须覆盖
        proxy_ssl_verify on;                          # 默认 off,生产环境应开启
        proxy_ssl_trusted_certificate /etc/nginx/ssl/upstream_ca.pem;
        proxy_ssl_verify_depth 2;                     # 默认 1,链为 叶子+中间+根 时需 ≥2
        proxy_ssl_protocols TLSv1.2 TLSv1.3;
        proxy_ssl_session_reuse on;                   # 默认 on,会话复用可减少重复握手
    }
    
    nginx -t && nginx -s reload
    # 复跑第 3 步,并用 curl 从业务视角验证:
    curl -sv https://example.com/api/v1/orders -o /dev/null 2>&1 | grep -E 'HTTP/|SSL certificate'
    tail -f /var/log/nginx/error.log   # 确认不再出现新的 SSL_do_handshake 报错
    

    若第 6 步后仍报 0A000086,把 proxy_ssl_verify_depth 提到 3 再试;若报 0A000410,则问题在后端信任策略而非 Nginx 一侧,需要后端把上游 CA 加入其 ssl_client_ca 配置。Mozilla 的 SSL Configuration Generator 可作为协议与套件取值的交叉参考。

Nginx 到 upstream 的 TLS 配置怎么写?命令与配置示例

先给一份可以直接落地的配置,适用于 Nginx 1.25.3(mainline,2023-10 发布)。据 nginx 官方文档,proxy_ssl_verify 与 proxy_ssl_server_name 的默认值都是 off,也就是说 Nginx 默认既不校验证书、也不发 SNI——这正是 upstream ssl 握手失败最常见的两个根源。

upstream backend_https {
    server 10.0.0.12:443;
    keepalive 32;                 # 复用后端连接,需配合下面两行 HTTP/1.1 设置
}

server {
    listen 443 ssl;
    server_name www.example.com;

    location /api/ {
        proxy_pass https://backend_https;
        proxy_http_version 1.1;           # keepalive 生效前提
        proxy_set_header Connection "";   # 清空客户端 Connection 头

        proxy_ssl_server_name on;                              # 发送 SNI(RFC 6066)
        proxy_ssl_name api.internal.example.com;               # SNI 与证书校验共用此名
        proxy_ssl_verify on;                                   # 默认 off,必须显式打开
        proxy_ssl_trusted_certificate /etc/nginx/ssl/upstream_ca.pem;  # PEM 格式 CA/中间链
        proxy_ssl_verify_depth 2;                              # 默认 1,链深常需 2
        proxy_ssl_protocols TLSv1.2 TLSv1.3;
        proxy_ssl_ciphers HIGH:!aNULL:!MD5;
        proxy_ssl_session_reuse on;                            # 默认 on
    }
}

为什么 proxy_ssl_name 不能省?proxy_pass 里写的是 IP 10.0.0.12,Nginx 会把它当作 $proxy_host 的默认值,而 RFC 6066 明确禁止用 IP 字面量作 SNI。后端若是按虚拟主机分发证书的网关(Ingress、HAProxy、Envoy),收不到 SNI 就会返回默认证书,于是校验失败。

指令 默认值 取值与说明
proxy_ssl_server_name off on/off,1.7.0+;控制是否发送 SNI
proxy_ssl_name $proxy_host 主机名,同时用于 SNI 与证书 SAN 比对
proxy_ssl_verify off on/off,1.7.0+
proxy_ssl_verify_depth 1 整数;中间 CA 多一级就需 +1
proxy_ssl_protocols TLSv1.2 TLSv1.3(1.23.4 起;此前含 TLSv1/TLSv1.1) 枚举,空格分隔
proxy_ssl_session_reuse on on/off;排查证书轮换问题时可临时 off

后端要求 mTLS 时,在同一 location 追加两行。按 RFC 5280,客户端证书必须带 extendedKeyUsage = clientAuth,且由后端信任的 CA 签发,否则后端会回 tlsv13 alert certificate required:

proxy_ssl_certificate     /etc/nginx/ssl/client.crt;  # 含完整链更稳妥
proxy_ssl_certificate_key /etc/nginx/ssl/client.key;
# 自检 EKU:输出 "SSL client : Yes" 才合规
openssl x509 -in /etc/nginx/ssl/client.crt -noout -purpose

动手改配置前,先用 openssl 独立验证链路,避免把后端问题和 Nginx 问题混在一起:

openssl s_client -connect 10.0.0.12:443 
  -servername api.internal.example.com 
  -CAfile /etc/nginx/ssl/upstream_ca.pem 
  -verify_return_error -state -tlsextdebug </dev/null
# 关注三行:Verify return code: 0 (ok) / Protocol : TLSv1.3 / Server Temp Key: X25519
# 确认主机名在 SAN 而非只在 CN(RFC 6125 已不推荐 CN 匹配)
openssl s_client -connect 10.0.0.12:443 -servername api.internal.example.com 
  /dev/null | openssl x509 -noout -text | grep -A1 "Subject Alternative Name"
# 时钟偏差会让 notBefore/notAfter 校验失败,建议差值 < 300 秒
date -u
openssl x509 -in /etc/nginx/ssl/upstream_ca.pem -noout -dates

日志层面,error_log /var/log/nginx/error.log warn; 已足够暴露问题,典型输出为:

[error] 1234#1234: *56 upstream SSL certificate verify error: (20:unable to get local issuer certificate) while SSL handshaking to upstream, upstream: "https://10.0.0.12:443/api/v1/ping"

错误码 20 指向缺中间证书,18 是自签名证书,10 是证书过期。要看完整握手过程必须 nginx -V 确认编译时带 --with-debug,再临时把级别调到 debug;排查完立即改回 warn,否则高 QPS 下日志会迅速膨胀。

proxy_ssl_* 参数怎么选?默认值与方案对比表

很多人把 upstream ssl握手失败 归咎于”证书不对”,但实际日志里 90% 的报错是参数组合没配齐:开了 proxy_ssl_verify on 却没给 proxy_ssl_trusted_certificate,或者后端是多域名虚拟主机却没开 SNI。这几个 proxy_ssl_* 参数不是独立开关,而是”校验开关 + 信任锚 + 主机名 + 深度 + 协议/套件”五件套,缺一项就会出现握手失败。先看 Nginx 1.25.3 的默认值与生产建议:

参数 默认值(1.25.3) 生产建议 为什么
proxy_ssl_verify off on 是否校验后端证书链。关闭时任何证书(含过期、自签、域名不符)都能握手成功,等于放弃中间人防护。
proxy_ssl_server_name off 后端依赖 SNI 时 on 握手时是否发送 SNI(RFC 6066)。后端若按 SNI 选证书,关闭后可能拿到默认站点证书或直接 alert。
proxy_ssl_name $proxy_host 设为后端证书 SAN 中的域名 同时决定 SNI 值与证书主机名校验目标;$proxy_host 常是 upstream 块名或 IP,SAN 不匹配就报 hostname mismatch。
proxy_ssl_trusted_certificate 未设置 /etc/nginx/ssl/upstream_ca.pem 指定私有 CA 或完整证书链;未设置时依赖系统信任库,自签后端必然校验失败。
proxy_ssl_verify_depth 1 2–3 允许的中间证书层数,链较深(根→中间→中间→叶)时需调大,否则报 unable to get local issuer certificate。
proxy_ssl_protocols 1.23.4 起为 TLSv1.2 TLSv1.3,旧版含 TLSv1/TLSv1.1 显式写 TLSv1.2 TLSv1.3 显式声明可避免与只开 TLSv1.2 的后端协商失败,也防止旧版默认值拖入不安全协议。
proxy_ssl_ciphers HIGH:!aNULL:!MD5 按 Mozilla SSL Configuration Generator 的 intermediate 套件 控制加密套件;后端若只支持特定套件,交集为空会触发 handshake failure。
proxy_ssl_session_reuse on 保持 on 复用 TLS 会话降低握手开销;若怀疑后端会话票据异常导致复用失败,可临时设 off 做对比定位。

下面是一份可直接落地的配置,关键行都有注释,适用于 Nginx 1.25.3(proxy_ssl_* 自 1.7.0 起可用,proxy_ssl_certificate 自 1.7.8 起):

# /etc/nginx/conf.d/api.conf
upstream backend {
    server 10.0.0.21:8443;
    server 10.0.0.22:8443;
}

server {
    listen 443 ssl;
    location /api/ {
        proxy_pass https://backend;                # 协议必须写 https,否则 proxy_ssl_* 全部无效

        proxy_ssl_verify on;                       # 默认 off,生产必须开
        proxy_ssl_trusted_certificate /etc/nginx/ssl/upstream_ca.pem;  # 默认未设置
        proxy_ssl_verify_depth 3;                  # 默认 1,深链需调大

        proxy_ssl_server_name on;                  # 默认 off,发送 SNI
        proxy_ssl_name api.internal.example.com;   # 默认 $proxy_host,须在证书 SAN 内

        proxy_ssl_protocols TLSv1.2 TLSv1.3;       # 1.23.4 起默认即此值,显式写更稳
        proxy_ssl_ciphers HIGH:!aNULL:!MD5;        # 可替换为 Mozilla intermediate 列表

        proxy_ssl_session_reuse on;                # 默认 on
    }
}

开启校验后,若信任锚或深度不对,error.log 会给出非常具体的 OpenSSL 原因,据 OpenSSL 文档的 X509 校验码对照即可定位:

# 典型报错(nginx error.log)
upstream SSL certificate verify error: (20:unable to get local issuer certificate) while SSL handshaking to upstream
upstream SSL certificate verify error: (21:unable to verify the first certificate) while SSL handshaking to upstream
SSL_do_handshake() failed (SSL: error:0A000410:SSL routines::sslv3 alert handshake failure)

20/21 通常是 proxy_ssl_trusted_certificate 缺失或只放了叶证书(应放”中间证书 + 根证书”的完整链);sslv3 alert handshake failure 在 proxy_ssl_verify on 下多为 SNI 未发送或套件无交集。复现时可用 openssl s_client -connect 10.0.0.21:8443 -servername api.internal.example.com -CAfile /etc/nginx/ssl/upstream_ca.pem -verify_return_error 直接验证,若这条命令成功而 Nginx 仍报 upstream ssl握手失败,问题就在 proxy_ssl_name 与证书 SAN 不一致。

最后是方案选型,四条路径的取舍差别很大:

方案 关键配置 适用场景 代价与风险
A 关闭校验 proxy_ssl_verify off 内网临时排障、抓包定位 任何证书都能握手成功,失去中间人防护,不建议长期保留
B 使用系统 CA 只开 proxy_ssl_verify on,不配 trusted_certificate,依赖 /etc/ssl/certs 后端由公网 CA(如 Let’s Encrypt、DigiCert)签发 受宿主机 ca-certificates 包版本影响,容器镜像精简时可能缺失根证书
C 指定私有 CA 文件 proxy_ssl_trusted_certificate 指向内部 CA 或完整链 自签名证书、内部 CA 签发 CA 轮换需同步更新文件并 reload,运维成本转移到这里
D mTLS 双向认证 在 C 基础上加 proxy_ssl_certificate / proxy_ssl_certificate_key 后端要求客户端证书 私钥需严格权限(chmod 600),且后端须校验客户端证书链

据 Let’s Encrypt 文档,其证书链默认包含中间证书,因此方案 B 一般可行;但一旦后端换成内部 CA,就必须切到 C 并同步调大 proxy_ssl_verify_depth。改动后务必 nginx -t && nginx -s reload 验证,proxy_ssl_* 属于握手期参数,配置错误只会在首次连接时暴露。

常见报错有哪些?upstream SSL 握手失败的真实日志与处理

Nginx 的 upstream SSL 报错来自两个不同的层,混在一起看很容易误判:一层是 OpenSSL 的链验证回调,日志形如 upstream SSL certificate verify error: (20:...),括号里的数字是 X509_V_ERR_* 常量值;另一层是 握手状态机,日志形如 SSL_do_handshake() failed (SSL: error:0A000086:...)。据 OpenSSL 3.0 的 openssl/err.h 与 3.0 迁移说明,错误串格式已从 error:14090086:SSL routines:ssl3_get_server_certificate:certificate verify failed 简化为省略函数名的 error:0A000086:SSL routines::certificate verify failed,这正是大量旧排障文章对不上日志的原因。先按下表定位层面,再按根因处理:

日志片段 错误码 / 原因码 常量或对端 alert 失败层面
SSL_do_handshake() failed (SSL: error:0A000086:…unable to get local issuer certificate) 0A000086(旧版 14090086) SSL_R_CERTIFICATE_VERIFY_FAILED 证书链验证
upstream SSL certificate verify error: (20:unable to get local issuer certificate) 20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY 证书链验证
upstream SSL certificate verify error: (10:certificate has expired) 10 X509_V_ERR_CERT_HAS_EXPIRED 证书链验证
SSL_do_handshake() failed (SSL: error:0A000410:…sslv3 alert handshake failure) 0A000410 对端 alert 40 handshake_failure 协商(协议/套件/客户端证书)
SSL_do_handshake() failed (SSL: error:0A00010B:…wrong version number) 0A00010B 对端 alert 70 protocol_version 协议识别
SSL_do_handshake() failed (SSL: error:0A000172:…tlsv1 alert unknown ca) 0A000172 对端 alert 48 unknown_ca mTLS 客户端认证

“unable to get local issuer certificate”怎么修?它表示 Nginx 手里的信任文件里找不到签发后端叶证书的那张中间 CA。两个成因:后端 ssl_certificate 只配了叶证书没配 fullchain(据 Let’s Encrypt 文档,其证书由 ISRG Root X1 经 R3/E1 中间证书签发,服务端必须主动发送中间证书,否则任何严格校验的客户端都会失败);或 Nginx 侧 proxy_ssl_trusted_certificate 只放了根 CA 而链不完整。修法是把后端实际下发的链导出并合并进信任文件:

# 1) 带 SNI 连后端,导出服务器下发的完整链(叶 + 中间)
openssl s_client -connect 10.0.0.12:8443 -servername api.internal.example.com 
  -showcerts </dev/null 2>/dev/null | awk '/BEGIN CERT/,/END CERT/{print}' 
  > /etc/nginx/ssl/upstream_chain.pem

# 2) 合并进信任文件(proxy_ssl_trusted_certificate 支持一个文件放多张证书,Nginx 1.11.8+)
cat /etc/nginx/ssl/upstream_chain.pem >> /etc/nginx/ssl/upstream_ca.pem

# 3) 核对张数:应 ≥ 2(叶证书 + 中间 CA),只有 1 张说明链仍不完整
grep -c "BEGIN CERTIFICATE" /etc/nginx/ssl/upstream_ca.pem

nginx -t && nginx -s reload

对应配置项如下,四个默认值必须同时正确,缺一个就会重演 upstream ssl 握手失败:

location /api/ {
    proxy_pass https://backend_pool;
    proxy_ssl_verify on;                      # 默认 off;不开则不做链验证,问题被掩盖
    proxy_ssl_trusted_certificate /etc/nginx/ssl/upstream_ca.pem;
    proxy_ssl_verify_depth 2;                 # 默认 1;叶证书+中间 CA 恰好需要 2
    proxy_ssl_server_name on;                 # 默认 off;不开则不发送 SNI
    proxy_ssl_name api.internal.example.com;  # 默认 $proxy_host,即 proxy_pass 里的主机名
}

为什么 proxy_ssl_verify_depth 2 是关键?该参数默认值为 1,表示最多校验一层中间证书;当后端链为“叶证书 → 中间 CA → 根 CA”时,深度不足会直接报 verify error: (20:...)。改完务必先 nginx -t 再 reload,因为 reload 失败时旧 worker 仍在跑,容易误判为“改了没用”。另外 SNI 在 RFC 6066 §3 定义,proxy_ssl_server_name 关闭时后端会返回默认虚拟主机的证书,链自然对不上。

报 sslv3 alert handshake failure 怎么办?先二分协议版本,再比对套件,别急着改配置:

# 分别测 TLS 1.2 与 TLS 1.3,看哪个版本能握上手
openssl s_client -connect 10.0.0.12:8443 -servername api.internal.example.com -tls1_2 </dev/null
openssl s_client -connect 10.0.0.12:8443 -servername api.internal.example.com -tls1_3 </dev/null

# 查看实际协商出的协议与套件
openssl s_client -connect 10.0.0.12:8443 -servername api.internal.example.com </dev/null 2>/dev/null 
  | grep -E "Protocol|Cipher"

若 TLS 1.3 通、1.2 不通,通常是 proxy_ssl_ciphers(默认值 DEFAULT)与后端 ssl_ciphers 无交集,或后端只启用 TLS 1.3;此时显式对齐 proxy_ssl_protocols(默认 TLSv1 TLSv1.1 TLSv1.2,建议按后端实际能力写死为 TLSv1.2 TLSv1.3)并统一套件串。若两个版本都报 handshake failure,则多半是后端启用了 mTLS 而 Nginx 未配 proxy_ssl_certificate。

wrong version number 几乎只有一种可能:协议写错了。proxy_pass https:// 指向的端口实际跑着明文 HTTP,或端口抄错。用 curl -v http://10.0.0.12:8443/ 看到 HTTP/1.1 200 就证明后端是 HTTP,把 scheme 改回 http:// 即可;反之若 curl -v https:// 也报 wrong version number,说明该端口不是 TLS。

certificate has expired 与 unknown ca 两个尾部问题:前者查有效期,注意要同时看信任文件与后端实时下发的叶证书:

openssl x509 -in /etc/nginx/ssl/upstream_ca.pem -noout -subject -dates
openssl s_client -connect 10.0.0.12:8443 -servername api.internal.example.com </dev/null 2>/dev/null 
  | openssl x509 -noout -subject -dates

后者出现在 mTLS 场景:0A000172 tlsv1 alert unknown ca 是后端发出的 alert,表示它不认 Nginx 出示的客户端证书。检查 proxy_ssl_certificate 指向的文件是否含中间证书(grep -c "BEGIN CERTIFICATE" /etc/nginx/ssl/client.crt 应为 2),以及后端信任库是否已导入签发该客户端证书的 CA。这三类报错的共性是:日志只告诉你“失败在验证”,真正答案永远在后端实际下发的那条链里,openssl s_client -showcerts 是唯一可靠的取证手段。

配置改完怎么验证?确认 upstream TLS 生效的 5 个检查

改完 proxy_ssl_* 参数后,最容易踩的坑不是配置写错,而是”以为生效了、其实没生效”。下面 5 个检查按成本从低到高排列,建议每次变更后全部跑一遍——尤其是排查 upstream ssl 握手失败 时,前三步就能排除掉八成的误判。

1. nginx -t 输出 ok,就说明 upstream TLS 配置生效了吗?

不够。nginx -t 只做语法与文件存在性检查,不校验证书内容、不建立连接。必须再 reload 并用 nginx -T(nginx 1.9.0+ 引入,打印含 include 展开后的完整生效配置)确认参数真的被加载。据 nginx.org 文档,proxy_ssl_verify 与 proxy_ssl_server_name 默认值都是 off,proxy_ssl_name 默认取 proxy_pass 中的主机名——很多人以为 upstream 会自动带 SNI,其实不会。

# 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) 平滑重载(等价于 kill -HUP)
nginx -s reload

# 3) 确认参数已进入运行时配置,行号便于回溯到具体文件
nginx -T | grep -n "proxy_ssl_"
# 12:    proxy_ssl_server_name on;
# 13:    proxy_ssl_name api.internal.example.com;
# 14:    proxy_ssl_verify on;
# 15:    proxy_ssl_trusted_certificate /etc/nginx/ssl/upstream_ca.pem;

2. 怎么从 Nginx 主机发一次真正的端到端请求?

用 --resolve 绕过 DNS,强制走内部地址,避免验证的是公网入口而非 upstream。

curl -v --resolve api.internal.example.com:443:10.0.0.12 
  https://api.internal.example.com/health
# * Server certificate:
# *  SSL certificate verify ok.        <-- 证书链校验通过
# < HTTP/1.1 200 OK                    <-- 应用层也通

# 若仍是 502,立刻看新的握手报错
tail -n 20 /var/log/nginx/error.log | grep -i "SSL_do_handshake"
# SSL_do_handshake() failed (SSL: error:0A000086:SSL routines::certificate verify failed:
#   unable to get local issuer certificate) while SSL handshaking to upstream

注意这条 curl 用的是系统 CA 库,而 Nginx 用的是 proxy_ssl_trusted_certificate 指定的文件,两者不是一回事,所以第 3 步不能省。

3. 怎么用 OpenSSL 严格验证上游证书链与协议版本?

-verify_return_error 让校验失败时直接终止握手(OpenSSL 1.1.0+),而不是像默认行为那样”握手成功但打印错误码”,这是能否复现 Nginx 行为的关键。

openssl s_client -connect 10.0.0.12:443 
  -servername api.internal.example.com 
  -CAfile /etc/nginx/ssl/upstream_ca.pem 
  -verify_return_error -verify_hostname api.internal.example.com 
  </dev/null
# Verify return code: 0 (ok)      <-- 必须为 0,21/20 分别代表中间证书缺失/根不受信
# Protocol  : TLSv1.3             <-- 或 TLSv1.2,取决于 proxy_ssl_protocols 配置
参数 作用 默认值 / 取值 版本要求
-servername 在 Client Hello 中携带 SNI 扩展(RFC 6066) 不指定则完全不发 SNI OpenSSL 1.0.0+
-CAfile 指定信任锚文件,应与 Nginx 的 trusted_certificate 一致 不指定则不做链校验 全版本
-verify_return_error 校验失败立即中断握手 默认关闭(仅打印错误码) 1.1.0+
-verify_hostname 额外校验证书 SAN 中的主机名 默认不校验主机名 1.0.2+

4. 怎么确认 SNI 真的发出去了?

上游是共享 IP 的多租户网关时,SNI 缺失会返回默认站点的证书,表现就是”证书链没问题但主机名对不上”。抓包是最直接的证据:

# 窗口 A:抓包(-i any 兼容多网卡,-nn 不做名称解析)
tcpdump -i any -nn port 443 -w /tmp/upstream.pcap

# 窗口 B:触发一次请求
curl -s -o /dev/null --resolve api.internal.example.com:443:10.0.0.12 
  https://api.internal.example.com/health

# Wireshark 过滤器,查看 Client Hello 里的扩展值
# tls.handshake.extensions_server_name == "api.internal.example.com"

5. 怎么观察日志与连接状态,并排除”配了但没生效”?

先看 1–5 分钟内有没有新增失败记录,同时确认 TCP 层真的建立了连接:

tail -f /var/log/nginx/error.log | grep -E "SSL_do_handshake|upstream SSL"
ss -tnp | grep 10.0.0.12:443
# ESTAB 0 0 10.0.0.5:51234 10.0.0.12:443 users:(("nginx",pid=1234,fd=21))

最后做一次反向验证:故意指向错误 CA,预期必须失败;若依然 200,说明校验根本没生效。

# 制造故障:换成一个不相关的 CA 文件
sed -i 's#upstream_ca.pem#wrong_ca.pem#' /etc/nginx/conf.d/api.conf
nginx -t && nginx -s reload
curl -s -o /dev/null -w '%{http_code}n' --resolve api.internal.example.com:443:10.0.0.12 
  https://api.internal.example.com/health
# 502  <-- 符合预期,说明 proxy_ssl_verify on 确实在起作用

# 恢复正确文件并再次 reload,避免把故障配置留在线上
sed -i 's#wrong_ca.pem#upstream_ca.pem#' /etc/nginx/conf.d/api.conf
nginx -t && nginx -s reload

这套流程同样适用于排查证书过期、TLS 版本协商失败(如上游只允许 TLSv1.2 而 proxy_ssl_protocols 仍含 TLSv1.3)等问题;Mozilla Server Side TLS 指南给出的协议与套件基线,可以作为 proxy_ssl_ciphers 的取值参考。

如何预防再次出现?证书轮换、SNI 与监控基线

预防 upstream SSL 握手失败,核心是把三件容易”漂移”的东西固定成基线:证书生命周期、Nginx 本地信任库、以及可观测性。据 Let’s Encrypt 官方文档,其证书有效期为 90 天,官方建议在剩余 30 天时完成续签(renewal),并用 certbot renew --dry-run 验证钩子可用。后端证书一旦更新,Nginx 侧的 proxy_ssl_trusted_certificate 指向的 CA 文件若不跟着换,下一次握手仍会抛出 unable to get local issuer certificate(verify error:num=20),因为 Nginx 只在启动/reload 时读取该文件,运行期不会自动重载。

# 1) 续签后端证书(certbot 默认剩余 30 天内才实际续签)
certbot renew --deploy-hook "systemctl reload nginx-backend"

# 2) 同步更新 Nginx 侧的信任锚文件(关键:必须是 CA 链,不是叶子证书)
cp /etc/letsencrypt/live/api.example.com/chain.pem /etc/nginx/ssl/upstream_ca.pem
chmod 644 /etc/nginx/ssl/upstream_ca.pem

# 3) 先语法检查,再灰度 reload(Nginx 1.16+ 支持 -s reload 平滑生效)
nginx -t && nginx -s reload
# 回滚:保留上一版 /etc/nginx/ssl/upstream_ca.pem.bak,1 分钟内 cp 回去再 reload

监控基线用黑盒探测最直接,每 5 分钟一次,等价于模拟 Nginx 的校验行为(-servername 触发 SNI,-CAfile 与 proxy_ssl_trusted_certificate 保持一致,-verify_return_error 让校验失败直接非零退出):

openssl s_client -connect 10.0.0.21:443 -servername api.example.com 
  -CAfile /etc/nginx/ssl/upstream_ca.pem -verify_return_error </dev/null
# 输出 Verify return code: 0 (ok) 才算通过;非 0 即触发告警

若已有 Prometheus,blackbox_exporter 的 probe_ssl_earliest_cert_expiry 指标(单位:Unix 时间戳秒)更适合做趋势告警,配 rate/减法即可算剩余天数:

# blackbox.yml 片段
modules:
  https_upstream:
    prober: https
    tls_config:
      ca_file: /etc/nginx/ssl/upstream_ca.pem
      server_name: api.example.com
# 告警规则:剩余天数 < 30 触发
# (probe_ssl_earliest_cert_expiry - time()) / 86400 < 30

配置基线方面,生产环境应保持 proxy_ssl_verify on、proxy_ssl_protocols TLSv1.2 TLSv1.3(Nginx 默认值为 TLSv1 TLSv1.1 TLSv1.2,需显式覆盖以禁用弱协议),proxy_ssl_ciphers 直接取 Mozilla SSL Configuration Generator 的 intermediate 套件列表,避免与后端交集为空导致 SSL_do_handshake() failed (SSL: error:...:no shared cipher)。SNI 与 Host 必须分离考虑:proxy_ssl_server_name on 与 proxy_ssl_name 要成对出现,且 proxy_ssl_name 必须与后端证书 SAN 完全一致;upstream 写成 IP 时不要用默认的 $proxy_host,否则 SNI 发出去的是 IP 字面量,后端返回默认站点证书,校验必然失败。

参数 Nginx 默认值 生产建议值 失败时的典型现象
proxy_ssl_verify off on 关闭时握手”成功”但中间人不可见,风险隐蔽
proxy_ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.2 TLSv1.3 协议交集为空 → no protocols available
proxy_ssl_server_name off on(多域名共用 IP 时必开) 取到默认站点证书 → hostname mismatch
proxy_ssl_name $proxy_host 后端证书 SAN 中的具体域名 IP 场景下 SNI 为 IP,校验失败
proxy_ssl_trusted_certificate 无 后端 CA 链文件路径 unable to get local issuer certificate

变更流程上,任何 upstream TLS 参数调整都应遵循”nginx -t → 灰度 reload → 观察 error.log”的顺序,并保留上一版配置与证书文件的 .bak 副本,确保握手失败时能在 1 分钟内回滚。复盘时直接抓 error.log 中的错误码(如 num=20 缺中间证书、num=62 主机名不匹配、num=10 证书过期),比逐条试配置快得多。这部分细节可对照 OpenSSL verify 手册页与 RFC 6125 的主机名验证规则逐项核对。

不一定。证书过期只是原因之一,SNI 未发送、协议版本不匹配、加密套件无交集、mTLS 客户端证书缺失、系统时间偏差超过 300 秒都会导致同样的 SSL_do_handshake() failed。先看 error.log 的错误码,再用 openssl s_client -servername 域名 -verify_return_error 复现,才能区分是证书校验失败还是协议协商失败。

据 Nginx 1.25.3 官方文档,proxy_ssl_verify 默认是 off,proxy_ssl_server_name 默认也是 off。默认关闭只代表 Nginx 不校验证书链,不代表后端一定接受握手;如果后端只允许 TLSv1.2、要求 SNI 或要求客户端证书,Nginx 仍会在握手阶段收到 alert 并记录 SSL_do_handshake() failed。

在 location 中配置 proxy_ssl_server_name on,并设置 proxy_ssl_name api.internal.example.com;proxy_ssl_name 默认是 $proxy_host,当 proxy_pass 写的是 IP 时不会自动变成证书域名。配置后用 tcpdump 抓包过滤 tls.handshake.extensions_server_name,确认 Client Hello 中的 SNI 与后端证书 SAN 一致。

这个报错表示 Nginx 找不到后端证书的签发者。先执行 openssl s_client -connect 后端:443 -servername 域名 -showcerts 导出叶子证书和中间证书,把中间证书追加到 /etc/nginx/ssl/upstream_ca.pem,再设置 proxy_ssl_trusted_certificate 指向该文件、proxy_ssl_verify_depth 2,最后 nginx -t && nginx -s reload。验证标准是 openssl s_client 返回 Verify return code: 0 (ok)。

Nginx 用 proxy_ssl_verify on、proxy_ssl_trusted_certificate、proxy_ssl_name 控制后端校验;HAProxy 则在 backend 的 server 行使用 ssl verify required、ssl ca-file、ssl sni str(域名)。两者都支持 mTLS,但 Nginx 的 proxy_ssl_verify 默认 off,HAProxy 的 verify 需要显式写 required 或 none,排查时不要直接套用另一侧的默认值。

不建议直接关闭校验。更稳妥的做法是把自签名证书的 CA 证书放入 /etc/nginx/ssl/upstream_ca.pem,配置 proxy_ssl_verify on 和 proxy_ssl_trusted_certificate 指向它,同时用 proxy_ssl_name 指定证书 SAN 中的域名。只有临时排障才考虑 proxy_ssl_verify off,并应记录恢复时间。

在 Nginx 主机上直接执行 openssl s_client -connect 后端IP:443 -servername 后端域名 -CAfile 信任文件 -verify_return_error;如果这里就失败,说明问题在 Nginx 到 upstream 链路。再用 curl -v –resolve 域名:443:后端IP https://域名/health 验证应用层,若 OpenSSL 成功而 curl 失败,继续看 HTTP Host、后端虚拟主机和证书 SAN 配置。


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

内容审核

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