Como instalar o Z-PRO em Modo Cluster

Por padrão, o backend do Z-PRO roda em modo fork — um único processo Node.js atendendo todas as requisições. Em instalações com volume alto de atendimentos, isso pode limitar o aproveitamento dos núcleos de CPU disponíveis no servidor. O Modo Cluster resolve isso: o PM2 passa a rodar múltiplos processos (workers) do backend em paralelo, distribuindo a carga entre eles.

Este guia mostra como ativar o Modo Cluster numa instalação já funcionando do Z-PRO.

Recurso em beta, fora do escopo do suporte técnico. A configuração e o ajuste de infraestrutura do Modo Cluster (Redis, PM2, número de workers) ficam sob responsabilidade do licenciado, de acordo com os termos de uso do modelo self-hosted. Valide em ambiente de teste antes de aplicar em produção.

Pré-requisitos:

• Z-PRO já instalado e funcionando em modo fork (padrão).

• Acesso root/sudo ao servidor.

• Docker (para rodar o Redis) ou um Redis já disponível na rede.

• PM2 instalado e em uso para gerenciar o processo do backend.

---

Como funciona

No Modo Cluster, o PM2 inicia N processos do backend. Um deles é eleito Worker 0 (primary) e os demais são secundários:

Recurso	Worker 0 (primary)	Workers 1..N (secundários)
HTTP API (GET)	✓	✓
HTTP API (POST/PUT/DELETE em rotas de sessão)	✓	proxy automático → Worker 0
Socket.IO	✓	✓ (sincronizado via Redis)
Sessões WhatsApp (Baileys/WWJS)	✓	✗
Jobs (cron/setInterval)	✓	✗
WebSocket do Webchat	✓	✗

Como cada worker é um processo separado, eles não compartilham memória. Por isso o Redis é obrigatório: ele faz o papel de Socket.IO Adapter, repassando os eventos de WebSocket entre todos os workers para que qualquer usuário conectado em qualquer worker receba as atualizações em tempo real.

Sessões, jobs e Webchat continuam centralizados no Worker 0. O Modo Cluster escala o atendimento HTTP e o Socket.IO, mas as conexões WhatsApp (Baileys/WWJS) e os jobs periódicos do sistema sempre rodam num único processo — isso evita sessões duplicadas e disputas de lock.

---

Etapa 1: Subir o Redis

Se você ainda não tem um Redis disponível, crie um com Docker:

docker run -d --name zpro-redis --restart unless-stopped -p 6379:6379 redis:7-alpine redis-server --requirepass SUA_SENHA_AQUI

Confirme que ele está respondendo:

docker ps | grep zpro-redis
docker exec -it zpro-redis redis-cli -a SUA_SENHA_AQUI ping

O comando ping deve retornar PONG.

---

Etapa 2: Configurar o .env do backend

Adicione (ou edite) estas variáveis no .env do backend:

# ===== REDIS (obrigatório para cluster) =====
IO_REDIS_SERVER=localhost
IO_REDIS_PASSWORD=SUA_SENHA_AQUI
IO_REDIS_PORT=6379
IO_REDIS_DB_SESSION=2

# ===== CLUSTER MODE =====
CLUSTER_MODE=true

# Número de workers (processos). Recomendado: número de CPUs do servidor ou metade
CLUSTER_INSTANCES=4

# Porta interna usada pelos workers secundários para fazer proxy ao Worker 0
# Não deve ser exposta externamente nem coincidir com a porta principal (PORT)
CLUSTER_PRIMARY_PORT=3002

CLUSTER_PRIMARY_PORT é de uso interno. Ela é usada apenas para a comunicação entre workers — não abra essa porta no firewall nem exponha ao público.

---

Etapa 3: Build do projeto

Diferente do modo fork, o Modo Cluster exige build antes de iniciar:

npm run build

---

Etapa 4: Iniciar com PM2

CLUSTER_MODE=true CLUSTER_INSTANCES=4 pm2 start ecosystem.config.js

As variáveis também podem já estar definidas no .env — nesse caso, basta rodar pm2 start ecosystem.config.js sem repeti-las na linha de comando.

---

Etapa 5: Verificar os workers

pm2 list                    # mostra quantos workers estão rodando
pm2 logs                    # logs de todos os workers
pm2 logs 0                  # logs só do Worker 0 (primary)
pm2 monit                   # monitor em tempo real (CPU/memória por worker)

Você deve ver CLUSTER_INSTANCES processos com o nome zpro-backend listados como online.

---

Voltar ao modo fork

Para desativar o cluster e voltar ao comportamento original (um único processo):

CLUSTER_MODE=false

Ou simplesmente remova a variável CLUSTER_MODE do .env. Depois, reinicie:

pm2 restart all

---

Resumo dos Comandos

Comando	Função
pm2 start ecosystem.config.js	Inicia o backend (fork ou cluster, conforme .env)
pm2 list	Lista os workers em execução
pm2 logs / pm2 logs 0	Logs de todos os workers / só do Worker 0
pm2 monit	Monitor de CPU/memória em tempo real
pm2 restart all	Reinicia todos os workers
pm2 stop all / pm2 delete all	Para / remove todos os workers

---

Encerramento

Com o Modo Cluster ativo, o Z-PRO passa a distribuir as requisições HTTP entre múltiplos processos, aproveitando melhor os núcleos de CPU do servidor — sem duplicar sessões do WhatsApp nem os jobs internos, que continuam centralizados no Worker 0. É a opção recomendada para instalações com alto volume de atendimentos simultâneos.

---

Sobre o suporte a este recurso

O Z-PRO é self-hosted: a ZPRO fornece o software, não a infraestrutura — a gestão do servidor (VPS) é responsabilidade do Cliente (Termos de Uso, cláusula 5.4). Por isso, configuração, gestão, manutenção ou segurança do servidor ficam fora do escopo do suporte técnico padrão (cláusula 7.4, item I), o que inclui o ajuste de infraestrutura necessário para o Modo Cluster.

---

Possíveis Erros e Soluções

Erro: workers secundários não conseguem se conectar ao Redis

Causa: IO_REDIS_SERVER/IO_REDIS_PASSWORD/IO_REDIS_PORT incorretos, ou o Redis não está acessível pela rede do servidor.

Solução: confirme o docker exec -it zpro-redis redis-cli -a SUA_SENHA ping retornando PONG e revise as variáveis IO_REDIS_* no .env.

Erro: build ausente ao iniciar em cluster

Causa: o Modo Cluster carrega o backend a partir de dist/server.js — sem rodar npm run build antes, o PM2 não encontra os arquivos.

Solução: rode npm run build antes de pm2 start ecosystem.config.js sempre que alternar para o Modo Cluster ou atualizar o código.

Sessões do WhatsApp não respondem em alguns workers

Causa: não é um erro — sessões WhatsApp (Baileys/WWJS), jobs e o WebSocket do Webchat só existem no Worker 0. Esse é o comportamento esperado do Modo Cluster.

Solução: nenhuma ação necessária. As requisições de sessão (POST/PUT/DELETE) feitas em workers secundários são automaticamente repassadas (proxy) para o Worker 0.

Conflito de porta com CLUSTER_PRIMARY_PORT

Causa: a porta interna definida em CLUSTER_PRIMARY_PORT já está em uso por outro serviço no servidor.

Solução: escolha outra porta livre e atualize a variável no .env antes de reiniciar.