PM2 no SetupVibe: processos, logs e inicialização segura

Guia de gerenciamento de processos — v0.41.8

O SetupVibe instala o PM2 globalmente e o configura para inicialização automática na edição Desktop.

macOS: inicialização automática via launchd. Baixa e inicia ecosystem.config.js do repositório para ~/ecosystem.config.js
Linux: inicialização automática via systemd. Baixa e inicia ecosystem.config.js do repositório para ~/ecosystem.config.js

O que é o PM2?

O PM2 é um gerenciador de processos para Node.js em produção — mantém seus aplicativos funcionando, reinicia-os em caso de falha, gerencia logs e integra-se com sistemas de init do sistema operacional.

Conceitos principais:

Conceito	Descrição
App	Um processo gerenciado pelo PM2 (Node.js, Python, Go ou qualquer binário)
Ecosystem file	`ecosystem.config.js` — configuração declarativa para um ou mais apps
Cluster mode	Cria múltiplas instâncias entre os núcleos da CPU (somente Node.js)
Fork mode	Processo único, funciona com qualquer runtime (padrão)

Primeiros Passos

1
# Iniciar um app diretamente
2
pm2 start app.js
3

4
# Iniciar com nome
5
pm2 start app.js --name meuapp
6

7
# Iniciar usando ecosystem file
8
pm2 start ecosystem.config.js
9

10
# Iniciar um app específico do ecosystem file
11
pm2 start ecosystem.config.js --only meuapp
12

13
# Iniciar com ambiente específico
14
pm2 start ecosystem.config.js --env production
15

16
# Listar todos os processos gerenciados
17
pm2 list
18

19
# Mostrar informações detalhadas de um app
20
pm2 show meuapp
21

22
# Monitorar todos os apps em tempo real
23
pm2 monit

Comandos Comuns

Controle de Processos

1
pm2 stop meuapp         # Parar (mantém na lista)
2
pm2 restart meuapp      # Reiniciar
3
pm2 reload meuapp       # Reload sem downtime (cluster mode)
4
pm2 delete meuapp       # Parar e remover da lista
5

6
pm2 stop all            # Parar todos os apps
7
pm2 restart all         # Reiniciar todos os apps
8
pm2 delete all          # Remover todos os apps

Logs

1
pm2 logs                # Transmitir todos os logs
2
pm2 logs meuapp         # Transmitir logs de um app
3
pm2 logs --lines 200    # Mostrar as últimas 200 linhas
4
pm2 flush               # Limpar todos os arquivos de log
5
pm2 reloadLogs          # Reabrir arquivos de log (útil após rotação)

Persistência

1
pm2 save                # Salvar lista de processos atual em disco
2
pm2 resurrect           # Restaurar lista de processos salva

Inicialização

1
# Gerar e configurar integração com sistema de init
2
pm2 startup             # Exibe um comando — execute-o com sudo
3

4
# Remover hook de inicialização
5
pm2 unstartup

Ecosystem File

O ecosystem file (ecosystem.config.js) é a forma recomendada de gerenciar apps. Um template é gerado em ~/ecosystem.config.js durante a configuração.

Template Padrão

1
module.exports = {
2
  apps: [
3
    {
4
      name: "app",
5
      script: "./index.js",
6
      instances: 1,
7
      exec_mode: "fork",
8
      watch: false,
9
      ignore_watch: ["node_modules", "logs", ".git"],
10
      max_memory_restart: "300M",
11
      log_date_format: "YYYY-MM-DD HH:mm:ss",
12
      merge_logs: true,
13
      time: true,
14
      autorestart: true,
15
      max_restarts: 10,
16
      restart_delay: 1000,
17
      kill_timeout: 3000,
18
      wait_ready: false,
19
      env: {
20
        NODE_ENV: "development",
21
      },
22
      env_production: {
23
        NODE_ENV: "production",
24
      },
25
    },
26
  ],
27
};

Referência de Configuração

Geral

Opção	Tipo	Padrão	Descrição
`name`	string	nome do script	Identificador usado em `pm2 list` e comandos
`script`	string	—	Caminho para o script de entrada (obrigatório)
`cwd`	string	—	Diretório de trabalho do processo
`args`	string	—	Argumentos CLI passados ao script
`interpreter`	string	`node`	Caminho para o interpretador do runtime
`interpreter_args`	string	—	Flags passadas ao interpretador (ex: `--max-old-space-size=4096`)
`force`	boolean	`false`	Permite iniciar o mesmo script mais de uma vez

Escalabilidade

Opção	Tipo	Padrão	Descrição
`instances`	number	`1`	Número de instâncias. `-1` = todos os núcleos da CPU
`exec_mode`	string	`fork`	`fork` (qualquer runtime) ou `cluster` (somente Node.js)

Estabilidade e Reinicialização

Opção	Tipo	Padrão	Descrição
`autorestart`	boolean	`true`	Reiniciar em caso de falha
`max_restarts`	number	`10`	Máximo de reinicializações instáveis consecutivas antes de parar
`min_uptime`	string/number	—	Tempo mínimo para ser considerado estável (ms ou `"2s"`)
`restart_delay`	number	`0`	Milissegundos de espera antes de reiniciar app com falha
`max_memory_restart`	string	—	Reiniciar se RSS exceder este valor (ex: `"300M"`, `"1G"`)
`kill_timeout`	number	`1600`	Milissegundos antes de SIGKILL após SIGTERM
`shutdown_with_message`	boolean	`false`	Usar `process.send('shutdown')` em vez de SIGTERM
`wait_ready`	boolean	`false`	Aguardar `process.send('ready')` antes de considerar o app online
`listen_timeout`	number	—	Milissegundos para aguardar sinal `ready` antes de forçar reload

Watch

Opção	Tipo	Padrão	Descrição
`watch`	boolean/array	`false`	Reiniciar em mudanças de arquivo. Passe um array de caminhos
`ignore_watch`	array	—	Caminhos ou padrões glob excluídos do watch

Logging

Opção	Tipo	Padrão	Descrição
`log_date_format`	string	—	Formato do timestamp (ex: `"YYYY-MM-DD HH:mm:ss"`)
`out_file`	string	`~/.pm2/logs/<name>-out.log`	Caminho para log de stdout
`error_file`	string	`~/.pm2/logs/<name>-error.log`	Caminho para log de stderr
`log_file`	string	—	Caminho para log combinado stdout+stderr
`merge_logs` / `combine_logs`	boolean	`false`	Desabilitar sufixos de log por instância no cluster
`time`	boolean	`false`	Prefixar cada linha de log com timestamp

Ambiente

Opção	Tipo	Descrição
`env`	object	Variáveis injetadas em todos os modos
`env_<name>`	object	Variáveis injetadas com `--env <name>` (ex: `env_production`)
`filter_env`	array	Remover variáveis de ambiente global com esses prefixos
`instance_var`	string	Nome da variável com índice da instância (padrão: `NODE_APP_INSTANCE`)
`appendEnvToName`	boolean	Acrescentar nome do ambiente ao nome do app

Source Maps e Diversos

Opção	Tipo	Padrão	Descrição
`source_map_support`	boolean	`true`	Habilitar suporte a source map para stack traces
`vizion`	boolean	`true`	Rastrear metadados do controle de versão
`cron_restart`	string	—	Expressão cron para reinicializações agendadas (ex: `"0 3 * * *"`)
`post_update`	array	—	Comandos a executar após uma atualização `pm2 pull`

Configurações Globais do PM2

O SetupVibe configura as seguintes durante a instalação:

Configuração	Valor	Descrição
`pm2:autodump`	`true`	Auto-salvar lista de processos em qualquer mudança
`pm2:log_date_format`	`YYYY-MM-DD HH:mm:ss`	Formato de timestamp padrão para todos os logs

1
pm2 set pm2:autodump true
2
pm2 set pm2:log_date_format "YYYY-MM-DD HH:mm:ss"
3
pm2 get                      # Listar todas as configurações atuais do módulo PM2

Cluster Mode (Node.js)

1
{
2
  instances: "max",   // ou um número, ou -1
3
  exec_mode: "cluster",
4
}

1
pm2 reload meuapp     # Reload rolling sem downtime em cluster mode
2
pm2 scale meuapp 4    # Escalar para 4 instâncias em tempo real
3
pm2 scale meuapp +2   # Adicionar 2 instâncias

Inicialização Automática

O SetupVibe configura o PM2 para iniciar automaticamente no boot:

macOS — registra um agente launchd (pm2 startup launchd)
Linux — registra um serviço systemd (pm2 startup systemd)

Para refazer manualmente:

1
pm2 startup            # Exibe o comando a executar
2
pm2 save               # Salva a lista de processos atual

Para remover:

1
pm2 unstartup