PM2 e reinício automático: mantendo o processo vivo

Um processo Node.js que lança uma exceção não tratada simplesmente morre. Se ninguém o sobe de volta, seu bot, API ou site fica fora do ar até você perceber. Um supervisor de processos resolve isso: ele fica de olho no seu app e o reinicia quando ele cai. No ecossistema Node.js, o mais usado é o PM2.

Como instalar e iniciar um app com o PM2?#

Com o Node.js instalado (veja como hospedar um app Node.js), instale globalmente e inicie o seu arquivo principal:

npm install pm2 -g
pm2 start app.js --name meu-app
pm2 list
pm2 logs meu-app

pm2 list mostra o status de cada processo, pm2 logs acompanha a saída em tempo real e pm2 restart meu-app reinicia manualmente. Para parar e remover da lista, use pm2 stop meu-app e pm2 delete meu-app.

Por padrão, o autorestart é true: se o app falhar ou terminar, o PM2 o sobe de novo. Para um script de execução única (uma migração, por exemplo), desligue com --no-autorestart.

Como usar um ecosystem file?#

Passar flags na linha de comando não escala. O ecosystem file concentra toda a configuração num arquivo versionado:

// ecosystem.config.js
module.exports = {
  apps: [
    {
      name: "meu-app",
      script: "./app.js",
      max_memory_restart: "300M",
      max_restarts: 10,
      restart_delay: 3000,
      kill_timeout: 5000,
      env: { NODE_ENV: "development" },
      env_production: { NODE_ENV: "production" },
    },
  ],
};

Inicie com pm2 start ecosystem.config.js --env production. O bloco env_production é aplicado só quando você passa --env production. Nunca grave segredos (tokens, senhas) nesse arquivo: leia-os de variáveis de ambiente. O arquivo usa CommonJS (module.exports); se o seu package.json tem "type": "module", chame-o de ecosystem.config.cjs.

Quais opções de reinício valem a pena?#

Duas dessas opções merecem cuidado.

max_memory_restart esconde um vazamento de memória, não o resolve. É um paliativo útil enquanto você investiga. Se o app reinicia a cada hora por memória, o defeito continua no código.

Sem restart_delay, um erro na inicialização vira um loop apertado. O app cai em milissegundos, o PM2 o sobe e ele cai de novo. Depois de max_restarts falhas instáveis seguidas, o PM2 marca o app como errored e para de tentar. Use restart_delay ou exp_backoff_restart_delay para dar fôlego a dependências externas, como um banco que ainda está subindo.

O PM2 inicia sozinho depois que o servidor reinicia?#

Não, a menos que você peça. São dois comandos:

pm2 startup
pm2 save

O pm2 startup detecta o sistema de init (systemd, por exemplo) e imprime o comando que registra o PM2 no boot: copie e execute esse comando (com sudo) antes do pm2 save. O pm2 save grava a lista atual de apps, e o PM2 a restaura quando o servidor sobe. Para restaurar na mão, use pm2 resurrect. Depois de atualizar o Node.js, rode pm2 unstartup e pm2 startup de novo, para o serviço apontar para o binário novo.

Como usar o PM2 dentro do Docker?#

Em contêiner (veja o que é Docker), use o pm2-runtime, um substituto do binário node que roda em primeiro plano, como um contêiner espera:

FROM node:lts
WORKDIR /app
COPY . .
RUN npm install
RUN npm install pm2 -g
CMD ["pm2-runtime", "ecosystem.config.js"]

O PM2 repassa os sinais de encerramento ao app. Escute SIGINT para fechar conexões antes de sair: o PM2 espera 1600 ms por padrão antes do SIGKILL, ajustável com kill_timeout. Para um processo por contêiner, adicione --only nome-do-app.

Na maioria dos casos, porém, o PM2 dentro do Docker é redundante: a política de restart do próprio contêiner já recria o processo que morreu.

Quando dispensar o PM2?#

O PM2 só faz sentido quando você mesmo administra a máquina, como numa VPS. Se a plataforma já reinicia o processo que parou, ele vira uma camada a mais para manter. Um contêiner sob orquestrador, um serviço do systemd com Restart=always ou uma hospedagem com reinício automático cumprem o mesmo papel.

Lembre-se de que o PM2 só recria o processo: ele não corrige o bug que derrubou o app. Registre erros e leia os logs (veja como ler os logs de um app) para achar a causa.

Como fazer isso na Square Cloud#

Na Square Cloud, o PM2 não é necessário nem recomendado. Os containers ficam sempre ligados, sem modo de suspensão. O reinício automático existe em todos os planos e vem ligado quando você faz o deploy pelo painel (num squarecloud.app escrito à mão, use AUTORESTART=true): ele religa o processo que encerra com erro.

Você faz o deploy por upload de ZIP, pela CLI, pelo GitHub ou pela extensão do VS Code. Se o app precisa de configuração, defina as variáveis de ambiente no painel: a mudança vale no próximo restart, sem rebuild. Os logs aparecem em tempo real no painel e na CLI, o que ajuda a achar o motivo de uma queda.

Uma ressalva: o reinício automático recria o processo, mas não corrige um erro de código nem um vazamento de memória. Se o app estourar a RAM alocada, ele para e não volta sozinho: aumente a memória nas configurações, inicie de novo e investigue a causa. Para ver como isso se encaixa num bot, leia como manter um bot do Discord 24/7.

Veja o que a hospedagem inclui em Recursos.