本文详解nginx代理websocket时出现“invalid websocket upgrade”错误的根本原因，并提供经过生产验证的最小完备配置，涵盖http/1.1协议启用、upgrade头透传、connection头动态处理及超时优化等关键要点。
本文详解nginx代理websocket时出现“invalid websocket upgrade”错误的根本原因，并提供经过生产验证的最小完备配置，涵盖http/1.1协议启用、upgrade头透传、connection头动态处理及超时优化等关键要点。
WebSocket连接在Nginx反向代理环境下频繁失败（如报错 Invalid websocket upgrade 或浏览器端 Unexpected response code: 200/400），其本质并非应用层逻辑缺陷，而是Nginx默认行为与WebSocket协议升级机制不兼容所致。
WebSocket握手依赖标准HTTP/1.1的协议升级流程：客户端发送含 Upgrade: websocket 和 Connection: Upgrade 头的请求；服务端响应 101 Switching Protocols 后，复用同一TCP连接切换为二进制帧通信。而Nginx默认以HTTP/1.0转发请求，且会过滤非标准请求头（如 $http_upgrade），导致关键升级信号被静默丢弃——这正是NiceGUI等框架日志中提示 Invalid websocket upgrade 的直接原因。
✅ 正确配置：四步闭环解决
以下配置需同时应用于 HTTP（80）和HTTPS（443）server块中的对应location（推荐精确匹配WebSocket路径，如 / _nicegui_ws/ 或 /websocket）：
location /_nicegui_ws/ {
proxy_pass http://127.0.0.1:8080;
# ① 强制使用 HTTP/1.1（WebSocket 升级的前提）
proxy_http_version 1.1;
# ② 透传客户端原始 Upgrade 头（关键！）
proxy_set_header Upgrade $http_upgrade;
# ③ 动态设置 Connection 头：WebSocket 请求设为 "upgrade"，普通请求设为 "close"
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
proxy_set_header Connection $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_set_header X-Forwarded-Proto $scheme;
proxy_buffering off; # 禁用缓冲，避免流式数据延迟
proxy_read_timeout 3600; # 连接空闲超时设为1小时（可根据业务调整）
proxy_send_timeout 3600;
}⚠️ 注意事项：
- proxy_set_header Connection "Upgrade" 是错误写法——它会强制所有请求都携带 Connection: Upgrade，破坏普通HTTP流量。必须配合 map 指令实现条件透传。
- proxy_http_version 1.1 必须显式声明，否则Nginx内部仍按HTTP/1.0与后端通信，导致升级失败。
- 若使用WSS（WebSocket Secure），确保SSL证书有效，且Nginx HTTPS配置中已正确设置 proxy_set_header X-Forwarded-Proto https;，否则后端可能因协议误判拒绝升级。
- 修改配置后务必执行验证与重载：
sudo nginx -t && sudo nginx -s reload
? 排查辅助技巧
当问题仍存在时，可快速定位瓶颈：
- 查看Nginx错误日志：tail -f /var/log/nginx/error.log，重点关注 upstream sent no valid HTTP/1.0 header 或 invalid Upgrade header 类报错；
- 抓包验证协议版本：使用 tcpdump -i lo port 8080 -w ws.pcap，Wireshark中检查Nginx与后端间是否为HTTP/1.1交互；
- 绕过Nginx直连测试：curl -v -H "Upgrade: websocket" -H "Connection: Upgrade" http://127.0.0.1:8080/_nicegui_ws/，确认后端自身可正常响应101。
通过上述配置，Nginx即可安全、高效地代理WebSocket流量，兼顾实时性与兼容性。该方案已在NiceGUI、Socket.IO、FastAPI WebSocket等多种框架中稳定运行，是当前Nginx代理WebSocket的事实标准实践。
