PAYATHON 2026

为什么 Websocket 在 SiteGround 生产环境中无法正常工作?

排障赵师傅

SiteGround 不支持题目中通过 6001、7001 等自定义端口对外提供 WebSocket 服务的部署方式。即使找到 privkey.pem 和 fullchain.pem,也无法解除平台的端口限制。SiteGround 官方建议改用标准 HTTP/HTTPS 端口上的长轮询。SiteGround 官方说明

如果必须使用 WebSocket,可以把网站继续放在 SiteGround,将 Socket.IO 服务部署到支持 WebSocket 的其他环境,让浏览器连接该服务。

为什么会在连接建立之前关闭?

这条错误表示 WebSocket 握手未完成,单凭它无法判断问题出在证书、网络、代理,还是服务未能启动。题目中的配置需要逐项检查。

监听的变量写错了

前面创建的是 server,最后调用的却是:

httpServer.listen(6001, "0.0.0.0", () => {
  console.log("Socket.IO server running on port 6001");
});

如果其他代码没有定义 httpServer,程序就会抛出 ReferenceError。这里应使用绑定 Socket.IO 的同一个实例:

server.listen(6001, "0.0.0.0", () => {
  console.log("Socket.IO server running on port 6001");
});

这项修改只能修复代码错误,监听 0.0.0.0 不会自动开放主机防火墙或平台入口。

实际连接地址与代码不一致

服务端和客户端示例使用的是 6001,报错指向的却是:

wss://sohraba28.sg-host.com:7001/socket.io/?EIO=4&transport=websocket

检查生产环境变量、前端构建产物和浏览器实际加载的配置,确认最终连接的域名和端口。否则,即使修好了 6001 上的服务,浏览器仍可能访问 7001。

客户端地址也建议明确写出协议:

io("https://socket.example.com", {
  auth: payload,
});

Socket.IO 客户端接受 https:// 或 wss:// 地址。HTTPS 页面连接 WebSocket 时应使用加密连接。客户端初始化文档

强制 WebSocket 后没有长轮询回退

两端都设置了:

transports: ["websocket"]

这会把传输方式限制为 WebSocket,平台不支持时,Socket.IO 就无法回退到 HTTP 长轮询。Socket.IO 连接机制

SiteGround 的证书在哪里?

各主机平台提供的证书文件名并不统一,不能假定一定有 privkey.pem 和 fullchain.pem,也不能直接把 /etc/ssl/privkey.pem 当作 SiteGround 的证书路径。

SiteGround 官方提供的 Let’s Encrypt 证书查看入口是:

Site Tools > Security > SSL Manager > Manage SSL
> 对应证书的菜单 > View Certificate

在这里可以查看证书、私钥和 CA Bundle。SSL 管理文档

如果需要在自己控制的服务器上整理成 PEM 文件:

  • privkey.pem 保存与证书匹配的私钥。
  • fullchain.pem 保存服务器证书及所需的中间证书链,服务器证书放在前面。

在允许 Node.js 直接终止 TLS 的环境中,可以这样创建 HTTPS 服务:

import { createServer } from "node:https";
import { readFileSync } from "node:fs";

const server = createServer({
  key: readFileSync("/actual/path/privkey.pem"),
  cert: readFileSync("/actual/path/fullchain.pem"),
});

将路径替换为文件的实际位置,再把这个 server 传给 new Server(server, ...)。Node.js HTTPS 文档

证书必须覆盖客户端实际访问的域名。手动复制到其他服务器后,还需要自行同步续期。私钥只能保存在服务端,不能放入前端代码或公开仓库。

方案一:将 Socket.IO 部署到支持 WebSocket 的环境

部署结构可以是:

SiteGround 上的网页
    ↓
https://socket.example.com:443
    ↓ TLS 由平台或反向代理处理
Node.js Socket.IO 服务

WebSocket 可以使用标准 443 端口,无需让浏览器访问自定义端口。入口代理仍须支持 WebSocket Upgrade,仅把客户端端口改成 443 并不能解决代理不支持的问题。

服务端示例

这段代码适用于平台或反向代理处理 HTTPS,再通过内部 HTTP 将请求转发到 Node.js 的环境:

import { createServer } from "node:http";
import { Server } from "socket.io";

const server = createServer();

const io = new Server(server, {
  path: "/socket.io/",
  cors: {
    origin: ["https://mydomain.com"],
    credentials: true,
  },
  transports: ["polling", "websocket"],
});

io.on("connection", (socket) => {
  console.log("Dashboard connected:", socket.id);

  socket.on("disconnect", (reason) => {
    console.log("Dashboard disconnected:", socket.id, reason);
  });
});

const port = Number(process.env.PORT || 6001);

server.listen(port, "0.0.0.0", () => {
  console.log(`Socket.IO server listening on ${port}`);
});

PORT 的取值和监听方式应遵循部署平台的要求。这里的 6001 只是内部端口示例,浏览器通过 443 访问服务。

反向代理需要将 /socket.io/ 转发到该进程,并正确处理 Upgrade、Connection 请求头。代理超时应大于 Socket.IO 的 pingInterval + pingTimeout。反向代理配置文档

客户端示例

import { io } from "socket.io-client";

S.socket = io("https://socket.example.com", {
  path: "/socket.io/",
  withCredentials: true,
  auth: payload,
  transports: ["polling", "websocket"],
});

S.socket.on("connect", () => {
  console.log("Connected:", S.socket.id);
});

S.socket.on("connect_error", (error) => {
  console.error("Socket.IO connection failed:", error.message);
});

将服务域名解析到新的 Socket.IO 部署入口,并配置覆盖该域名的有效证书。采用这种结构时,Node.js 通常不需要读取 SiteGround 的证书。

方案二:保留 SiteGround,改用 HTTP 长轮询

使用这个方案前,需要确认当前套餐支持运行该 Node.js 应用,而且能通过平台提供的标准 HTTPS 入口访问 Socket.IO 路由。

SiteGround 已提供 Node.js 托管服务,能否运行 Node.js、能否使用 WebSocket,需要分别确认。SiteGround Node.js 托管说明

将前述服务端配置中的传输方式改为:

transports: ["polling"]

客户端也要同步修改:

S.socket = io("https://your-node-app.example.com", {
  path: "/socket.io/",
  withCredentials: true,
  auth: payload,
  transports: ["polling"],
});

这里必须填写实际运行 Socket.IO 应用的 HTTPS 地址,不能继续访问被平台限制的 :6001 或 :7001。

长轮询仍需要 Socket.IO 服务端持续运行,只修改客户端参数或上传静态前端文件都无法提供这项服务。如果当前套餐无法运行该后端,可以将后端迁出;更新频率较低时,也可以改用普通 HTTP API 定时查询。

部署后还要检查什么?

cors.origin 应填写前端页面的完整 Origin,例如:

origin: ["https://mydomain.com"]

只写 "mydomain.com" 不符合浏览器 Origin 的格式。使用跨域凭据时,允许来源也不能设为 "*"。浏览器的 CORS 限制主要作用于 HTTP 长轮询,因此修正 CORS 并不能解决所有强制 WebSocket 连接失败的问题。Socket.IO CORS 文档

启用长轮询后,可以用下面的命令检查公开入口:

curl -i 'https://socket.example.com/socket.io/?EIO=4&transport=polling'

正常的 Engine.IO 握手响应应以 0 开头,并包含 sid 等字段。如果返回 HTML、404 或 502,先检查路由、代理和进程状态。这项检查只能确认长轮询入口可达。要确认 WebSocket 是否连接成功,还需在浏览器网络面板中检查握手是否返回 101 Switching Protocols。

服务端还需要验证客户端通过 auth: payload 传入的认证数据,传递这些数据本身不会自动完成鉴权。

备注:内容仅供参考。