Adaptador Cluster
Cómo funciona
El adaptador Cluster permite usar Socket.IO dentro de un clúster de Node.js.
Cada paquete enviado a múltiples clientes (ej. io.to("room1").emit() o socket.broadcast.emit()) también se envía a otros workers a través del canal IPC.
El código fuente de este adaptador se puede encontrar aquí: https://github.com/socketio/socket.io/tree/main/packages/socket.io-cluster-adapter
Características soportadas
| Característica | Versión de socket.io | Soporte |
|---|---|---|
| Gestión de sockets | 4.0.0 | ✅ SÍ (desde versión 0.1.0) |
| Comunicación entre servidores | 4.1.0 | ✅ SÍ (desde versión 0.1.0) |
| Broadcast con acknowledgements | 4.5.0 | ✅ SÍ (desde versión 0.2.0) |
| Recuperación del estado de conexión | 4.6.0 | ❌ NO |
Instalación
npm install @socket.io/cluster-adapter
Uso
Con cluster de Node.js
const cluster =require("cluster");
const http =require("http");
const{Server}=require("socket.io");
const numCPUs =require("os").cpus().length;
const{ setupMaster, setupWorker }=require("@socket.io/sticky");
const{ createAdapter, setupPrimary }=require("@socket.io/cluster-adapter");
if(cluster.isMaster){
console.log(`Master ${process.pid} está ejecutándose`);
const httpServer = http.createServer();
// configurar sesiones sticky
setupMaster(httpServer,{
loadBalancingMethod:"least-connection",
});
// configurar conexiones entre los workers
setupPrimary();
// necesario para paquetes que contienen buffers (puedes ignorarlo si solo envías objetos de texto plano)
// Node.js < 16.0.0
cluster.setupMaster({
serialization:"advanced",
});
// Node.js > 16.0.0
// cluster.setupPrimary({
// serialization: "advanced",
// });
httpServer.listen(3000);
for(let i =0; i < numCPUs; i++){
cluster.fork();
}
cluster.on("exit",(worker)=>{
console.log(`Worker ${worker.process.pid} murió`);
cluster.fork();
});
}else{
console.log(`Worker ${process.pid} iniciado`);
const httpServer = http.createServer();
const io =newServer(httpServer);
// usar el adaptador cluster
io.adapter(createAdapter());
// configurar conexión con el proceso primario
setupWorker(io);
io.on("connection",(socket)=>{
/* ... */
});
}
Con PM2
Ver la documentación asociada.
Con recluster
cluster.js
const cluster =require("cluster");
const http =require("http");
const{ setupMaster }=require("@socket.io/sticky");
const{ setupPrimary }=require("@socket.io/cluster-adapter");
const recluster =require("recluster");
const path =require("path");
const httpServer = http.createServer();
// configurar sesiones sticky
setupMaster(httpServer,{
loadBalancingMethod:"least-connection",
});
// configurar conexiones entre los workers
setupPrimary();
// necesario para paquetes que contienen buffers (puedes ignorarlo si solo envías objetos de texto plano)
// Node.js < 16.0.0
cluster.setupMaster({
serialization:"advanced",
});
// Node.js > 16.0.0
// cluster.setupPrimary({
// serialization: "advanced",
// });
httpServer.listen(3000);
const balancer =recluster(path.join(__dirname,"worker.js"));
balancer.run();
worker.js
const http =require("http");
const{Server}=require("socket.io");
const{ setupWorker }=require("@socket.io/sticky");
const{ createAdapter }=require("@socket.io/cluster-adapter");
const httpServer = http.createServer();
const io =newServer(httpServer);
// usar el adaptador cluster
io.adapter(createAdapter());
// configurar conexión con el proceso primario
setupWorker(io);
io.on("connection",(socket)=>{
/* ... */
});
Opciones
| Nombre | Descripción | Valor predeterminado |
|---|---|---|
heartbeatInterval | El número de ms entre dos heartbeats. | 5_000 |
heartbeatTimeout | El número de ms sin heartbeat antes de considerar un nodo caído. | 10_000 |
Últimas versiones
| Versión | Fecha de lanzamiento | Notas de lanzamiento | Diff |
|---|---|---|---|
0.3.0 | Octubre 2025 | link | 0.2.2...0c43124 |
0.2.2 | Marzo 2022 | link | 0.2.1...0.2.2 |
0.2.1 | Octubre 2022 | link | 0.2.0...0.2.1 |
0.2.0 | Abril 2022 | link | 0.1.0...0.2.0 |
0.1.0 | Junio 2021 | link |
Changelog completo: https://github.com/socketio/socket.io/blob/main/packages/socket.io-cluster-adapter/CHANGELOG.md