如何利用 proxy_set_header Connection 实现 WebSocket 协议的平滑升级-Nginx-PHP中文网

websocket 协议升级必须配置 proxy_set_header connection "upgrade";，因其与 proxy_http_version 1.1; 和 proxy_set_header upgrade $http_upgrade; 协同触发 101 响应，缺一不可；还需设置 proxy_read_timeout 和 proxy_send_timeout 防止长连接超时断开。

如何利用 proxy_set_header connection 实现 websocket 协议的平滑升级

要让 WebSocket 连接成功完成协议升级，proxy_set_header Connection 的配置不是可选项，而是关键动作。它的作用不是“添加一个普通请求头”，而是向后端明确传达：“这个连接不是普通 HTTP 请求，而是正在申请协议切换”。Nginx 默认会把客户端发来的 Connection: Upgrade 或 Connection: keep-alive, upgrade 等值直接丢弃或重写，导致后端收不到有效升级信号，握手失败。

为什么 Connection 头必须显式设为 "upgrade"

Nginx 官方文档明确要求：当代理 WebSocket 时，Connection 头必须被强制设为字符串 "upgrade"（全小写，带英文双引号）。这是因为：

HTTP/1.1 升级机制依赖 Connection: upgrade 与 Upgrade: websocket 成对出现，缺一不可
客户端实际发送的 Connection 头可能含多个值（如 keep-alive, upgrade），而 Nginx 默认不透传，也不做解析
后端服务（如 Spring Boot WebSocket、ws 库、Socket.IO）只认标准格式的 Connection: upgrade，其他形式会被忽略或拒绝

正确写法与常见错误

在 location 块中必须这样写：

proxy_set_header Connection "upgrade";

⚠️ 容易出错的地方：

CPA Update - Secure CLI Proxy API Maintenance

安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。

下载

漏掉英文双引号：Connection upgrade 是无效语法，Nginx 配置校验（nginx -t）会报错
大小写错误：写成 "Upgrade" 或 "UPGRADE"，后端无法识别
误用变量：$http_connection 不可靠——客户端可能没发该头，或值不规范，不能替代硬编码的 "upgrade"
放在 http 或 server 块顶层：必须放在具体的 location /ws/ { ... } 内，避免影响普通 HTTP 接口

它必须和另外两个指令协同工作

Connection "upgrade" 单独存在毫无意义，必须搭配以下两项才能触发完整升级流程：

proxy_http_version 1.1;：WebSocket 升级基于 HTTP/1.1 持久连接，HTTP/1.0 会被直接拒绝
proxy_set_header Upgrade $http_upgrade;：把客户端原始的 Upgrade: websocket 头原样转发，否则后端看不到升级意图

三者缺一不可。只要其中任一缺失，浏览器发起 WebSocket 连接时，后端收不到标准升级请求，返回的仍是 200 OK，而非 101 Switching Protocols，连接立即中断。