NPM 反代 WebSocket 不推送消息？排查思路与解决姿势都在这了

最近折腾建站，发现不少朋友在用 Nginx Proxy Manager（也就是大家熟知的 NPM）做反向代理时，都会遇到一个让人头秃的问题：明明网页能打开，HTTP 访问一切正常，但涉及到实时通信的功能（比如在线客服、即时聊天）却直接“哑火”了。

我手头也正好有个类似的环境：后端跑着 PHP 的实时通讯系统，前面套了一层 NPM。直连后端端口时，消息那是秒收；但一旦经过 NPM 转发，推送就断了，非得手动刷新页面才能把新消息“刷”出来。这显然是 WebSocket 在反代环节出了幺蛾子。

今天就把这个坑的排查思路和解决办法细细扒一遍，希望能帮到正为此烦恼的朋友。

🕵️‍♂️ 问题定位：为什么 WebSocket 挂了？

首先我们要明白，WebSocket 和普通的 HTTP 请求不太一样。HTTP 是“短平快”，请求完就断开；而 WebSocket 是为了保持长连接设计的，它需要一条持续的通道来推送数据。

当你使用 Nginx（包括 NPM）做反代时，默认的配置往往是针对 HTTP 优化的。它在处理 WebSocket 握手请求时，因为缺少特定的头字段支持，或者超时时间设置得太短，就可能有以下两种“搞事”行为：

拦截升级请求： WebSocket 连接建立时，客户端会发一个带有 Upgrade: websocket 头的 HTTP 请求。如果 Nginx 不知道要放过这个请求，或者没把头原样转发给后端，连接就升级失败，退化成普通 HTTP。
超时切断连接： 即使握手成功了，如果 Nginx 的 proxy_read_timeout 设置得比较短（比如默认的 60 秒），一旦这期间双方没有数据传输，Nginx 就会以为连接空闲，直接把链路掐断。这就是为什么“页面能访问，但消息过一会就不推了”的根本原因。

🛠️ 解决方案：给 NPM 开个“后门”

NPM 虽然是个可视化工具，但它本质还是生成 Nginx 配置文件。解决方法就是手动注入 Nginx 的 WebSocket 支持指令。操作步骤如下：

1. 找到 Advanced 配置区

在 NPM 的后台，找到你那个 Proxy Host（代理主机），Edit 编辑，切到 Advanced 选项卡。这里就是我们要自定义 Nginx 指令的地方。

2. 注入关键配置代码

我们需要告诉 Nginx 两件事：一是别改那些特殊的头，二是把超时时间设长一点。请在 Custom Nginx Configuration 输入框中粘贴以下内容：

# WebSocket 核心配置
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

# 增加超时时间，防止长连接被断开（建议设置大一点，比如一小时）
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;

代码详解：

proxy_set_header Upgrade $http_upgrade;：这一步至关重要，它告诉 Nginx，“嘿，客户端想升级协议，你照着传给后端，别拦着”。
proxy_set_header Connection "upgrade";：这行是指定连接状态为升级，配合上一行使用，完成 WebSocket 握手。
proxy_read_timeout 3600s;：这里定义了后端响应的超时时间。如果不设置，WebSocket 一旦静默超过 60 秒，Nginx 就会切断连接。设置为 3600s（1小时）能有效解决“连上没多久就断”的问题。

3. 保存并生效

点击 Save，NPM 会自动重载 Nginx 配置。不出意外的话，你的实时推送功能这就恢复了。

💡 进阶排查：如果还不行怎么办？

如果加了上面的配置还是不灵，别急，还有几个细节可以查：

检查 SSL 配置： 如果你启用了 HTTPS，确保后端服务也正确处理了 SSL 链接，或者 NPM 到后端是 HTTP 明文代理但协议头没乱写。通常保持 SSL Offloading（也就是 NPM 负责解密，NPM 到后端走 HTTP）是最稳的路径。
查看浏览器控制台： 按 F12 打开开发者工具，切换到 Network 或 Console 标签。看看 WebSocket 连接状态是不是显示 101 Switching Protocols。如果是 pending 或者直接 failed/404，那说明请求根本没到后端，或者后端路径配置错了。
Nginx 错误日志： 直接上服务器看 /var/log/nginx/error.log，这上面报错最准确，通常能看到是超时还是连接被拒绝。

⚡ 总结

遇到这种“网页能用但功能残缺”的问题，90% 都是反代配置没适配长连接。记住 Nginx 反代 WebSocket 的三板斧：传递 Upgrade 头、传递 Connection 头、延长超时时间。搞定这三点，基本就能稳住长连接了。

希望这篇排查笔记能帮你省下那 50R 的“悬赏金”，留着去买杯咖啡不香吗？