如何在Python中配置Nginx反向代理以支持WebSocket长连接-Python教程-PHP中文网

nginx 默认不透传 websocket 升级头，必须配置 proxy_http_version 1.1、proxy_set_header upgrade $http_upgrade、proxy_set_header connection "upgrade"、proxy_set_header host $host 和 proxy_pass 五项，缺一则握手失败导致 400 或连接秒断。

如何在python中配置nginx反向代理以支持websocket长连接

Nginx 默认不转发 WebSocket 升级请求，直接配 proxy_pass 会导致 400 或连接立即关闭 —— 必须显式透传 Upgrade 和 Connection 头，并禁用缓冲。

为什么 WebSocket 在 Nginx 后会断开

浏览器发起 WebSocket 连接时，会发送带 Upgrade: websocket 和 Connection: Upgrade 的 HTTP 请求。Nginx 默认把这类请求当普通 HTTP 处理，不透传升级头，也不保持长连接，后端（如 Python 的 websockets 或 FastAPI + uvicorn）收不到合法的升级请求，直接返回 400 或静默关闭。

常见现象：WebSocket opening handshake was canceled、Error during WebSocket handshake: Unexpected response code: 400、连接建立后几秒内自动 close。

确保后端服务本身支持 WebSocket（例如 uvicorn 启动时未禁用 --ws，websockets 服务监听正确路径）
Nginx 版本需 ≥ 1.3.13（旧版不支持 Upgrade 透传）
不要在 location 块里加 proxy_buffering on —— WebSocket 是流式协议，缓冲会破坏帧边界

必需的 Nginx 配置项

在对应 location 块中添加以下 5 行，缺一不可：

python学习

Python 编程学习助手 skill，面向零基础用户。当用户表达以下意图时触发： - 学习 Python 基础概念（变量、数据类型、循环、函数、类等） - 请求 Python 练习题或测验 - 请求审查或调试 Python 代码 - 请求 Python 项目实战指导（爬虫、数据分析、Web 开发等入门项目） - 泛化表述如"教我 Python""我想学编程""Python 怎么写""帮我学 Python" 此 skill

下载

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_pass http://your_backend;

说明：

proxy_http_version 1.1：WebSocket 依赖 HTTP/1.1 的持久连接和升级机制
$http_upgrade 是 Nginx 内置变量，只在请求含 Upgrade 头时非空；若直接写死 "websocket"，普通 HTTP 请求也会被错误升级
Connection "upgrade" 必须加英文双引号，否则 Nginx 会忽略该值（这是易错点）
proxy_set_header Host $host 看似冗余，但某些 Python 框架（如 Starlette）校验 Host 头是否匹配，缺失会导致 400

Python 后端注意事项（以 uvicorn + FastAPI 为例）

即使 Nginx 配对了，Python 侧仍可能因配置或中间件中断连接：

启动命令必须含 --ws（uvicorn ≥ 0.20.0 默认开启，但低版本需显式指定）
避免使用 gzip 中间件或任何修改响应 body 的中间件 —— WebSocket 帧不是 HTTP body，压缩会损坏二进制帧
检查路由路径是否一致：Nginx 的 location /ws/ 必须和 FastAPI 的 @app.websocket("/ws/") 完全匹配（注意结尾斜杠）
如果用 websockets 库自建服务，确保监听的是 0.0.0.0:port 而非 127.0.0.1:port，否则 Nginx 无法反向代理到它

验证与调试技巧

别只看浏览器控制台，要分层确认：

用 curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" http://your-domain.com/ws/ 直连 Nginx，看响应头是否含 Upgrade: websocket 和 Connection: upgrade
在 Python 后端日志中打印 scope["type"]（ASGI）或 request.headers.get("upgrade")（WSGI 兼容层），确认升级头是否抵达
Nginx 错误日志（error_log /var/log/nginx/error.log debug;）里搜 upstream prematurely closed 或 websocket，能快速定位是 Nginx 断开还是后端拒绝
WebSocket 连接建立后，用 ss -tuln | grep :your_port 观察连接状态，ESTAB 持续存在才说明长连接生效