核心是让proxy_read_timeout设为后端心跳间隔的2–3倍（如90–120s），并同步配置proxy_send_timeout、upstream keepalive及系统tcp参数，location中还需启用http/1.1升级头和proxy_buffering off。

要防止 WebSocket 在 Nginx 代理下中途断连，核心不是盲目拉长 proxy_read_timeout，而是让它精准匹配后端心跳节奏，并配套调整其他关键参数。默认值 60 秒会直接导致静默 60 秒后连接被 Nginx 主动关闭，客户端收到 WebSocket is closed 或 EOF 错误——这不是后端崩溃，是代理层单方面“撕票”。

按心跳周期设 proxy_read_timeout

该参数控制的是 Nginx 从后端读取数据时允许的最大空闲时间（单位：秒），只管“两次数据帧之间的等待”，不管整个会话寿命。

• 后端每 30 秒发一次 ping → 设为 90–120
• 工控设备固定 45 秒上报 → 设为 180
• 低频审批通知（心跳 3600 秒）→ 设为 3600 即可，不必硬上 86400
• 禁止设为 0，Nginx 不支持无限超时，会退化回默认 60 秒

必须同步配置的三项配套

只改 proxy_read_timeout 是无效的，以下三者缺一不可：

WebChat Voice Proxy

⚠️ 已弃用 — 该技能已拆分为两个独立技能，以提升模块化程度：**webchat-https-proxy**（HTTPS/WSS 反向代理）和 **webchat-voi...**

下载

• proxy_send_timeout 必须与 proxy_read_timeout 值一致，否则大消息或弱网下发送阶段就被切断
• upstream keepalive 需启用，例如 keepalive 32;，避免每次心跳都重建 TCP 连接
• 系统级 TCP 参数：检查 net.ipv4.tcp_keepalive_time ≥ 7200，防止内核早于 Nginx 主动断连

location 块内必须包含的基础转发配置

这些必须写在对应 WebSocket 路径的 location 块中（不能放在 http 或 server 级）：

• proxy_http_version 1.1; —— WebSocket 强制要求 HTTP/1.1
• proxy_set_header Upgrade $http_upgrade; —— 透传客户端原始 Upgrade 头
• proxy_set_header Connection "upgrade"; —— 注意双引号，确保字面量传递
• proxy_buffering off; —— 防止帧被缓存粘包，破坏 WebSocket 流式语义

Kubernetes Ingress 环境特别注意

在 Nginx Ingress Controller 中，不要修改 ConfigMap 或 nginx.conf：

• 通过 Ingress 资源的 annotation 注入：nginx.ingress.kubernetes.io/proxy-read-timeout: "120"
• 支持按路径粒度控制，例如 /ws/chat 和 /ws/notify 可设不同值
• 硬改全局配置易被升级覆盖，且无法实现路由级差异化