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.

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
- Três regimes que parecem iguais no `ps` e só o reboot separa
- Por que o Passenger só levanta o app quando chega requisição
- Worker sem HTTP no cPanel: `cpuser_service_manager` e o subsistema ubic
- Em VPS, `systemd --user` sem linger morre junto com a sessão
- Provar por CLI que o processo subiu no boot, e não no seu login
- Do sintoma à causa: tabela de diagnóstico
- Quando um cron de guarda basta e você não precisa de serviço nenhum
- 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.
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
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
- Documentação oficial (cpanel) — The cpuser_service_manager Script and the ubic Subsystem. Consultado em 2026-10-08.