必须显式配置proxy_http_version 1.1、proxy_set_header Connection ""和upstream keepalive N三项，缺一不可：HTTP/1.1提供长连接协议基础，清空Connection头防透传干扰，keepalive声明连接池大小以复用TCP连接。
要让 Nginx 与后端之间真正复用 TCP 连接，proxy_http_version 1.1; 和 proxy_set_header Connection ""; 必须成对出现，且必须配合 upstream 中的 keepalive N; —— 三者缺一不可。单独写其中一项，不仅无效，还可能引发连接频繁重建、后端负载飙升等问题。
为什么必须显式写 proxy_http_version 1.1
默认情况下，Nginx 向上游（后端）发起的是 HTTP/1.0 请求。而 HTTP/1.0 协议本身不定义持久连接机制，即使后端返回 Keep-Alive 响应头，Nginx 也不会识别、不会等待、更不会把连接交还给连接池。
只有启用 HTTP/1.1，Nginx 才具备以下能力：
- 在发往后端的请求中自动携带 Connection: keep-alive（前提是 Connection 头未被干扰）
- 正确解析并响应后端返回的 Keep-Alive: timeout=60, max=100 等指令
- 在响应结束后保持 TCP 连接打开，供后续请求复用
注意：该指令必须写在 location 块内，且需放在 proxy_pass 之后；写在 upstream 或 server 块中会被忽略或报错。
为什么 Connection 头必须清空而不是设为 keep-alive
客户端可能携带 Connection: close、Connection: upgrade 或其他非标准值。如果 Nginx 直接透传这些头，后端会按字面意思立即关闭连接，导致长连接失效。
proxy_set_header Connection ""; 的作用是“清除”而非“覆盖”——它让 Nginx 不向后端发送任何 Connection 指令，转而由 HTTP/1.1 协议默认行为接管连接生命周期。
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
常见误区：
- 写成
proxy_set_header Connection "keep-alive";：后端可能误判为“客户端要求关闭连接”，反向触发断连 - 写成
proxy_set_header Connection "close";：等同于主动宣告断连 - 完全不配置：Nginx 默认透传原始 Connection 头，风险不可控
三项配置如何协同生效
这三项不是独立开关，而是一个完整闭环：
- proxy_http_version 1.1; 提供协议基础 —— 让连接“可以”复用
- proxy_set_header Connection ""; 清除干扰信号 —— 让连接“不被强制关闭”
- upstream { keepalive 32; } 声明连接池容量 —— 让连接“有地方可复用”
典型配置结构如下：
<!-- upstream 定义在 http 块下 -->
upstream backend {
server 10.0.1.10:8080;
keepalive 32;
}
location /api/ {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
WebSocket 场景下的特殊处理
普通 API 接口适用清空 Connection 头，但 WebSocket 升级握手必须保留特定语义：
- 不能使用
proxy_set_header Connection ""; - 必须动态设置：
proxy_set_header Connection "upgrade";和proxy_set_header Upgrade $http_upgrade; - 通常还需搭配
proxy_read_timeout 3600;防止空闲断连
混用会导致握手失败（返回 200 或 502，而非 101 Switching Protocols）。
