在 nginx 中配置 websocket 心跳保持机制，核心在于利用 `proxy_read_timeout` 和 `proxy_send_timeout` 参数来维持连接存活。默认情况下，nginx 会在一段时间无数据传输后关闭连接，通过将这些超时时间设置为较大的值（如 86400 秒），可以防止 nginx 主动切断长连接。同时，必须确保 http 升级请求头 `upgrade` 和 `connection` 被正确传递到后端服务，由后端应用层负责实际的心跳包发送与响应逻辑。
Nginx 如何透传 WebSocket 升级请求头
Nginx 需要显式配置 `proxy_set_header` 指令来转发 `Upgrade` 和 `Connection` 头部字段，否则后端无法识别 WebSocket 握手请求。如果不进行此配置，WebSocket 连接将降级为普通 HTTP 请求并立即关闭。这是建立 WebSocket 通道的前提条件，只有握手成功，后续的心跳机制才能生效。
server {
listen 80;
server_name example.com;
location /ws {
proxy_pass http://backend_server;
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_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
如何设置 Nginx 层面的连接超时时间
为了防止 Nginx 在客户端或后端空闲时主动断开连接，需要调整 `proxy_read_timeout` 和 `proxy_send_timeout`。这些参数定义了 Nginx 在与上游服务器通信时，两次成功传输之间的最大间隔。如果超过这个时间没有数据交换，Nginx 会返回 504 错误并关闭连接。对于 WebSocket 这种长连接场景，通常将其设置为一个非常大的数值，或者根据业务需求设定合理的保活周期。
server {
listen 80;
server_name example.com;
location /ws {
proxy_pass http://backend_server;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
# 设置超时时间为 1 天，防止 Nginx 主动断开
proxy_read_timeout 86400s;
proxy_send_timeout 86400s;
}
}
当后端服务未发送心跳包时 Nginx 的行为表现
如果后端服务没有按照约定发送心跳包，且 Nginx 配置的超时时间较短，Nginx 将会检测到连接空闲并主动关闭它。此时，客户端会收到连接断开的信号。若后端服务持续不响应，Nginx 的 `proxy_read_timeout` 计时器会在最后一次收到后端数据后开始计数，一旦超时，Nginx 会向客户端发送 504 Gateway Timeout 错误。因此，仅靠 Nginx 配置不足以完全维持心跳，必须配合后端应用的定期心跳发送，才能确保连接长期稳定。
