PM2 para Node.js e Python: como manter processos ativos e monitorados

Aprenda a iniciar aplicações, configurar reinícios automáticos, acompanhar logs e restaurar processos após reiniciar um servidor Linux.

Usar PM2 para Node.js e Python ajuda a organizar a operação de APIs, sites e automações que precisam continuar funcionando depois que a sessão SSH termina. O gerenciador mantém os processos em segundo plano e permite consultar seu estado, investigar erros e configurar a recuperação após encerramentos.

Neste tutorial, vamos administrar uma API Node.js e um worker Python em um servidor Linux com systemd. Os exemplos usam os diretórios /srv/site/api e /srv/site/worker. Ajuste os caminhos ao seu projeto e faça os testes de falha em homologação.

O que é PM2 e quando usar em aplicações Node.js e Python

O gerenciador de processos PM2 oferece comandos para iniciar, parar, reiniciar e acompanhar aplicações. Ele depende do ambiente Node.js, mas também pode executar scripts Python com o interpretador apropriado.

Imagine um site empresarial cuja API recebe solicitações de orçamento e cujo worker processa tarefas em segundo plano. Executar ambos diretamente no terminal dificulta a administração. Com o PM2, cada processo recebe um nome e fica sob supervisão, independentemente da sessão SSH.

Processo online não significa aplicação saudável. Uma API pode estar executando e retornar erros porque perdeu a conexão com o banco. Um worker pode continuar ativo sem concluir nenhuma tarefa. Por isso, combine a supervisão com verificações HTTP, acompanhamento das filas e alertas externos.

Essa abordagem atende à administração de processos em um servidor. Para avaliar necessidades de orquestração mais amplas, vale entender quando Kubernetes faz sentido e quando aumenta a complexidade.

O reinício automático de aplicações também não corrige bugs, credenciais inválidas ou dependências indisponíveis. Alta disponibilidade exige decisões adicionais sobre infraestrutura, redundância e recuperação.

Como preparar o servidor e instalar o PM2

Antes da instalação, confirme quais executáveis estão disponíveis:

node --version
npm --version
python3 --version
command -v node
command -v npm
command -v python3

Escolha uma versão LTS do Node.js com suporte vigente na data da instalação. O Node.js e o npm são necessários mesmo quando o PM2 administra apenas processos Python.

Use um usuário dedicado à aplicação, sem privilégios administrativos na execução cotidiana. Neste exemplo, ele se chama siteapp e possui um diretório pessoal persistente. Se ainda não existir, peça ao administrador que o crie conforme a política do servidor.

Um administrador pode preparar os diretórios abaixo. O comando pressupõe que o usuário e o grupo siteapp já existem:

sudo install -d -o siteapp -g siteapp /srv/site
sudo install -d -o siteapp -g siteapp /srv/site/api /srv/site/worker

Na sessão do usuário siteapp, com uma instalação do npm cujo diretório global permita escrita por esse usuário, execute:

npm install -g pm2
pm2 --version

Se ocorrer erro de permissão, ajuste a instalação do Node.js ou o prefixo global do npm. Evite administrar as aplicações alternando entre pm2 e sudo pm2: usuários diferentes podem acessar listas e ambientes distintos.

Publique os arquivos dos projetos nos diretórios preparados e instale suas dependências. Mantenha o mesmo usuário, ambiente e caminhos nas próximas etapas.

Como iniciar e administrar uma aplicação Node.js com PM2

Os comandos abaixo pressupõem uma API já implementada em server.js, configurada para escutar em 127.0.0.1:3000 e responder no endpoint /health. Se o projeto usa outros valores, adapte os exemplos.

Primeiro, valide a execução direta:

cd /srv/site/api
NODE_ENV=production PORT=3000 node server.js

Em outra sessão, teste a resposta:

curl --fail --show-error --max-time 5 http://127.0.0.1:3000/health

Depois do teste, encerre a execução manual com Ctrl+C para liberar a porta. Inicie a API com PM2 Node.js:

NODE_ENV=production PORT=3000 pm2 start /srv/site/api/server.js --name api-site --cwd /srv/site/api
pm2 list
pm2 describe api-site
curl --fail --show-error --max-time 5 http://127.0.0.1:3000/health

Os principais comandos de administração têm efeitos diferentes:

• pm2 restart api-site: interrompe e inicia novamente o processo.
• pm2 stop api-site: para a execução, mantendo a entrada na lista.
• pm2 delete api-site: para e remove a entrada da lista gerenciada.

Use esses comandos conforme a necessidade; não execute todos em sequência como parte da instalação.

O PM2 não configura domínio, HTTPS, firewall ou proxy reverso. Para disponibilizar a API publicamente, essas etapas precisam integrar o deploy. Se o projeto também utiliza contêineres, o artigo sobre padronização de ambientes com Docker complementa essa preparação.

Como executar Python com PM2 e um ambiente virtual

O cuidado principal com PM2 Python é escolher o executável que possui as dependências do projeto. Crie um ambiente virtual dentro do diretório do worker:

cd /srv/site/worker
python3 -m venv .venv
/srv/site/worker/.venv/bin/python -m pip install -r requirements.txt

O exemplo pressupõe que o projeto fornece um requirements.txt. Se usa outro mecanismo de dependências, siga o procedimento correspondente. Algumas distribuições também exigem a instalação do pacote que disponibiliza o módulo venv.

Valide o worker antes de colocá-lo sob supervisão:

/srv/site/worker/.venv/bin/python -u worker.py

Confirme que ele realiza uma tarefa de teste e encerre a execução manual. Depois, inicie:

PYTHONUNBUFFERED=1 pm2 start /srv/site/worker/worker.py --name worker-python --interpreter /srv/site/worker/.venv/bin/python --cwd /srv/site/worker
pm2 describe worker-python

O caminho absoluto do interpretador dispensa a ativação do ambiente virtual na sessão. Já cwd define o diretório de trabalho, relevante quando o código abre arquivos por caminhos relativos. A variável PYTHONUNBUFFERED=1 reduz atrasos na saída padrão e de erro.

Este fluxo serve para um worker contínuo. Para um script pontual, que termina após executar uma tarefa, use --no-autorestart ou configure autorestart: false. Caso contrário, a conclusão normal pode provocar novas execuções.

Aplicações web Python precisam de um servidor WSGI ou ASGI adequado ao framework, como Gunicorn ou Uvicorn. Nesse caso, supervise o comando desse servidor; o servidor de desenvolvimento do framework não deve substituir a configuração de produção.

Como organizar Node.js e Python no ecosystem.config.js

Centralize a configuração em /srv/site/ecosystem.config.js. Coloque esse arquivo CommonJS fora de um pacote que declare "type": "module".

module.exports = {
  apps: [
    {
      name: 'api-site',
      script: '/srv/site/api/server.js',
      cwd: '/srv/site/api',
      exec_mode: 'fork',
      instances: 1,
      watch: false,
      autorestart: true,
      min_uptime: '10s',
      max_restarts: 10,
      restart_delay: 3000,
      max_memory_restart: '300M',
      time: true,
      env_production: {
        NODE_ENV: 'production',
        PORT: '3000'
      }
    },
    {
      name: 'worker-python',
      script: '/srv/site/worker/worker.py',
      cwd: '/srv/site/worker',
      interpreter: '/srv/site/worker/.venv/bin/python',
      exec_mode: 'fork',
      instances: 1,
      watch: false,
      autorestart: true,
      min_uptime: '10s',
      max_restarts: 10,
      restart_delay: 3000,
      max_memory_restart: '300M',
      time: true,
      env_production: {
        PYTHONUNBUFFERED: '1'
      }
    }
  ]
};

Os valores de memória e reinício são exemplos e precisam de ajuste conforme a carga. Se você iniciou os processos nas etapas anteriores, faça a substituição em homologação ou em uma janela de manutenção:

pm2 delete api-site worker-python
pm2 start /srv/site/ecosystem.config.js --env production

Para reaplicar alterações posteriores:

pm2 restart /srv/site/ecosystem.config.js --env production --update-env

O parâmetro --env production seleciona as variáveis de env_production. Mantenha credenciais fora do arquivo versionado e forneça-as pelo mecanismo de segredos do ambiente. Verifique também as permissões dos arquivos persistidos pelo PM2.

Em projetos com contêineres, esse cuidado se relaciona às boas práticas de Docker em produção, embora o gerenciamento dos processos deva seguir a arquitetura escolhida.

Como configurar reinícios automáticos e retorno após o reboot

Existem duas configurações distintas: recuperar um processo encerrado e restaurar as aplicações quando o servidor reinicia.

Recuperação do processo

No arquivo anterior, autorestart habilita a recuperação e restart_delay introduz uma espera. max_restarts limita reinícios consecutivos considerados instáveis segundo min_uptime; ele não limita todos os reinícios durante a vida da aplicação.

max_memory_restart provoca recuperação quando o consumo ultrapassa o valor configurado. A verificação é periódica, portanto esse recurso não funciona como um teto rígido de memória. Investigue a causa do crescimento.

Inicialização do servidor

Na sessão do usuário siteapp, execute:

pm2 startup

O PM2 exibirá um comando com privilégios administrativos. Confira o usuário, o diretório pessoal e o caminho do Node.js antes de executá-lo. Depois, salve a lista desejada:

pm2 save

pm2 startup integra o PM2 à inicialização do Linux; pm2 save registra os processos para restauração. Salve novamente após adicionar, remover ou atualizar aplicações.

Se mudar o caminho ou a versão do Node.js, revise a integração com pm2 unstartup e pm2 startup, seguindo os comandos gerados.

Teste separadamente a recuperação de um processo descartável e o reboot de uma VPS de homologação. Após reconectar, confirme a resposta HTTP e o trabalho realizado pelo worker.

Como acompanhar status, logs, CPU e memória com PM2

Uma rotina de monitoramento de processos pode começar com:

pm2 list
pm2 describe api-site
pm2 describe worker-python
pm2 logs worker-python --lines 100
pm2 monit

Execute os comandos de acompanhamento interativo separadamente e saia com Ctrl+C. Isso encerra a visualização, mantendo as aplicações em execução.

Compare o tempo de atividade com a quantidade de reinícios. Um processo com uptime baixo e contador crescente merece investigação. Abra os logs PM2 e procure o primeiro erro: uma dependência ausente costuma ser mais útil ao diagnóstico do que as mensagens posteriores de reinicialização.

pm2 monit apresenta consumo de CPU e memória no terminal. Observe esses valores junto com volume de requisições, duração das tarefas e latência. Uma medição isolada não comprova a saúde do serviço nem substitui um histórico de métricas.

Rotação e retenção dos logs

Por padrão, os logs ficam no diretório .pm2/logs do usuário. Para evitar crescimento indefinido, configure rotação e retenção. Uma opção é instalar o módulo:

pm2 install pm2-logrotate

Ajuste tamanho, quantidade de arquivos retidos e periodicidade conforme o espaço disponível e a necessidade de investigação. Evite registrar senhas, tokens e dados pessoais. Apagar os logs não resolve a causa de um erro recorrente.

Complete o acompanhamento local com testes HTTP externos e alertas. Para o worker, monitore tarefas concluídas, falhas e tempo de espera na fila.

Restart, reload e cluster: o que muda entre Node.js e Python

restart interrompe e inicia novamente o processo. Em uma aplicação com uma única instância, isso pode causar indisponibilidade durante a retomada.

O modo cluster do PM2 utiliza recursos do Node.js. Uma API preparada para múltiplas instâncias pode alterar sua entrada no arquivo para:

exec_mode: 'cluster',
instances: 2

Depois de aplicar essa configuração, a recarga pode ser solicitada com:

pm2 reload api-site

Reload não é uma garantia universal de ausência de interrupções. A recarga pode recorrer a um reinício se não for concluída. Valide o comportamento com tráfego de teste e implemente encerramento gracioso, permitindo concluir requisições e liberar recursos.

Antes de multiplicar instâncias, revise sessões, conexões persistentes e estado em memória. Também evite que cada instância dispare a mesma tarefa agendada sem coordenação.

Para Python, a concorrência depende do servidor WSGI/ASGI ou da arquitetura dos workers. Mantenha o worker do exemplo em fork com uma instância até definir como tarefas serão distribuídas e como repetições serão tratadas.

Use watch deliberadamente. Em produção, logs, uploads e outros arquivos gerados podem provocar reinícios inesperados quando entram no conjunto observado. O exemplo mantém essa opção desabilitada.

Como resolver erros comuns e validar a configuração do PM2

Quando a aplicação funciona manualmente e falha sob supervisão, compare usuário, interpretador, diretório de trabalho e variáveis. Não presuma que o PM2 reproduz todos os detalhes da sessão em que você testou o projeto.

Para o usuário adotado neste tutorial, se o serviço gerado manteve o nome padrão:

systemctl status pm2-siteapp
journalctl -u pm2-siteapp -b --no-pager
pm2 list

Execute pm2 list como siteapp. A leitura completa do journal pode exigir acesso administrativo. Se o serviço recebeu outro nome, ajuste os comandos.

Checklist de validação

• A API responde no endpoint local e no endereço público esperado.
• O worker conclui uma tarefa de teste, com resultado verificável.
• Os processos continuam ativos após encerrar e reabrir a sessão SSH.
• Um processo descartável se recupera após uma falha simulada em homologação; pm2 stop não serve para esse teste, pois solicita uma parada administrativa.
• As aplicações desejadas retornam após reboot e mantêm o comportamento esperado.
• Logs possuem rotação, retenção e acesso adequado.
• Existem verificações externas e responsáveis definidos para responder a falhas.

Registre o usuário de operação, os caminhos, os comandos de deploy e os responsáveis pela manutenção. Para sites empresariais em Recife, esse procedimento ajuda a dar continuidade à operação além da publicação inicial. A disponibilidade também depende do banco, da rede, da infraestrutura e das demais integrações.

Seu site ou aplicação precisa de uma operação mais estável? Entre em contato com a Codephix para conversar sobre seu projeto de criação de sites em Recife e as necessidades de hospedagem, deploy e manutenção.