Cómo elegir entre los modos Fork y Cluster en PM2

El modo fork vs cluster de PM2 es una de las primeras decisiones a las que te enfrentas al ejecutar aplicaciones Node.js en producción. PM2 es el gestor de procesos de Node.js más usado (más de 43 000 estrellas en GitHub, más de 600 M de descargas en npm), y te ofrece dos formas fundamentalmente distintas de ejecutar tus apps. Elige el modo equivocado y desperdiciarás recursos o romperás funciones como la recarga graceful.

PM2 v7.0.3 (junio de 2026) es la versión actual. Requiere Node.js >= 18, añade soporte para el runtime Bun, incluye trazado con OpenTelemetry y source maps nativos. Si estás usando una versión de PM2 más antigua, la ruta de actualización importa. Más sobre eso abajo.

Esta guía cubre qué hace cada modo, las diferencias reales (incluidas algunas correcciones a lo que encontrarás en otros sitios), cuándo elegir cada uno y las buenas prácticas de producción que mantienen tus apps vivas.

Para un tutorial más amplio de PM2, consulta gestionar aplicaciones con PM2.

¿Qué es el modo fork en PM2?

El modo fork es el predeterminado de PM2. Genera un único proceso por aplicación usando child_process.fork() de Node. Un proceso, una app.

El modo fork es la elección correcta para:

• Scripts, workers y tareas cron: cualquier cosa que no escuche en un puerto.
• Runtimes que no son Node.js: el modo fork puede ejecutar Python, Ruby o binarios arbitrarios.
• Apps que necesitan distintas versiones de Node: usa node_args para apuntar a un binario específico.
• Desarrollo y pruebas: más simple, menor consumo de memoria.

Uso básico del modo fork

# Ejecuta app.js en modo fork (predeterminado)
pm2 start app.js

O con un archivo de ecosistema:

// ecosystem.config.js
module.exports = {
  apps: [{
    script: "app.js",
    exec_mode: "fork"
  }]
};

pm2 start ecosystem.config.js

Una creencia errónea común: funciones como los reinicios por cron, el soporte de source maps y los formatos de log personalizados no son exclusivas del modo fork. Son atributos generales de PM2 que funcionan tanto en fork como en cluster. PM2 v7 sustituyó la dependencia npm source-map-support por process.setSourceMapsEnabled() nativo, así que los source maps funcionan en todas partes sin paquetes extra.

Para gestionar las variables de entorno de PM2 entre modos, consulta la guía enlazada.

¿Qué es el modo cluster en PM2?

El modo cluster genera varios procesos worker usando el módulo cluster de Node.js. Cada worker es un proceso de sistema operativo independiente que ejecuta tu app, y comparten el mismo puerto del servidor mediante el uso compartido de handles IPC. Es una función de Node.js, no algo que PM2 haya inventado. El módulo cluster se encarga del balanceo de carga round-robin entre los workers.

Iniciar el modo cluster

# Ejecuta con tantos workers como núcleos de CPU
pm2 start app.js -i max

# Ejecuta con exactamente 4 workers
pm2 start app.js -i 4

Con un archivo de ecosistema:

// ecosystem.config.js
module.exports = {
  apps: [{
    script: "app.js",
    instances: "max",
    exec_mode: "cluster"
  }]
};

Desde PM2 v7, definir instances en una app de Node.js activa automáticamente el modo cluster. exec_mode: "cluster" explícito es opcional pero recomendado por claridad. Tu yo del futuro te lo agradecerá.

Los valores de instances:

• "max" o 0: un worker por núcleo de CPU
• -1: todos los núcleos menos uno (deja margen para el SO)
• Cualquier número: esa cantidad de workers

Ventajas del modo cluster

• Aprovechamiento multinúcleo: tu app atiende peticiones en paralelo en todos los núcleos.
• Tolerancia a fallos: si un worker se cae, PM2 lo reinicia mientras los demás siguen sirviendo.
• Recarga graceful / reinicio sin tiempo de inactividad: pm2 reload sustituye los workers uno a uno (explicado en detalle abajo).

Limitaciones del modo cluster

• Mayor uso de memoria: cada worker es un proceso aparte. 4 workers de 200 MB cada uno = 800 MB como mínimo.
• Requiere la misma versión de Node.js para todos los workers (limitación del módulo cluster). Bun tiene soporte en PM2 v7+ pero presenta casos límite. Haz pruebas exhaustivas.
• Requiere aplicaciones sin estado (stateless). Esta es la trampa que la mayoría de los tutoriales omiten.

PM2 fork vs cluster: diferencias clave

Si estás dimensionando un VPS para el modo cluster, primero haz benchmark de tu VPS para entender el margen real.

El modo cluster suele ser el mejor valor predeterminado para apps web en producción que sirven tráfico HTTP. El modo fork gana en cargas de trabajo sin red, trabajos en segundo plano y entornos donde necesitas varios runtimes o versiones de Node.

Recarga graceful y reinicio sin tiempo de inactividad en PM2

La recarga graceful y el reinicio sin tiempo de inactividad son lo que separa un entorno de desarrollo de un despliegue en producción. La mayoría de las guías de PM2 se saltan esta parte.

pm2 reload vs pm2 restart

Son comandos distintos con comportamientos distintos:

pm2 reload my-app     # reinicio continuo (cluster) / reinicio (fork)
pm2 restart my-app    # matar + arrancar inmediato

• pm2 restart mata todos los procesos y luego los arranca. Breve inactividad en modo fork. Inactividad total en modo cluster (todos los workers se matan a la vez).
• pm2 reload en modo cluster es un reinicio continuo real. Los workers se sustituyen uno a uno; al menos un worker sigue sirviendo tráfico en todo momento. En modo fork, pm2 reload recurre a pm2 restart (hay inactividad), porque solo hay un proceso. No hay nada que rotar.

Para despliegues sin tiempo de inactividad en modo cluster, usa siempre pm2 reload.

Apagado graceful en el lado de la aplicación (manejo de SIGINT)

Definir wait_ready: true en tu configuración de ecosistema le dice a PM2 que espere una señal de “ready” de tu app antes de considerarla iniciada. Pero esa señal tiene que venir de tu código. Cuando PM2 envía un SIGINT para recargar un worker, tu app necesita manejarlo: cerrar el servidor, vaciar las conexiones y salir limpiamente.

Sin este código, PM2 esperará listen_timeout y luego forzará el cierre del proceso. Eso no es graceful. Es un timeout con riesgo de pérdida de datos.

const express = require('express');
const app = express();

// ... tus rutas y middleware ...

const PORT = process.env.PORT || 3000;

const server = app.listen(PORT, () => {
  console.log(`Worker ${process.pid} escuchando en ${PORT}`);
  // Avisa a PM2 de que el worker está listo (requerido con wait_ready: true)
  if (process.send) {
    process.send('ready');
  }
});

// Maneja la señal de recarga graceful de PM2
process.on('SIGINT', () => {
  console.log('SIGINT recibido, cerrando el servidor...');
  server.close(() => {
    // Cierra conexiones de BD, vacía logs, libera recursos
    console.log('Servidor cerrado, saliendo');
    process.exit(0);
  });
  // Seguridad: salida forzada si no se cierra dentro de kill_timeout
  setTimeout(() => {
    console.error('Apagado forzado tras el timeout');
    process.exit(1);
  }, 5000);
});

La configuración de ecosistema que acompaña a esto:

module.exports = {
  apps: [{
    name: "my-api",
    script: "./app.js",
    instances: "max",
    exec_mode: "cluster",
    wait_ready: true,        // espera a process.send('ready')
    listen_timeout: 5000,    // ms de espera por la señal 'ready'
    kill_timeout: 5000,      // ms de espera para una salida limpia tras SIGINT
  }]
};

Buenas prácticas del modo cluster de PM2 para producción

Configuración de ecosistema para producción

Genera un archivo inicial con pm2 init simple (o pm2 ecosystem, ambos siguen funcionando). Luego complétalo:

// ecosystem.config.js
module.exports = {
  apps: [{
    name: "my-api",
    script: "./app.js",
    instances: "max",
    exec_mode: "cluster",              // explícito, recomendado por claridad
    max_memory_restart: "300M",         // reinicio automático si el worker supera 300 MB
    wait_ready: true,                   // espera a process.send('ready')
    listen_timeout: 5000,               // ms de espera por la señal ready
    kill_timeout: 5000,                 // ms de espera para el apagado limpio
    max_restarts: 10,                   // límite de reinicios dentro de la ventana min_uptime
    min_uptime: "10s",                  // si el proceso dura menos de 10 s, es un fallo
    log_date_format: "YYYY-MM-DD HH:mm:ss Z",
    merge_logs: true,                   // fusiona los logs de los workers en un archivo
    env: {
      NODE_ENV: "development",
    },
    env_production: {
      NODE_ENV: "production",
    },
  }]
};

Arrancar en producción:

pm2 start ecosystem.config.js --env production

Estrategia de escalado de instancias

No toda app necesita instances: "max". Escala según tu carga de trabajo:

• Apps limitadas por CPU: instances: "max" (una por núcleo).
• Apps limitadas por E/S: puedes probar 1,5x-2x el número de núcleos; vigila la memoria.
• VPS con memoria limitada: calcula RAM_disponible / RAM_por_instancia = máximo seguro.

Escalado dinámico sin reinicio:

pm2 scale my-app +2     # añade 2 workers más
pm2 scale my-app 4      # escala a exactamente 4 workers

Gestión de variables de entorno

Una trampa común: cuando reinicias por CLI con nuevas variables de entorno, no se actualizan a menos que pases --update-env:

NODE_ENV=production pm2 restart my-app --update-env

Los archivos de ecosistema siempre actualizan las variables de entorno al reiniciar o recargar. Úsalos siempre que puedas. Consulta variables de entorno de PM2 para todos los detalles.

Seguridad: filter_env

Si tu VPS tiene otros servicios o usuarios, evita que variables de entorno sensibles se filtren a los procesos hijo de PM2 con filter_env:

// En ecosystem.config.js
module.exports = {
  apps: [{
    name: "my-api",
    script: "./app.js",
    // Solo pasa estas variables de entorno (por prefijo) al worker
    filter_env: ["NODE_", "APP_", "DB_"],
    // O elimina TODAS las variables de entorno globales:
    // filter_env: true,
    // ...
  }]
};

Para un endurecimiento (hardening) más amplio del VPS, consulta cómo securizar un servidor VPS.

Rotación de logs

Por defecto, los logs de PM2 crecen hasta llenar el disco. Instala el módulo de rotación de logs:

pm2 install pm2-logrotate
pm2 set pm2-logrotate:max_size 10M
pm2 set pm2-logrotate:retain 30
pm2 set pm2-logrotate:compress true

Esto mantiene los logs en 10 MB por archivo, conserva 30 archivos rotados y comprime los antiguos. Esencial en cualquier VPS de producción.

Para una monitorización más amplia, consulta monitorizar el uso de CPU en Linux.

PM2 en contenedores: pm2-runtime para Docker

Si ejecutas PM2 dentro de un contenedor Docker, usa pm2-runtime en lugar de pm2 start.

El pm2 start normal genera un proceso demonio, lo cual es incorrecto para contenedores. El contenedor arranca, PM2 hace fork, el proceso principal termina y Docker cree que el contenedor ha acabado. pm2-runtime se mantiene en primer plano y envía los logs a stdout/stderr, que es lo que Docker espera.

FROM node:20-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .

CMD ["pm2-runtime", "start", "ecosystem.config.js"]

O sin un archivo de ecosistema:

CMD ["pm2-runtime", "npm", "--", "start"]

Una decisión: en Docker, el modo cluster escala mediante instances en el archivo de ecosistema o mediante réplicas de Docker/Kubernetes. Elige una opción, no ambas, o acabarás con N x M workers y te preguntarás por qué tu contenedor muere por OOM.

Para más sobre comandos de contenedores, consulta comandos de Docker para producción. El modo fork de PM2 también puede ejecutar apps de Python en Docker u otros runtimes que no sean Node.js.

Consideraciones sobre WebSocket y sticky sessions

El modo cluster usa balanceo de carga round-robin por defecto. Para peticiones HTTP, eso está bien: cada petición es independiente. Para conexiones WebSocket, es un problema. El handshake inicial llega al worker A, pero los frames siguientes pueden enrutarse al worker B, que no tiene ni idea de esa conexión.

Tres soluciones:

1. Sticky sessions en el proxy inverso: Nginx: ip_hash. HAProxy: persistencia basada en cookie. Esto fija un cliente a un worker.
2. Adaptador Redis para socket.io: @socket.io/redis-adapter permite que los workers compartan el estado de las conexiones. Funciona bien pero añade Redis como dependencia.
3. Servidor WebSocket separado: ejecuta tu manejador WebSocket en modo fork en un puerto distinto, junto a tu servidor HTTP en cluster. Simple, sin estado compartido.

Elige la opción que encaje con tu arquitectura. Si tienes un único VPS con Nginx delante, las sticky sessions son el camino más fácil.

PM2 v7: novedades (2025-2026)

PM2 v7.0.0 (mayo de 2026) fue una versión mayor. Cambios clave relevantes para la decisión fork vs cluster:

• Se requiere Node.js >= 18. PM2 abandonó el soporte de Node 16. Si aún estás en la 16, primero tienes que actualizar.
• Soporte del runtime Bun. Modo fork desde v6.0.5, modo cluster desde v7.0.0. Advertencia: Bun + cluster tiene casos límite (ver los issues de GitHub). Haz pruebas exhaustivas antes de desplegar.
• Source maps nativos. Sustituyó la dependencia npm source-map-support por process.setSourceMapsEnabled(). Funciona en ambos modos, sin paquetes extra.
• OpenTelemetry integrado. @opentelemetry/api, sdk-node y auto-instrumentations-node son dependencias directas. Advertencia: en modo cluster, los workers pueden reportar spans duplicados (problema conocido de OpenTelemetry).
• pm2 ls muestra métricas del host por defecto (v7.0.2). CPU, memoria y disco de un vistazo.
• max_memory_restart se muestra en pm2 describe (v7.0.1). Más fácil auditar los límites de memoria.
• Correcciones de seguridad. CVE-2025-5891 (ReDoS), CVE-2026-27699 (proxy-agent), tres correcciones de inyección de comandos, una corrección de prototype pollution. Si estás en v5 o v6, son buenas razones para actualizar.

Solución de problemas de PM2 en fork y cluster

# Comprueba qué está usando el puerto
lsof -i :3000

# Comprueba conflictos entre apps de PM2
pm2 list

# Revisa los logs para la causa raíz
pm2 logs my-app --lines 100

# Describe la app para ver los reinicios
pm2 describe my-app

# Comprueba si wait_ready está activado
pm2 describe my-app | grep wait_ready

# Busca el mensaje "SIGINT recibido" en los logs durante la recarga
pm2 logs my-app

# Observa la memoria en tiempo real
pm2 monit

NODE_ENV=production pm2 restart my-app --update-env

Comandos rápidos de verificación

Tras el despliegue, confirma que todo funciona como esperas:

pm2 list          # revisa la columna de modo (fork/cluster), nº de instancias y estado
pm2 describe 0    # info detallada: exec_mode, nº de reinicios, límites de memoria
pm2 monit         # CPU/memoria en vivo por instancia
pm2 logs          # busca errores de arranque

Conclusión

La vieja división “fork para funciones, cluster para escalar” está desfasada. Los reinicios por cron, los source maps y los formatos de log personalizados funcionan en ambos modos. Elige según la arquitectura de tu app:

• Modo cluster para servidores HTTP/TCP en producción que necesitan disponibilidad y aprovechamiento multinúcleo. Solo la recarga sin tiempo de inactividad ya compensa la memoria extra.
• Modo fork para workers en segundo plano, scripts, tareas cron, runtimes que no sean Node.js y entornos donde necesitas versiones de Node distintas por app.

Si estás en un VPS económico como Hetzner Cloud o Hostinger VPS, el modo cluster con 2 a 4 instancias funciona bien en un plan de 2 a 4 GB. Solo haz primero el cálculo de memoria.

Para el tutorial completo de PM2 sobre gestión de procesos, monitorización y despliegue, consulta gestionar aplicaciones con PM2. Si estás evaluando opciones más amplias de gestión de servidores, echa un vistazo a los paneles de servidor autoalojados como alternativa a la gestión manual con PM2.