服务部署与常见故障排查
🎯 引言
本地聊天室可以运行后,需要让远端客户端连到同一个服务。部署时先确认进程正常、地址可达、代理转发正确,再检查认证和消息处理。本篇先部署单实例,最后介绍增加实例时需要补上的能力。
🧰 启动与检查
继续使用前面章节的 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 | 地址、端口、服务是否运行,以及错误消息 |
| UNAUTHENTICATED | token 是否正确,服务端认证规则是否匹配 |
| 能连接但无消息 | 事件名、房间加入结果、服务端发送范围 |
| 固定时间断开 | 代理空闲超时与心跳配置 |
| 一条消息打印多次 | 是否在 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 服务从本地运行推进到可检查的部署环境。
