WebSocket长连接服务器配置指南

知识分享

2026-06-08 01:40

14 阅读

为什么要单独配置 WebSocket 长连接服务器？

WebSocket 是一种全双工的通信协议，一旦建立连接，服务端和客户端可以随时互相推送数据，非常适合在线聊天、股票行情、实时通知等场景。
普通的 HTTP 请求是“一问一答”，而 WebSocket 保持一条长期通道，省去反复握手的开销。
如果你的应用需要主动推送或低延迟交互，就得在服务器上专门做 WebSocket 长连接配置，否则默认的 Nginx 或防火墙会把连接截断。

准备工作：你需要哪些条件？

在动手之前，先把这几样备齐：

一台云服务器：Linux 系统（推荐 Ubuntu 20.04 或 CentOS 7/8），内存 1G 以上即可。
一个域名（非必需，但推荐）：用于配置 SSL 证书，因为现代浏览器强制要求安全连接（wss://）才能使用 WebSocket。
SSH 客户端：Windows 用户可以用 Xshell 或 Putty，macOS/Linux 直接终端。
Node.js 环境：我们用它演示一个简单的 WebSocket 服务端，你也可以换成 Python、Go 等。

确认服务器已经开放 22 端口（SSH），并且你能用 root 或 sudo 权限执行命令。

核心操作：分四步完成 WebSocket 长连接服务器配置

第一步：部署 WebSocket 服务端程序

登录服务器后，先安装 Node.js。
以 Ubuntu 为例：

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

创建一个项目目录并初始化：

mkdir ws-server && cd ws-server
npm init -y
npm install ws   # 安装 ws 库

新建 server.js 文件，写入一个最简单的 WebSocket 回声服务：

const WebSocket = require('ws');
const wss = new WebSocket.Server({ port: 8080 });

wss.on('connection', function connection(ws) {
  console.log('新客户端已连接');
  ws.on('message', function incoming(message) {
    console.log('收到消息:', message);
    ws.send('服务端回声: ' + message);
  });
  ws.send('欢迎连接 WebSocket 服务器');
});

启动服务：

node server.js &

建议用 nohup node server.js > ws.log 2>&1 & 让进程在后台持久运行。

第二步：配置 Nginx 反向代理 WebSocket

Nginx 默认的 HTTP 代理不认识 WebSocket 的升级请求，必须手动添加 Upgrade 和 Connection 头。
编辑 Nginx 配置文件（例如 /etc/nginx/conf.d/ws.example.com.conf）：

server {
    listen 80;
    server_name ws.example.com;   # 换成你自己的域名

    location / {
        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_set_header Upgrade $http_upgrade; 让 Nginx 把客户端发起的 WebSocket 升级请求传递给后端。
proxy_set_header Connection "upgrade"; 告诉后端这是一个升级连接。

检查配置并重载：

nginx -t
nginx -s reload

第三步：放行防火墙端口

如果服务器启用了防火墙（如 ufw 或 firewalld），需要允许外部访问 80（或 443）以及后端端口（本示例 8080）。

Ubuntu（ufw）：

sudo ufw allow 80/tcp
sudo ufw allow 8080/tcp
sudo ufw reload

CentOS（firewalld）：

sudo firewall-cmd --add-port=80/tcp --permanent
sudo firewall-cmd --add-port=8080/tcp --permanent
sudo firewall-cmd --reload

如果想开启 HTTPS（强烈推荐），还要放行 443 端口，并使用 Certbot 申请 SSL 证书。

第四步：验证 WebSocket 长连接是否正常工作

使用浏览器开发者工具或在线 WebSocket 测试工具。
打开 Chrome，按 F12 → Console，输入：

let ws = new WebSocket('ws://ws.example.com');  // 如果用 HTTPS，改成 wss://
ws.onopen = function() { console.log('连接成功'); };
ws.onmessage = function(e) { console.log('收到:', e.data); };
ws.send('你好');

如果控制台看到“连接成功”并且很快收到“欢迎连接 WebSocket 服务器”，说明配置正确。
也可以查看服务端日志 cat ws.log，确认有“新客户端已连接”的日志。

高频问题与避坑指南

问题 1：后端启动了，但客户端一直连接不上

检查 Nginx 配置里是否遗漏了 proxy_set_header 那两行。
检查防火墙是否放行了对应端口（尤其是 8080，如果连接走代理则只放行 80/443）。
检查 /var/log/nginx/error.log 看是否有 502 或连接拒绝的错误。

问题 2：WebSocket 连接几秒后自动断开

这可能是因为后端程序未设置心跳保活，或者 Nginx 的 proxy_read_timeout 太短（默认 60 秒）。
可以在 Nginx 的 location 块里增加：

proxy_read_timeout 3600s;
proxy_send_timeout 3600s;

同时在后端程序里实现定时发送 ping/pong 帧，保持长连接。

问题 3：用了 HTTPS 但 WebSocket 连接失败

如果你配置了 SSL，那么客户端必须使用 wss:// 协议，且 Nginx 需要监听 443 端口并包含 SSL 配置。
另一个常见问题是在 SSL 终端上又没正确传递升级头，务必在 SSL 的 server 块里也加上相同的 proxy_set_header。

写在最后

WebSocket 长连接服务器配置并不复杂，核心就是两个点：一是后端程序要监听一个端口，二是 Nginx 反向代理时要正确传递升级头。
按照上面步骤操作，大部分人都能在 30 分钟内跑通。
如果你在生产环境中使用，记得加上进程守护（如 PM2 或 systemd）和 SSL 加密。
处理遇到异常时，优先回看本文的避坑和高频问题部分，对照日志逐条排查，通常都能解决。

HTTP2与QUIC协议部署加速网站

服务器网卡绑定提升网络带宽：服务器网卡绑定全攻略