nginx 实现协议升级需协同配置 proxy_http_version 1.1、proxy_set_header upgrade $http_upgrade 和 connection "upgrade"，并禁用缓冲与调整超时。
在 Nginx 中通过 proxy_set_header Connection 实现协议升级（如 HTTP → WebSocket、HTTP/1.1 → HTTP/2 代理中透传升级请求），关键在于正确透传 Connection 和 Upgrade 请求头，并关闭 Nginx 的缓冲与连接复用干扰。这不是简单加一行配置，而是需协同多个指令完成的端到端链路适配。
明确协议升级的核心请求头组合
客户端发起升级（如 WebSocket）时，必须携带两个关键请求头：
-
Connection: Upgrade—— 告知中间节点“当前连接将切换协议” -
Upgrade: websocket（或h2c等）—— 指明目标协议类型
Nginx 默认会清除或改写 Connection 头（因它属于“逐跳头”，hop-by-hop），所以必须显式保留；同时需确保后端服务能收到原始 Upgrade 头。
WebSocket 升级转发的标准配置示例
以下是最小可行配置，适用于反向代理 WebSocket 服务（如前端 Vue App 连接后端 ws://api.example.com/ws）：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
location /ws/ {
proxy_pass http://backend_ws;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
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_read_timeout 86400; # 长连接保活，避免空闲断连
}
说明：
-
proxy_http_version 1.1是强制项 —— HTTP/1.0 不支持Upgrade机制 -
$http_upgrade是 Nginx 内置变量，自动捕获客户端发来的Upgrade头值（大小写不敏感） -
Connection "upgrade"必须写成字面量"upgrade"，不能写$http_connection—— 否则可能带入keep-alive等干扰值 -
proxy_read_timeout设长些，防止 Nginx 主动关闭空闲长连接
避免常见陷阱：缓冲、重定向与 SSL 终止
即使头设置正确，仍可能失败，原因常藏在其他配置中：
-
禁用缓冲：添加
proxy_buffering off;，否则 Nginx 可能缓存响应并破坏 WebSocket 帧流 - 关闭重定向跟随：WebSocket 不支持 301/302 跳转，确保后端不返回重定向；若必须跳转，应在应用层处理
-
SSL 终止时注意：若 Nginx 做 HTTPS 终止，客户端用
wss://，Nginx 到后端仍可用ws://（明文），但需确认后端接受非加密 WebSocket；若后端也要求 TLS，则用https://+proxy_ssl_*系列指令 -
检查 upstream 是否健康：WebSocket 连接建立阶段无传统 HTTP body，
health_check类型需设为type=websocket或禁用主动健康检查，避免误判
验证是否生效的实操方法
不要只看 Nginx 日志，要端到端抓包或调试：
- 用浏览器开发者工具 → Network → WS 标签，查看连接状态码是否为
101 Switching Protocols - 用
curl -i -H "Connection: Upgrade" -H "Upgrade: websocket" http://your-nginx/ws/模拟请求，观察响应头 - 在后端服务日志中打印收到的请求头，确认
Upgrade和Connection是否原样抵达 - 用
tcpdump或 Wireshark 抓 Nginx 与后端之间的包，过滤http.request.uri contains "ws"，比对请求头字段
只要客户端发了 Upgrade、Nginx 正确透传、后端识别并返回 101，就表示协议升级链路打通。后续数据帧即走新协议，不再经过 HTTP 解析。
