在宝塔面板中部署带有实时通信需求的应用时，WebSocket经常会在几十秒后莫名断开。根本原因在于Nginx作为反向代理没有把协议升级请求正确传递给后端，同时默认的代理超时时间太短，导致空闲连接被直接关闭。理解并修正这些代理规则，就能让长连接稳定工作。
为什么反向代理会导致WebSocket断开
WebSocket在建立连接时，客户端先发送一个HTTP请求，里面带有Upgrade: websocket和Connection: Upgrade头。这个请求告诉服务器，要把协议从HTTP切换成WebSocket。如果前面的Nginx没有把这些头转发给后端，后端就不知道要升级协议，连接无法建立或建立后立即断开。
另一个常见问题是超时。Nginx的proxy_read_timeout默认是六十秒。WebSocket是长连接，可能很长时间没有消息往来。一旦超过这个时间代理层没有收到后端数据，Nginx就会主动断开连接，前端就会收到close事件。很多开发者误以为是代码bug，其实是代理层的超时配置在起作用。
在宝塔面板中找到Nginx配置入口
登录宝塔面板后，进入左侧的网站菜单，点击对应站点名称，选择配置文件选项卡。这里展示的就是该站点对应的Nginx server块内容。我们所有的修改都在这个文本区域里完成，不需要去命令行手动编辑文件。
如果你使用的是LNMP环境，宝塔默认就是Nginx处理站点。确认面板软件商店中Nginx已安装且运行正常。有些用户装了Apache又装Nginx，导致配置混乱，建议实时通信类项目统一用Nginx做唯一前端代理，避免多层代理放大超时与头丢失问题。
添加WebSocket代理配置
在server块内部的location中，加入处理WebSocket所需的代理头与超时设置。核心是指明升级协议头，并放大读写超时。以下给出一个典型的配置片段，你可以直接复制到宝塔的配置文件中对应location里。
location /ws/ {
proxy_pass http://127.0.0.1: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_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
}
其中proxy_set_header Connection "Upgrade"对于固定WebSocket路径是安全的。如果你的 location 同时服务普通HTTP和WebSocket，需要使用变量判断，宝塔里可以用map指令实现，后文会提到。超时被设为3600秒，意味着一小时无数据才会断开，足以覆盖绝大多数心跳间隔。
修改完成后，点击面板下方的保存按钮，然后点击重载配置或重启Nginx。不要直接重启服务器，重载就能让新配置生效，且不会中断其他站点服务。
使用map指令兼容混合路径
当同一个location既处理普通请求又处理WebSocket时，写死Connection为Upgrade会让普通请求出错。Nginx提供了map指令，根据$http_upgrade的值动态决定Connection头。
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 80;
server_name example.ipipp.com;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header Host $host;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
}
}
这段配置要放在http块中，而宝塔的站点配置文件通常已经包含在总配置里，你可以把map写在面板配置文件的server块之外顶部，或者在宝塔的Nginx主配置中增加。它的作用是：如果请求带upgrade头，Connection就是upgrade；如果不带，就是close，普通HTTP请求不受影响。
使用map后，前端无论访问普通接口还是连接WebSocket，代理层都能正确转发。这是生产环境最稳妥的写法，也避免了因配置错误导致的静态资源加载异常。
后端代码示例与心跳
除了代理配置，后端也应配合发送心跳，防止中间网络设备回收连接。下面以Node.js的ws库为例，展示一个最小服务。
const WebSocket = require('ws');
const wss = new WebSocket.Server({ port: 8080, path: '/ws/' });
wss.on('connection', function connection(ws) {
// 每三十秒发送一次心跳
const timer = setInterval(() => {
if (ws.readyState === WebSocket.OPEN) {
ws.send(JSON.stringify({ type: 'ping' }));
}
}, 30000);
ws.on('message', function incoming(msg) {
console.log('received:', msg.toString());
});
ws.on('close', function () {
clearInterval(timer);
});
});
心跳间隔应小于Nginx的proxy_read_timeout。上面代理设的是3600秒，心跳三十秒完全足够。即使客户端网络短暂阻塞，只要心跳正常，连接就不会被代理层误杀。
前端也应实现onclose重连逻辑，但那是应用层容错，不能替代代理层正确配置。只有代理层稳定，重连频率才会降到最低，用户体验才平滑。
常见错误排查
第一，忘记写proxy_http_version 1.1。Nginx默认用1.0代理，不支持keep-alive和协议升级，WebSocket必然失败。第二，宝塔开启了防跨站或额外安全插件，可能注入自己的location，覆盖了你的配置，需要检查配置文件中是否有重复location块。
第三，使用了CDN。如果域名走了Cloudflare等CDN，它们对WebSocket支持有限且有自己的超时，需在CDN后台开启WebSocket功能。否则你在宝塔配得再好，外层CDN照样断流。排查时建议先绕过CDN，用服务器IP直连测试，确认是代理层还是CDN层问题。
| 现象 | 可能原因 | 解决办法 |
|---|---|---|
| 握手后立即断开 | 未转发Upgrade头 | 添加proxy_set_header Upgrade |
| 几十秒后断开 | 代理超时太短 | 调大proxy_read_timeout |
| 普通页面打不开 | Connection写死Upgrade | 改用map动态赋值 |
总结建议
在宝塔面板配置WebSocket并不复杂，核心就是三件事：升级HTTP版本、传递升级头、放大超时。配合后端心跳，就能彻底解决反向代理下的长连接断开。建议将所有实时通信站点统一用Nginx管理，避免Apache与Nginx混用带来的配置分歧。
每次修改配置后，利用浏览器的开发者工具查看Network中的WebSocket帧，确认连接状态是101 Switching Protocols，并且能持续收到ping帧，就说明代理链路已经完全通畅。