Nginx 代理 WebSocket 心跳保活的关键是协同配置超时参数与前后端心跳：必须设 proxy_read_timeout > 心跳间隔（如心跳30秒则至少45秒），配合 proxy_http_version 1.1、proxy_set_header Upgrade $http_upgrade 和 Connection "upgrade"，并关闭 proxy_buffering，确保心跳帧透传不被中断。
在 Nginx 中代理 WebSocket 时，心跳保活和超时中断不是由 Nginx 主动发起的，而是通过配置相关超时参数来配合客户端和服务端的心跳机制，避免连接被中间设备（如防火墙、负载均衡器）或 Nginx 自身误断。关键在于正确设置几个与长连接生命周期相关的 timeout 指令。
必须配置的三个核心超时参数
Nginx 对 WebSocket 连接的维持依赖于以下三个指令，缺一不可，且需协同设置：
- proxy_read_timeout：定义 Nginx 从上游（WebSocket 后端）读取响应的最长等待时间。若后端在该时间内未发送任何数据（包括 ping/pong 心跳帧），Nginx 将主动关闭连接。建议设为略大于服务端心跳间隔（例如后端每 30 秒发一次 pong，则设为 35 或 45）。
- proxy_send_timeout：定义 Nginx 向上游发送请求或数据的最大等待时间。对 WebSocket 来说，它影响的是 Nginx 将客户端数据转发给后端的超时，一般无需调得很大，60 已足够，除非后端处理极慢。
- proxy_http_version 1.1 和 proxy_set_header Upgrade $http_upgrade、proxy_set_header Connection "upgrade"：这是启用 WebSocket 代理的前置条件，确保协议升级成功；没有它们，连接根本不会进入 WebSocket 模式，timeout 设置也无效。
客户端与服务端需同步配合心跳
Nginx 不解析 WebSocket 帧，不识别 ping/pong，也不主动发心跳。真正的保活靠前后端约定：
- 客户端（如浏览器 JS）应定期（如每 25 秒）调用
ws.send()发送业务数据，或依赖浏览器自动响应服务端 ping —— 多数现代浏览器会自动回复 pong。 - 服务端（如 Node.js 的 ws 库、Spring WebSocket）需开启心跳检测（如
pingInterval: 30000），并确保在proxy_read_timeout设定的时间内至少有一次数据交互（哪怕只是 pong）。 - 若服务端只发 ping、不收 pong 或不发 pong，而客户端又不主动发数据，Nginx 在
proxy_read_timeout后就会断连 —— 这是常见“莫名断连”的根源。
可选但推荐的补充配置
增强稳定性与可观测性：
- proxy_buffering off：禁用缓冲，让 WebSocket 数据实时透传，避免因缓冲导致延迟或粘包错觉。
- proxy_request_buffering off：防止 Nginx 对 WebSocket 升级请求做请求体缓冲（默认开启，可能干扰 upgrade 流程）。
- keepalive_timeout（在 http 或 server 块）：控制 Nginx 与客户端之间 HTTP 连接的空闲保持时间。WebSocket 已升级，此值不影响 WebSocket 数据流，但影响升级前的初始连接；设为 75 左右较稳妥。
一个典型可用的 server 配置片段
假设后端 WebSocket 服务运行在 localhost:8080，期望支持 30 秒心跳：
location /ws/ {
proxy_pass http://localhost:8080;
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_read_timeout 45;
proxy_send_timeout 60;
proxy_buffering off;
proxy_request_buffering off;
}
注意：proxy_read_timeout 45 是最关键的保活参数，它给了后端 45 秒窗口来响应或发送任意帧；只要在此期间有数据流动，连接就持续存活。
