Nginx 中怎么使用 proxy_pass 实现即时通讯聊天服务的长连接代理-Nginx-PHP中文网

nginx代理websocket等即时通讯需配置协议升级与超时保活：设proxy_http_version 1.1、透传upgrade头、connection设为upgrade；调大proxy_read_timeout和proxy_send_timeout至86400，关闭proxy_buffering；路径须独立location精确匹配。

nginx 中怎么使用 proxy_pass 实现即时通讯聊天服务的长连接代理

在 Nginx 中用 proxy_pass 代理即时通讯（如 WebSocket、SSE 或长轮询）的聊天服务，关键不是单纯写上 proxy_pass，而是必须配合一系列连接保活和协议升级配置，否则长连接会很快被断开或降级为短连接。

必须启用 WebSocket 协议升级

WebSocket 依赖 HTTP 的 Upgrade 和 Connection: upgrade 头完成握手。Nginx 默认不透传这些头，需显式设置：

proxy_http_version 1.1; —— 强制使用 HTTP/1.1（WebSocket 升级要求）
proxy_set_header Upgrade $http_upgrade; —— 将客户端的 Upgrade 头（如 "websocket"）透传给后端
proxy_set_header Connection "upgrade"; —— 固定设为 "upgrade"，触发 Nginx 自身的升级处理逻辑

防止连接被意外关闭

默认情况下，Nginx 的超时机制会主动关闭空闲长连接。需延长或禁用相关超时：

proxy_read_timeout 86400; —— 后端响应空闲等待时间（秒），设为 24 小时可覆盖典型聊天场景
proxy_send_timeout 86400; —— Nginx 向后端发数据的超时，同样建议拉长
proxy_connect_timeout 60; —— 建连超时保持合理即可（60 秒足够）
避免设置 proxy_buffering on;（默认开启），长连接建议关掉：proxy_buffering off;，防止 Nginx 缓存未完结响应导致粘包或延迟

匹配路径与后端地址要明确

不要把 WebSocket 路径和普通 API 混在同一 location，推荐单独拆分：

FastAPI Flask Proxy

FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。

下载

例如后端 WebSocket 服务跑在 http://127.0.0.1:8080/chat，则 location 应精确匹配：
location /chat/ {
proxy_pass http://backend/chat/;（注意末尾斜杠，保证路径重写一致）
# 上述 upgrade + timeout 配置全部放在这里
}

若后端要求路径完全透传（比如需要 /chat/ws），可用 rewrite 或确保 proxy_pass 不带路径后缀。

验证是否生效

上线后务必检查三件事：

浏览器开发者工具 Network 标签中，WebSocket 连接状态应为 101 Switching Protocols，而非 200 OK 或直接失败
Nginx error log 中不应出现 upstream prematurely closed connection 或 client closed connection 类报错
用 curl -i -H "Connection: upgrade" -H "Upgrade: websocket" http://your-domain/chat/ 手动测试握手是否返回 101

不复杂但容易忽略：少配一个头、漏设一个超时，都可能导致连接几秒后断开，表现为“能连上但发不了消息”或“频繁重连”。