ssl_do_handshake()失败本质是nginx作为https客户端连接上游服务时tls握手中断，常见原因包括sni未启用、协议错配（proxy_pass协议与后端实际协议不符）、会话重用不兼容及tls 1.3密钥交换参数不匹配。
SSL_do_handshake() 失败本质是 Nginx 与上游（upstream）服务建立 TLS 连接时中断，不是客户端访问你 Nginx 的问题，而是 Nginx 自己作为 HTTPS 客户端去连后端服务时“握手失败”。错误日志里明确带 to upstream 或 while SSL handshaking to upstream 就是这个场景。
看准错误日志里的关键线索
先别急着改配置，打开 error.log 精准定位：
- error:14094410 … sslv3 alert handshake failure：大概率是 SNI（Server Name Indication）没传，后端多域名 HTTPS 服务无法选对证书
-
error:1408F10B … wrong version number：Nginx 配置了
proxy_pass https://…，但后端实际只监听 HTTP（比如 8081 端口跑的是 Spring Boot 默认 HTTP），协议错配 -
error:14094085 … ccs received early：SSL 会话重用（
proxy_ssl_session_reuse on）与某些后端 TLS 实现不兼容，尤其在复用连接时触发 - error:141CF06C … bad key share：TLS 1.3 密钥交换参数不匹配，常见于 Nginx 版本较新、后端 OpenSSL 或 Java 版本老旧（如 JDK 8u2XX 以下）
检查 proxy_pass 协议是否真实匹配
这是最常被忽略的低级但致命错误。确认你写的 proxy_pass 地址和后端实际暴露的协议一致：
- 如果后端是
http://127.0.0.1:8080（无 TLS），proxy_pass必须写成http://...；写成https://...就会强制走 TLS 握手，而对方根本不会响应，直接报wrong version number - 如果后端确实是 HTTPS（例如自签证书的 API 服务），确保它监听的是 443 或对应端口，并能被 Nginx 正常访问：
curl -vk https://backend-host:port/health - 避免用
https://ip:port直连 —— 缺少域名，SNI 不生效，证书校验也容易失败；优先用域名或配合proxy_ssl_name
启用 SNI 并显式指定服务器名
当后端是基于域名的 HTTPS 服务（如 Nginx/Apache 反向代理多个站点，或 Cloudflare、K8s Ingress 后端），必须让 Nginx 在 TLS 握手时发送正确的 server_name：
- 在对应
location或upstream的 proxy 段中添加：proxy_ssl_server_name on; - 如果 upstream 是 IP 或泛域名，还需指定具体主机名：
proxy_ssl_name "api.example.com"; - 同时设置 Host 头保持一致：
proxy_set_header Host "api.example.com";
不加 proxy_ssl_server_name on，Nginx 默认不发 SNI 扩展，后端无法识别该连哪个虚拟主机，直接拒绝握手。
关闭会话重用并验证 TLS 兼容性
部分后端（尤其是旧版 Java/Tomcat、某些嵌入式 HTTPS 服务）对 TLS 会话票据或密钥交换处理不严谨，开启重用会放大问题：
- 临时禁用会话复用：
proxy_ssl_session_reuse off; - 若仍失败，尝试限制 TLS 版本，排除高版本协商问题（例如禁用 TLS 1.3）：
proxy_ssl_protocols TLSv1.2; - 检查后端支持的加密套件是否与 Nginx 默认兼容，必要时显式配置：
proxy_ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
改完记得 nginx -t && nginx -s reload，不要用 restart。
