服务部署与常见故障排查

配置端口和反向代理,检查连接与业务,并了解多实例广播的扩展方式。

🎯 引言

本地聊天室可以运行后,需要让远端客户端连到同一个服务。部署时先确认进程正常、地址可达、代理转发正确,再检查认证和消息处理。本篇先部署单实例,最后介绍增加实例时需要补上的能力。


🧰 启动与检查

继续使用前面章节的 server.mjs 和客户端。先将服务端原来的 listen 调用替换为下面的代码,使端口可以通过环境变量配置。

const port = Number(process.env.PORT || 3000);
httpServer.listen(port, () => {
    console.log(`服务已启动,端口:${port}`);
});

在服务器安装 Node.js 和项目依赖后启动服务。环境沿用 Node.js 24.19.0、socket.io 4.8.1 和 socket.io-client 4.8.1。

PORT=3000 node server.mjs

客户端将连接地址改为从环境变量 URL 读取,保留原有的有效凭证。

const socket = io(process.env.URL || 'http://localhost:3000', {
    auth: { token: 'demo-token-a' }
});

先在同一台机器运行客户端,确认连接和加入房间成功,再运行前面的用户B客户端发送一条消息,检查接收及确认结果。

URL=http://localhost:3000 node client.mjs

从另一台机器测试时,把 URL 换成服务器的域名或地址,并确认防火墙允许对应入口。部署时用进程管理工具持续运行服务,并记录标准输出。

主机平台的防火墙、进程管理和证书入口会更新,操作时以当前平台界面为准。

🛠 配置反向代理

反向代理把公网请求转发给内部的 Node.js 服务。以下 Nginx 配置可用于本地8080端口验证,放在 http 配置块内。公网使用 HTTPS 时还需配置自己域名的证书。

map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

server {
    listen 8080;

    location /socket.io/ {
        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 75s;
    }
}

Upgrade 和 Connection 头允许通信升级到 WebSocket。Socket.IO 默认还可以使用 HTTP 长轮询,两种传输都通过这个路径转发。代理读取超时应大于 Socket.IO 的心跳间隔与等待超时之和,默认合计约45秒,否则连接可能被代理定期关闭。反向代理文档

用 URL=http://localhost:8080 启动客户端,再做一次加入和收发测试。默认的 Socket.IO 请求路径是 /socket.io/,客户端、服务器和代理必须保持一致。

浏览器跨域时怎样设置

本课程的 Node.js 客户端可以直接指定服务端地址。如果使用单独域名的 Vue 页面,需要在创建 Server 时把实际前端来源加入 CORS 配置,例如 cors: { origin: 'https://chat.example.com' }。认证仍由 auth 凭证处理。来自非浏览器客户端的请求同样需要校验身份。


🧱 常见故障从哪里查

现象优先检查
服务启动报 EADDRINUSE端口是否被占用
一直 connect_error地址、端口、服务是否运行,以及错误消息
UNAUTHENTICATEDtoken 是否正确,服务端认证规则是否匹配
能连接但无消息事件名、房间加入结果、服务端发送范围
固定时间断开代理空闲超时与心跳配置
一条消息打印多次是否在 connect 内重复注册业务监听
重启后历史为空当前项目使用的是进程内存

日志可以记录 userId、事件名、房间和错误原因。避免把完整 token 写入日志。保存消息失败时应返回拒绝或错误,不能因为已经收到客户端事件就提前确认成功。


🧰 选学:两个实例怎样广播

默认房间只管理当前进程里的连接。要让连接到不同进程的用户通信,可以使用 Redis adapter。Adapter 是 Socket.IO 用来管理房间和传播广播的组件,这个实现通过 Redis 把广播传到其他实例。

以 Node.js 24.19.0、Socket.IO 4.8.1 为基线,安装 @socket.io/redis-adapter 8.3.0 和 redis 4.7.0,准备可连接的 Redis 7 服务。

npm install --save-exact @socket.io/redis-adapter@8.3.0 redis@4.7.0

在 server.mjs 导入模块,在创建 io 后、listen 前连接 Redis。

import { createClient } from 'redis';
import { createAdapter } from '@socket.io/redis-adapter';

const pub = createClient({ url: process.env.REDIS_URL });
const sub = pub.duplicate();
pub.on('error', (error) => console.error(error.message));
sub.on('error', (error) => console.error(error.message));
await Promise.all([pub.connect(), sub.connect()]);
io.adapter(createAdapter(pub, sub));

启动两个不同 PORT 的实例,使用相同 REDIS_URL。让A的 URL 指向3000,B指向3001,都加入room1,A发消息时B应收到。

此实验只验证跨实例实时广播。当前 histories Map 分别存在于两个进程,历史查询还不能一致,继续扩展需把它移到共享数据库。登录会话和成员权限也应共享。默认长轮询需要负载均衡器保持同一连接的请求落在同一实例,Redis adapter 不会替代这个路由设置。Redis adapter


❓ 知识问答

Q1:进程已经启动,是否就能判断上线成功?

还需通过实际入口验证连接、身份、加入房间和一次消息往返。进程运行无法说明代理转发和业务监听都正确。

Q2:服务退出前需要做什么?

停止接收新业务,等待正在处理的操作结束,再关闭 Socket.IO 和依赖连接。实际环境由进程管理工具设置退出宽限期,客户端重新连接后再恢复订阅和补取记录。


🧪 小练习

分别通过直连端口和代理端口完成同一组登录、加入、发送、退出测试。停掉Node.js服务,观察客户端错误,再恢复服务并确认重新加入。记录一次错误现象、检查位置和修复结果。


🎉 你已经可以把 Socket.IO 服务从本地运行推进到可检查的部署环境。