1. 问题全景一次典型的SSL握手失败排查最近在线上环境处理一个Nginx反向代理的故障报错信息非常经典peer closed connection in SSL handshake while SSL handshaking to upstream。这个错误直接翻译过来就是“对端在SSL握手期间关闭了连接”它发生在Nginx作为反向代理试图与上游Upstream服务器比如一个Java应用、一个Go服务或者另一个Nginx建立HTTPS连接的时候。表面上看是上游服务器“不搭理”了但背后的原因可能五花八门从证书问题、协议不匹配到网络抖动甚至是上游服务本身的Bug。对于运维和开发来说遇到这种问题最头疼的地方在于它不像404或502那样指向明确。SSL/TLS握手是一个复杂的、多步骤的加密协议协商过程任何一步出问题都可能导致连接被对端直接关闭而Nginx通常只会给你一个相对笼统的错误日志。这就需要我们像侦探一样从有限的线索日志、配置、版本信息出发系统地排查所有可能性。这篇文章我就结合自己多次踩坑和解决的经验把排查这个问题的完整思路、工具和实操步骤梳理出来希望能帮你快速定位问题根源。2. 核心原理SSL/TLS握手与Nginx代理的角色要解决问题必须先理解问题发生的上下文。当Nginx配置了proxy_pass指向一个HTTPS地址例如proxy_pass https://backend-server;并且使用了proxy_ssl_*系列指令时它就扮演了一个TLS客户端的角色。2.1 TLS握手流程简述一次完整的TLS 1.2握手最常见大致包含以下核心步骤ClientHello Nginx客户端发送一个消息给上游服务器里面包含了它支持的TLS版本如TLSv1.2、支持的密码套件列表Cipher Suites、以及一个随机数。ServerHello 上游服务器回应从中选出一个双方都支持的TLS版本和密码套件并发送自己的随机数。证书传递与验证 服务器发送其SSL证书链。Nginx作为客户端会验证这个证书是否由可信CA签发、是否在有效期内、证书中的域名是否与连接的目标地址匹配取决于proxy_ssl_verify配置。密钥交换 双方根据之前的随机数和交换的信息生成用于后续通信的对称加密密钥。握手完成 交换完成消息加密通道建立成功。peer closed connection in SSL handshake这个错误就发生在上述第1步到第4步之间的任意环节。上游服务器因为不满意Nginx客户端发来的信息或者自身无法满足协商要求直接断开了TCP连接。2.2 Nginx相关配置指令解析Nginx作为TLS客户端其行为由几个关键的proxy_ssl_*指令控制proxy_ssl_verify on | off; 是否验证上游服务器的证书。如果设为on且证书验证失败如自签名证书未受信握手会失败。这是最常见的原因之一。proxy_ssl_trusted_certificate /path/to/ca.crt; 指定用于验证上游服务器证书的受信CA证书包。当上游使用自签名或私有CA签发的证书时必须正确配置此指令。proxy_ssl_verify_depth number; 证书链验证深度。proxy_ssl_protocols [TLSv1 TLSv1.1 TLSv1.2 TLSv1.3]; 指定Nginx向上游发起握手时使用的TLS协议版本。如果上游服务器只支持TLSv1.3而Nginx配置只允许TLSv1.2那么握手就会失败。proxy_ssl_ciphers HIGH:!aNULL:!MD5; 指定Nginx支持的密码套件。必须与上游服务器支持的套件有交集。proxy_ssl_server_name on | off; 是否在TLS握手时启用SNIServer Name Indication扩展。如果上游服务器是虚拟主机一个IP托管了多个HTTPS服务必须将此指令设为on并在proxy_pass中使用域名否则上游服务器可能不知道返回哪个证书而导致握手失败。proxy_ssl_name $proxy_host; 指定SNI中发送的服务器名称默认是proxy_pass指令中的主机名。有时需要手动指定。理解这些指令是排查问题的基石。错误往往就隐藏在某个配置的疏忽或不匹配中。3. 系统性排查流程与实操步骤当看到错误日志后不要盲目修改配置。遵循一个从易到难、从外到内的排查路径可以极大提升效率。3.1 第一阶段基础检查与日志收集1. 确认Nginx配置与日志级别首先找到你的Nginx反向代理配置片段。确保错误日志级别至少为error默认级别为了获得更详细的SSL调试信息可以临时将其提升为info甚至debug。在http或server块中修改error_log /var/log/nginx/error.log debug;注意debug日志会产生大量输出仅建议在排查问题时临时开启并在问题解决后调回error级别。2. 检查网络连通性与端口确认Nginx服务器能通过网络访问到上游服务器的HTTPS端口默认443。使用telnet或nc进行最基础的TCP连接测试nc -zv upstream-server-ip 443如果TCP连接都无法建立那问题就是网络或防火墙层面的与SSL无关。需要检查安全组、iptables/防火墙规则以及上游服务是否在监听。3. 从上游服务器视角检查这是关键一步。登录到上游服务器查看其应用日志。例如如果是Java应用如Spring Boot使用Tomcat查看catalina.out或应用日志文件看是否有关于SSL握手失败的记录如“unsupported protocol”、“handshake_failure”等这些信息比Nginx的日志更具指向性。 同时确认上游服务本身是健康的能够处理其他正常的直接HTTPS请求。3.2 第二阶段SSL/TLS协议与证书问题深度排查如果基础网络和端口是通的那么问题大概率集中在SSL/TLS协议本身。1. 使用OpenSSL模拟Nginx客户端进行诊断这是最强大的命令行工具。我们可以用s_client命令来模拟Nginx向上游服务器发起一次TLS握手并输出详细过程。openssl s_client -connect upstream-server-domain-or-ip:443 -servername upstream-server-domain -tlsextdebug -state -showcerts-servername 指定SNI如果上游是虚拟主机这个参数至关重要必须与proxy_ssl_name或实际访问的域名一致。-tlsextdebug -state 打印握手过程中的状态信息。-showcerts 显示服务器返回的完整证书链。如何分析输出连接建立 看开头是否成功建立TCP连接。证书验证 输出末尾会有一行“Verify return code:”。如果代码不是0 (ok)就说明证书验证失败。常见错误码如20 (unable to get local issuer certificate)意味着找不到签发证书的CA。握手完成 如果命令没有立即退出而是停留在一个空白行等待输入说明TLS握手成功了。你可以输入一些HTTP命令如GET / HTTP/1.0测试。如果命令立即退出并报错说明握手失败错误信息会直接显示出来比如sslv3 alert handshake failure。2. 针对性测试协议与密码套件如果s_client默认连接失败可以分别测试不同协议版本以确定是否是协议不匹配。# 测试TLSv1.2 openssl s_client -connect backend:443 -tls1_2 -servername backend.example.com # 测试TLSv1.3 openssl s_client -connect backend:443 -tls1_3 -servername backend.example.com同样可以测试特定的密码套件但通常协议匹配是首要问题。3. 核对Nginx与上游的SSL配置匹配度根据OpenSSL测试结果回头检查Nginx配置协议匹配 确保proxy_ssl_protocols包含上游服务器支持的版本。现代服务建议至少包含TLSv1.2 TLSv1.3。证书验证如果上游是自签名证书必须将proxy_ssl_verify设为off或者将上游服务器的证书或私有CA证书添加到proxy_ssl_trusted_certificate指定的文件中并保持proxy_ssl_verify on。proxy_ssl_trusted_certificate文件通常需要包含完整的证书链从服务端证书的签发CA直到根CA而不仅仅是根证书。可以使用cat root-ca.crt intermediate-ca.crt trusted_ca.crt来创建。SNI配置 如果上游服务器一个IP对应多个域名证书虚拟主机必须设置proxy_ssl_server_name on;。并且proxy_pass指令中最好使用域名而非IP因为SNI信息默认来自$proxy_host变量即proxy_pass中的主机部分。3.3 第三阶段高级问题与边缘情况排查如果上述步骤都没问题那可能遇到了一些更隐蔽的情况。1. 上游服务器对客户端的限制有些上游服务如某些CDN后端、严格的API网关可能会对TLS客户端的某些特征进行限制例如不支持的密码套件 即使协议匹配但Nginx提供的密码套件列表proxy_ssl_ciphers中没有一个被上游接受。尝试使用更通用或与上游匹配的密码套件。一个相对安全且兼容性较好的配置是proxy_ssl_ciphers HIGH:!aNULL:!MD5:!RC4;。客户端证书要求 极少数情况下上游服务要求双向TLS认证mTLS即不仅客户端验证服务器服务器也要验证客户端。这需要Nginx配置proxy_ssl_certificate和proxy_ssl_certificate_key来提供客户端证书。如果你的场景不需要mTLS那这就是上游配置错误。ALPN协议 上游是HTTP/2服务且要求客户端在TLS握手时通过ALPN扩展声明支持h2。Nginx作为反向代理客户端时默认可能不支持或不声明对上游的ALPN。这个问题较为复杂可能需要确保Nginx编译时包含了ngx_http_v2_module并在与上游连接时使用合适的配置。2. Nginx与上游之间的超时设置SSL握手过程可能因为网络延迟或上游服务器繁忙而变慢。如果超时时间设置过短Nginx可能会在握手完成前就放弃并报错。相关的指令是proxy_connect_timeout它定义了与上游服务器建立连接的超时时间这个时间包含了TCP连接和SSL握手的时间。默认是60秒通常足够。但在网络极差或上游服务器负载极高时可以适当调大。proxy_connect_timeout 75s;3. 系统资源与第三方模块影响系统熵Entropy不足 在虚拟化环境或某些低配服务器上系统用于生成随机数的熵池可能耗尽导致SSL握手时生成随机数缓慢或失败。可以检查/proc/sys/kernel/random/entropy_avail如果值很低如小于1000可以考虑安装haveged等服务来补充熵。Nginx第三方模块冲突 如果你安装了非标准的第三方模块特别是与SSL相关的可能存在兼容性问题。尝试在一个纯净的、只包含核心模块和标准SSL模块的Nginx环境中测试。4. 常见错误场景与解决方案速查表为了方便快速对照我将常见原因、现象和解决方案整理成下表问题类别典型现象/线索排查命令/位置解决方案证书验证失败OpenSSLs_client返回非零Verify code。Nginx错误日志可能伴随certificate verify failed。openssl s_client -showcerts ...查看末尾验证码。检查Nginx配置proxy_ssl_verify和proxy_ssl_trusted_certificate。1. 自签名/私有证书将CA证书添加到trusted_ca.crt文件并正确配置proxy_ssl_trusted_certificate。2. 证书过期/域名不匹配联系上游服务管理员更新证书。TLS协议不匹配OpenSSLs_client指定某个协议版本能连上另一个不能。上游应用日志可能提示协议版本不支持。openssl s_client -tls1_2 ...和-tls1_3 ...分别测试。核对上游服务支持的协议。调整Nginx的proxy_ssl_protocols指令包含上游支持的协议如TLSv1.2 TLSv1.3;。SNI未启用或错误上游是虚拟主机使用IP直接访问可能成功但通过Nginx代理失败。OpenSSL测试不带-servername失败带上则成功。openssl s_client -servername correct-domain ...1. 确保proxy_ssl_server_name on;。2. 确保proxy_pass中使用域名。3. 必要时用proxy_ssl_name显式指定SNI值。密码套件不兼容相对少见。OpenSSL测试可能显示握手失败且无更具体错误。上游日志可能有密码套件相关错误。查看上游服务器支持的密码套件列表与Nginxproxy_ssl_ciphers对比。修改Nginx的proxy_ssl_ciphers为一个更通用、与上游有交集的集合例如ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!aNULL:!MD5:!RC4;。网络/连接问题nc -zv测试TCP连接失败。或OpenSSL连接在非SSL阶段就失败。nc -zv upstream_ip 443,telnet upstream_ip 443,traceroute。检查防火墙、安全组、路由、上游服务监听状态。上游服务问题Nginx报错但直接访问上游服务也失败。上游服务日志有明确错误如端口占用、崩溃。查看上游服务的应用日志、系统日志journalctl -u service-name。重启上游服务检查上游服务配置、资源占用内存、CPU、端口冲突等。5. 实战案例一个自签名证书引发的“血案”让我分享一个最近处理的真实案例。开发环境的一个服务backend-app:8443使用了自签名证书。Nginx配置起初是这样的location /api/ { proxy_pass https://backend-app:8443; proxy_ssl_verify on; # 默认就是on但这里显式写了 }错误日志不断出现peer closed connection in SSL handshake。排查过程nc -zv backend-app 8443通过TCP连接正常。用OpenSSL测试openssl s_client -connect backend-app:8443 -showcerts。输出末尾显示Verify return code: 18 (self signed certificate)。确认是证书验证失败。检查Nginx配置发现proxy_ssl_verify是on但没有配置proxy_ssl_trusted_certificate。解决方案有两种选择方案A不推荐用于生产 关闭证书验证。在开发环境可以接受。proxy_ssl_verify off;方案B更规范 将自签名证书加入Nginx的受信列表。从上游服务获取其自签名证书例如通过openssl s_client -connect ... -showcerts命令输出的-----BEGIN CERTIFICATE-----到-----END CERTIFICATE-----部分保存为backend-app.crt。在Nginx配置中指定该证书为受信证书。proxy_ssl_trusted_certificate /etc/nginx/conf.d/trusted/backend-app.crt; proxy_ssl_verify on; proxy_ssl_verify_depth 2;采用方案B后错误消失代理功能恢复正常。这个案例的核心教训是当proxy_ssl_verify启用时Nginx必须能够验证上游证书的合法性要么是公共CA签发要么通过proxy_ssl_trusted_certificate指定私有CA或证书。6. 配置模板与预防建议最后给出一份相对健壮的反向代理HTTPS上游的Nginx配置模板适用于常见场景server { listen 443 ssl http2; server_name proxy.example.com; # 自身对外的SSL证书 ssl_certificate /path/to/your/fullchain.pem; ssl_certificate_key /path/to/your/privkey.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:...; ssl_prefer_server_ciphers off; location /upstream-path/ { # 上游HTTPS服务地址建议使用域名以支持SNI proxy_pass https://upstream.backend.com:8443/some-context/; # 重要的代理SSL配置 proxy_ssl_verify on; # 生产环境建议开启验证 proxy_ssl_trusted_certificate /etc/nginx/ssl/trusted_ca_bundle.crt; # 包含上游CA的证书包 proxy_ssl_verify_depth 2; proxy_ssl_protocols TLSv1.2 TLSv1.3; # 与上游协商的协议 proxy_ssl_ciphers HIGH:!aNULL:!MD5:!RC4; # 兼容的密码套件 proxy_ssl_server_name on; # 如果上游是虚拟主机必须开启 # proxy_ssl_name $host; # 默认使用$proxy_host通常无需更改 # 其他代理设置 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_connect_timeout 75s; proxy_send_timeout 3600s; proxy_read_timeout 3600s; } }预防性建议明确上游SSL要求 在配置前向上游服务提供方确认其TLS协议版本、支持的密码套件以及证书类型公共CA/私有CA/自签名。先测试后配置 在将配置应用到生产Nginx之前务必使用openssl s_client命令模拟连接确保从Nginx服务器网络位置可以成功完成TLS握手。区分环境 开发、测试、生产环境的上游证书可能不同。在开发环境可以临时使用proxy_ssl_verify off但生产环境务必配置正确的证书验证。集中管理证书 将所有需要信任的私有CA或自签名证书维护在一个或几个受信证书包文件中通过proxy_ssl_trusted_certificate引用便于管理。监控与告警 对Nginx的错误日志特别是SSL相关错误进行监控。如果peer closed connection in SSL handshake错误突然增多可能是上游证书即将过期、上游服务SSL配置变更或网络出现问题的信号。排查peer closed connection in SSL handshake的过程本质上是对TLS协议、证书体系和网络通信的一次综合检验。掌握OpenSSLs_client这个利器理解Nginxproxy_ssl_*指令的含义并按照从网络到协议、从证书到配置的层次化思路进行排查大部分问题都能迎刃而解。