必须显式配置proxy_http_version 1.1，否则nginx默认以http/1.0向上游发起请求，无法传递upgrade、keep-alive等关键头部，导致wss、grpc等安全路径下的长连接握手失败、复用失效；还需同步配置proxy_set_header connection ""、proxy_set_header upgrade $http_upgrade、proxy_set_header connection "upgrade"及upstream keepalive n，并调优proxy_read_timeout等参数。
要让 Nginx 在反向代理中真正启用与后端的高性能长连接复用，必须显式配置 proxy_http_version 1.1——这不是可选项，而是激活整个长连接链路的开关。默认情况下，Nginx 以 HTTP/1.0 向上游发起请求，即便客户端走的是 HTTPS + HTTP/1.1，不写这一行，后端永远收不到 Upgrade 或 Keep-Alive 相关语义，安全路径（如 WSS、HTTPS API）下的连接复用就无从谈起。
为什么 proxy_http_version 1.1 是安全路径下长连接的前提
HTTP/1.0 不支持协议升级（101 Switching Protocols）和持久连接自动协商。WSS、gRPC-over-HTTP/2（需 ALPN）、甚至某些 TLS 封装的 REST API 都依赖 HTTP/1.1 的逐跳头部（如 Upgrade、Connection）完成握手或维持通道。Nginx 若未强制设为 1.1，会直接丢弃或忽略这些头，导致：
- 前端 WebSocket 连接卡在
CONNECTING状态，控制台报1006 - HTTPS 后端返回 400 或 502，access log 显示“invalid request”
- 即使 upstream 配了
keepalive 32，连接池也始终为空
必须同步配置的三项关键配套
单写 proxy_http_version 1.1 仅是起点，还需三者协同才能落地：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
-
清除干扰性 Connection 头：加
proxy_set_header Connection ""，防止客户端传来的Connection: close或其他值污染后端判断 -
透传 Upgrade 协议升级信号：对 WebSocket/WSS 场景，必须配
proxy_set_header Upgrade $http_upgrade和proxy_set_header Connection "upgrade"（注意是固定字符串"upgrade"，非变量） -
启用 upstream 连接池：在
upstream块中配置keepalive 32（数值按并发量调整），并确保后端服务本身支持 keep-alive（如 Tomcat 的connectionTimeout非零，Node.js 未禁用server.keepAliveTimeout）
HTTPS/WSS 安全路径下的超时与缓冲调优
安全链路往往承载长周期通信（如实时通知、心跳保活），默认 60 秒超时和响应缓冲会直接中断连接：
-
proxy_read_timeout 3600：避免后端空闲期间 Nginx 主动断连（WSS 推荐设为 3600 或更高） -
proxy_send_timeout 3600：保障服务端消息、心跳帧能稳定发出 -
proxy_buffering off：禁用缓冲，防止 WebSocket 帧被攒批发送，造成延迟或粘包 - 不启用任何
proxy_cache_*指令：WSS 和长连接数据不可缓存，否则握手失败
配置位置与生效要点
这几项必须写在 location 块内，且 proxy_http_version 1.1 要紧邻 proxy_pass 后（不能被 if 块包裹或条件覆盖）：
- MacOS 下配置路径为
/usr/local/etc/nginx/nginx.conf，改完需nginx -t校验 +nginx -s reload - 若使用多级代理（如 CDN → Nginx → Backend），确保每一层都启用
proxy_http_version 1.1和对应头透传 - 验证是否生效：抓包看 Nginx 发往后端的请求是否含
Connection: upgrade及Upgrade: websocket；或检查后端 access log 中连接复用情况
