blog
Servidores

Node some no reboot: Passenger, ubic ou linger

A diferença entre processo iniciado na mão, app que o Passenger recria sob demanda e serviço realmente habilitado no boot, com a verificação por CLI de cada caso.

JR · · 7 min de leitura · 2 tabelas · 11 blocos de código

Resposta curta: Node em Linux tem três regimes de persistência: processo iniciado na mão morre no reboot; app no Passenger só volta quando chega a primeira requisição; serviço habilitado com systemd --user e linger (ou ubic no cPanel) sobe sozinho no boot, sem ninguém logar.

Neste artigo
  1. Três regimes que parecem iguais no `ps` e só o reboot separa
  2. Por que o Passenger só levanta o app quando chega requisição
  3. Worker sem HTTP no cPanel: `cpuser_service_manager` e o subsistema ubic
  4. Em VPS, `systemd --user` sem linger morre junto com a sessão
  5. Provar por CLI que o processo subiu no boot, e não no seu login
  6. Do sintoma à causa: tabela de diagnóstico
  7. Quando um cron de guarda basta e você não precisa de serviço nenhum
  8. Como desfazer tudo sem derrubar o site

Três regimes que parecem iguais no `ps` e só o reboot separa

Um processo visível em ps aux pode estar em um de três regimes completamente diferentes de persistência. O terminal não mostra a diferença, mas o reboot mostra.

Regime Quem sobe o processo Sobrevive a logout Sobrevive a reboot Sobrevive a crash
Iniciado na mão (node app.js &, nohup, screen) Você Depende (nohup/screen sim, shell job não) Não Não
Passenger via Application Manager (cPanel) O Passenger, na primeira requisição HTTP Sim Sim, mas só quando chega requisição Recria no próximo request, se o app conseguir subir
Serviço habilitado (systemd --user com linger, ou ubic no cPanel) O init do sistema, no boot Sim Sim, sem requisição nenhuma Sim, com Restart= configurado

A pergunta "a aplicação Node parou depois que o servidor reiniciou" quase sempre é o primeiro regime disfarçado de terceiro. O app ficou meses no ar porque ninguém reiniciou a máquina, não porque alguém o habilitou.

Quem sobe o processo em cada regimeInício manualMorre no reboot, sem supervisorPassenger sob demandaSobe só na primeira requisiçãoServiço declaradoSobe no boot, sem requisição
Os três regimes aparecem iguais no ps e só o reboot os separa.

Por que o Passenger só levanta o app quando chega requisição

No cPanel, o Application Manager registra a aplicação no Phusion Passenger sob o Apache/EA4. O modelo é de spawn sob demanda: o processo da aplicação nasce quando chega uma requisição para o domínio ou caminho mapeado, e pode ser desligado por ociosidade. Isso tem duas consequências práticas.

Primeira: depois de um reboot, a aplicação só "volta" quando alguém a acessa. Se você mediu com curl e deu certo, foi o seu próprio curl que a levantou. Se o app tem um worker interno de fila ou um cron em processo, ele ficou parado até a primeira visita.

Segunda: quando o app falha ao subir, o Passenger não entra em loop de restart indefinido útil para você. Ele responde erro e registra o stack trace. O lugar de ler é o stderr.log do diretório da aplicação, além do error log do domínio:

tail -n 100 ~/nodeapp/stderr.log
tail -n 100 ~/logs/meudominio.com.br.error.log

Sinais típicos nesse arquivo: Cannot find module (dependência instalada fora do ambiente virtual correto) e MODULE_NOT_FOUND em app.js quando o entrypoint registrado no Application Manager não bate com o arquivo real.

O EADDRINUSE aparece de vez em quando e costuma ser mal diagnosticado. O loader Node do Passenger faz monkey-patch de server.listen: ele intercepta a chamada, descarta a porta que você passou e pluga o servidor no socket que o próprio Passenger já criou. Ou seja, porta fixa no código normalmente não gera conflito nenhum, porque aquela porta nunca chega a ser aberta.

Quando o erro aparece mesmo assim, olhe para fora do http.Server: outro processo da conta já ocupando a porta (uma instância antiga do worker, um deploy anterior que ficou de pé), ou um socket aberto direto por net.createServer(), dgram.createSocket() ou por uma biblioteca de métricas e debug, que o patch do Passenger não cobre. Confirme quem está com a porta antes de mexer no código:

ss -ltnp | grep ':3000'
pgrep -af 'node .*app\.js'

Usar a variável de ambiente continua sendo a forma correta de escrever o código, para rodar igual sob Passenger e fora dele, mas não espere que isso cure um EADDRINUSE causado por outro processo:

const port = process.env.PORT || 3000;
app.listen(port);

Worker sem HTTP no cPanel: `cpuser_service_manager` e o subsistema ubic

Para processos que precisam existir sem requisição HTTP (worker de fila, consumidor de AMQP, bot), o cPanel documenta um subsistema próprio de serviços por usuário. O script é o cpuser_service_manager, que opera sobre o subsistema ubic, conforme a documentação oficial do cPanel.

Esse é o ponto que separa um worker que volta do que não volta: o ubic é o que mantém o serviço do usuário declarado e supervisionado pelo servidor, em vez de depender de um processo solto na sessão de quem fez o deploy. Consulte a página acima para a sintaxe exata do script e os serviços suportados na sua versão do painel, porque o conjunto varia entre releases.

Em hospedagem compartilhada, nem todo comando do subsistema está liberado para o usuário final. Antes de desenhar a arquitetura em cima dele, confirme com o provedor o que está habilitado na sua conta. Se não estiver, a alternativa honesta não é gambiarra com screen: é um cron de verificação (ver seção final) ou um VPS.

Em VPS, `systemd --user` sem linger morre junto com a sessão

Em VPS com acesso root ou com sudo, o caminho limpo é um unit de usuário. Ele roda com os privilégios da conta, lê o ambiente dela e não exige escrever em /etc/systemd/system.

O unit de usuário e os dois campos que o derrubam em produção

# ~/.config/systemd/user/meuworker.service
[Unit]
Description=Worker de fila

[Service]
Type=simple
WorkingDirectory=%h/app
Environment=NODE_ENV=production
ExecStart=%h/.nvm/versions/node/v20.11.1/bin/node worker.js
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

Dois detalhes que derrubam esse unit em produção. O ExecStart precisa de caminho absoluto: o systemd não resolve node pelo PATH do seu .bashrc, e shims de nvm não existem no ambiente dele. E WantedBy=default.target, não multi-user.target, porque o alvo padrão da instância de usuário é outro.

Repare no que não está ali: nenhum After=network-online.target. Esse alvo pertence à instância de sistema do systemd, e a instância de usuário não enxerga nem ordena contra units de outra instância. Escrever a linha não gera erro, só é ignorada, e você fica com a falsa sensação de que a rede está pronta quando o processo sobe. Se o worker precisa mesmo de rede ativa no primeiro segundo, há dois caminhos: um unit de sistema em /etc/systemd/system com After=network-online.target e User=, ou aceitar que o processo pode nascer antes da rede e deixar o Restart=on-failure com RestartSec=5 reciclar até conectar. A segunda opção é a que o unit acima adota: o worker tenta, falha, o systemd o traz de volta cinco segundos depois.

Habilitar o serviço para o boot

systemctl --user daemon-reload
systemctl --user enable --now meuworker.service

Ligar o linger, a linha que falta na maioria dos deploys

Sem linger, a instância systemd --user é criada no login e destruída quando a última sessão do usuário fecha. O serviço "habilitado" morre junto e não é recriado no boot. Com linger, o systemd instancia o gerenciador do usuário no boot, sem sessão nenhuma:

sudo loginctl enable-linger $USER

Essa é a linha que mais falta nos deploys que "param quando eu saio do SSH".

Provar por CLI que o processo subiu no boot, e não no seu login

Teste de verdade é reboot. Mas antes dele, quatro checagens separam estado declarado de estado real.

# 1. Está declarado para o boot?
systemctl --user is-enabled meuworker.service
# esperado: enabled

# 2. Está rodando agora?
systemctl --user is-active meuworker.service
# esperado: active

# 3. O usuário tem linger? (sem isto, 1 e 2 são ilusão pós-reboot)
loginctl show-user "$(id -u)" -p Linger
# esperado: Linger=yes

A quarta é a que prova quem subiu o processo. Compare o horário de início do PID com o uptime da máquina:

uptime -s
ps -o lstart= -p "$(systemctl --user show -p MainPID --value meuworker.service)"

Se o lstart do processo é praticamente o mesmo instante do uptime -s, ele subiu no boot. Se é o horário em que você abriu o SSH, ele subiu porque você logou, e o reboot seguinte vai derrubá-lo. Esse par de comandos também denuncia restart silencioso: um processo bem mais novo que o uptime, num serviço que você nunca reiniciou, significa que o Restart=on-failure está trabalhando e algo está crashando.

Para ver o histórico dessas mortes:

journalctl --user -u meuworker.service -n 200 --no-pager
systemctl --user show -p NRestarts --value meuworker.service
Quatro checagens antes do reboot de testeis-enabledDeclarado para o bootis-activeRodando agoraLingerLinger=yes no loginctllstart vs uptimeSubiu no boot ou no login
Sequência de checagens que separa estado declarado de estado real.

Do sintoma à causa: tabela de diagnóstico

Sintoma Causa provável Verificação
App Node some após reboot, volta ao acessar o site Passenger sob demanda, não é serviço de boot ps -o lstart= posterior ao primeiro acesso
Worker morre ao fechar o SSH Falta enable-linger loginctl show-user UID -p Linger
is-enabled retorna enabled, mas nada roda após reboot Linger ausente ou WantedBy errado Conferir Linger=yes e default.target
status=203/EXEC no journal Caminho do binário inválido no ExecStart command -v node e usar o caminho absoluto
EADDRINUSE no stderr.log Outro processo ocupando a porta, ou socket aberto fora do http.Server (o patch do Passenger só cobre server.listen) ss -ltnp e pgrep -af node para achar o dono da porta
Cannot find module só em produção npm install rodado fora do ambiente do app Reinstalar pelo ambiente virtual do Application Manager

Quando um cron de guarda basta e você não precisa de serviço nenhum

Se a conta é compartilhada e o subsistema de serviços não está disponível, um cron de guarda resolve o caso do worker que precisa estar sempre no ar, com granularidade de um minuto. Não é supervisor, é rede de proteção, e o próprio comando deixa isso explícito:

* * * * * pgrep -f "node /home/usuario/app/worker.js" >/dev/null || /home/usuario/.nvm/versions/node/v20.11.1/bin/node /home/usuario/app/worker.js >> /home/usuario/logs/worker.log 2>&1

Riscos reais dessa abordagem: pgrep -f com padrão curto demais casa com o próprio shell do cron e nunca reinicia nada, então teste o padrão na mão antes; e o log cresce sem rotação, então aponte para um arquivo com logrotate configurado ou descarte o stdout.

O caminho do interpretador é o mesmo do ExecStart da seção anterior, e por motivo idêntico: o cron também não carrega o seu .bashrc nem os shims do nvm. Se a conta não usa nvm e sim o Node do sistema ou o do ambiente do Application Manager, troque o caminho pelo que sair de readlink -f "$(command -v node)" rodado dentro do ambiente certo. Não presuma /usr/bin/node: em host com nvm esse arquivo pode não existir, ou apontar para uma versão diferente da que você testou.

E o conselho que vai contra a venda de plano maior: se a aplicação é um site HTTP puro, sem fila nem job em processo, o comportamento sob demanda do Passenger é suficiente e não há nada a corrigir. O problema só existe quando algo precisa rodar sem que chegue requisição. Decida por isso, não pelo desconforto de ver o ps vazio depois do reboot.

Como desfazer tudo sem derrubar o site

Tudo acima é reversível sem downtime de site.

# desabilitar o serviço de usuário
systemctl --user disable --now meuworker.service

# desligar o linger (o gerenciador do usuário volta a morrer no logout)
sudo loginctl disable-linger $USER

# remover o unit
rm ~/.config/systemd/user/meuworker.service
systemctl --user daemon-reload

No cPanel, desregistrar a aplicação no Application Manager derruba o mapeamento do Passenger e o domínio volta a servir o document root estático. Guarde o stderr.log antes, porque ele é o único lugar com o stack trace de quando o app não subiu.

Referências

  1. Documentação oficial (cpanel) — The cpuser_service_manager Script and the ubic Subsystem. Consultado em 2026-10-08.
Leia também