# 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.

> 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.

João Rizzon · 2026-11-07 · Servidores

---

## 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:

```bash
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:

```bash
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:

```js
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](https://docs.cpanel.net/knowledge-base/web-services/the-cpuser_service_manager-script-and-the-ubic-subsystem/).

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

```ini
# ~/.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

```bash
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:

```bash
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.

```bash
# 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:

```bash
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:

```bash
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:

```bash
* * * * * 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.

```bash
# 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.

