🚨 Sistema Offline
Aprenda como diagnosticar os principais problemas quando o sistema estiver offline ou não carregar corretamente.
Antes de realizar alterações mais sensíveis na VPS, como reiniciar serviços, alterar configurações ou mexer no banco de dados, recomendamos criar um snapshot da VPS.
📑 Checklist rápido de diagnóstico
Execute os comandos abaixo na ordem para fazer uma verificação inicial:
df -h
free -h
pm2 status
docker ps -a
ss -tulpn | grep LISTEN
nginx -t
tail -100 /var/log/nginx/error.log
systemctl status postgresql
pg_lsclusters
pg_isready
Mesmo que o PM2 mostre frontend e backend como online, o sistema ainda pode ficar offline caso o PostgreSQL, Redis, Nginx ou alguma porta essencial esteja com problema.
💾 Etapa 1: Verificar espaço em disco
O primeiro passo é confirmar se a VPS ainda possui espaço disponível.
Execute:
df -h
Verifique principalmente a partição principal, normalmente /.
Exemplo de uso saudável:
/dev/sda2 99G 41G 54G 44% /
Se o uso estiver em 100%, o sistema pode parar de funcionar, o banco pode travar e os serviços podem não conseguir salvar arquivos temporários ou logs.
Se o disco estiver cheio, evite reiniciar vários serviços repetidamente antes de identificar o que está ocupando espaço. Isso pode piorar o problema.
🧠 Etapa 2: Verificar memória da VPS
Execute:
free -h
Para acompanhar os processos em tempo real, execute:
top
Ou, se estiver disponível:
htop
Verifique se algum processo está consumindo muita memória ou CPU.
Quando a VPS fica sem memória, serviços como backend, banco de dados, Redis ou containers Docker podem cair ou reiniciar automaticamente.
⚙️ Etapa 3: Verificar status dos serviços no PM2
O frontend e o backend rodam no PM2.
Execute:
pm2 status
Exemplo esperado:
┌────┬────────────────────┬──────────┬──────┬───────────┬──────────┬──────────┐
│ id │ name │ mode │ ↺ │ status │ cpu │ memory │
├────┼────────────────────┼──────────┼──────┼───────────┼──────────┼──────────┤
│ 0 │ sistema-backend │ fork │ 0 │ online │ 0% │ 150mb │
│ 1 │ sistema-frontend │ fork │ 0 │ online │ 0% │ 50mb │
└────┴────────────────────┴──────────┴──────┴───────────┴──────────┴──────────┘
Se algum serviço estiver com status como:
errored
stopped
stopping
launching
ou reiniciando muitas vezes, provavelmente há erro na aplicação ou em algum serviço dependente.
📜 Etapa 4: Verificar logs do PM2
Para ver os logs gerais, execute:
pm2 logs
Para ver os logs apenas do backend:
pm2 logs NOME DO SEU BACKEND
Exemplo:
pm2 logs sistema-backend
Para ver mais linhas diretamente pelo arquivo de log:
tail -100 /root/.pm2/logs/sistema-backend-error.log
E também:
tail -100 /root/.pm2/logs/sistema-backend-out.log
Procure erros como:
ECONNREFUSED
SequelizeConnectionError
password authentication failed
database does not exist
Redis connection refused
EADDRINUSE
MODULE_NOT_FOUND
🔎 Significado dos erros mais comuns
| Erro | Possível causa |
|---|---|
ECONNREFUSED | Algum serviço necessário está parado. |
SequelizeConnectionError | Backend não conseguiu conectar ao PostgreSQL. |
password authentication failed | Senha do banco incorreta. |
database does not exist | Banco de dados não existe ou o nome está incorreto. |
Redis connection refused | Redis está parado ou inacessível. |
EADDRINUSE | Porta já está em uso por outro processo. |
MODULE_NOT_FOUND | Dependência ausente no projeto. |
💾 Verificar e limpar o espaço ocupado pelos logs
Logs muito grandes podem ocupar todo o disco da VPS e fazer o sistema parar de funcionar. Para verificar o tamanho dos logs do PM2, execute:
du -sh /root/.pm2/logs
Para descobrir quais arquivos estão ocupando mais espaço:
du -ah /root/.pm2/logs | sort -h
Também verifique os logs do Nginx e o espaço usado pelo journald:
du -sh /var/log/nginx 2>/dev/null
journalctl --disk-usage
Se os logs do PM2 estiverem ocupando muito espaço, limpe o conteúdo deles com:
pm2 flush
O comando remove o conteúdo dos logs do PM2, mas mantém os arquivos e os serviços em execução. Depois, confirme o espaço liberado:
du -sh /root/.pm2/logs
df -h
Para reduzir logs antigos do journald, mantendo somente os registros dos últimos 7 dias, execute:
journalctl --vacuum-time=7d
Antes de limpar, confira o tamanho dos logs e, se houver um erro em investigação, salve ou copie os arquivos relevantes. Não apague manualmente todo o conteúdo de /var/log, pois alguns serviços precisam desses arquivos para continuar registrando eventos corretamente.
🔄 Etapa 5: Reiniciar serviços do PM2
Se os serviços estiverem online, mas o sistema não responder corretamente, tente reiniciar:
pm2 restart all
Ou reinicie apenas o backend:
pm2 restart NOME DO SEU BACKEND
Exemplo:
pm2 restart sistema-backend
Depois confira novamente:
pm2 status
Se o serviço voltar a cair após reiniciar, verifique os logs antes de continuar. Reiniciar várias vezes sem analisar o erro pode dificultar o diagnóstico.
🐳 Etapa 6: Verificar containers Docker
O sistema usa serviços no Docker, como Redis, n8n, WuzAPI ou outros, execute:
docker ps
Para ver todos os containers, inclusive os parados:
docker ps -a
Verifique se algum container importante está com status:
Exited
Restarting
Created
O status esperado é algo como:
Up 4 weeks
📦 Etapa 7: Verificar logs de containers Docker
Para ver os logs de um container:
docker logs nome-do-container --tail 100
Exemplo:
docker logs redis-sistema --tail 100
Para acompanhar os logs em tempo real:
docker logs nome-do-container -f
Para sair dos logs:
CTRL + C
🌐 Etapa 8: Verificar se as portas estão ativas
Execute:
ss -tulpn | grep LISTEN
Ou filtre apenas processos Node:
ss -tulpn | grep node
Exemplo esperado:
tcp LISTEN 0 511 0.0.0.0:4000 0.0.0.0:* users:(("node",pid=1234))
tcp LISTEN 0 511 *:3000 *:* users:(("node",pid=5678))
Neste exemplo:
- Porta 3000: frontend;
- Porta 4000: backend.
As portas podem variar de acordo com a instalação. Por isso, compare as portas exibidas com as configurações do PM2 e do Nginx.
🧪 Etapa 9: Testar o frontend
Se o frontend estiver na porta 3000, execute no terminal da sua VPS:
curl -I http://127.0.0.1:3000
Resposta esperada:
HTTP/1.1 200 OK
Se retornar 200 OK, significa que o frontend está respondendo localmente na VPS.
🧪 Etapa 10: Testar o backend
Se o backend estiver na porta 4000, execute:
curl -I http://127.0.0.1:4000
Resposta esperada:
HTTP/1.1 403 Forbidden
Se o comando ficar travado ou demorar muito, pode haver problema no backend, banco de dados ou em algum serviço dependente.
🧭 Etapa 11: Verificar configuração do Nginx
Liste os sites configurados:
ls /etc/nginx/sites-enabled
Depois veja para quais portas o Nginx está apontando:
grep -R "proxy_pass" /etc/nginx/sites-enabled /etc/nginx/conf.d
Exemplo:
/etc/nginx/sites-enabled/sistema-backend: proxy_pass http://127.0.0.1:4000;
/etc/nginx/sites-enabled/sistema-frontend: proxy_pass http://127.0.0.1:3000;
Confirme se as portas configuradas no Nginx são as mesmas portas onde o frontend e o backend estão rodando.
✅ Etapa 12: Testar configuração do Nginx
Execute:
nginx -t
Resposta esperada:
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
Se estiver tudo certo, você pode reiniciar o Nginx:
systemctl restart nginx
Reinicie o Nginx somente depois de validar a configuração com nginx -t.
📜 Etapa 13: Verificar logs do Nginx
Execute:
tail -100 /var/log/nginx/error.log
Alguns erros comuns:
upstream timed out
connect() failed (111: Connection refused)
upstream prematurely closed connection
🔎 O que esses erros indicam
| Erro no Nginx | Possível causa |
|---|---|
upstream timed out | Backend demorou demais para responder. |
connect() failed (111: Connection refused) | Nginx tentou acessar uma porta onde não havia serviço ativo. |
upstream prematurely closed connection | Backend caiu ou reiniciou durante a requisição. |
Se aparecerem muitos erros apontando para o backend, por exemplo:
upstream: "http://127.0.0.1:4000"
significa que o problema provavelmente está no backend ou em algum serviço que ele depende, como PostgreSQL ou Redis.
🐘 Etapa 14: Verificar PostgreSQL
Para verificar o status geral do serviço PostgreSQL, execute:
systemctl status postgresql
Esse comando mostra se o serviço principal do PostgreSQL está ativo no sistema.
Em alguns casos, o comando systemctl status postgresql pode mostrar o serviço como ativo, mas isso não garante que o cluster real do banco esteja online.
Por isso, também é importante verificar os clusters do PostgreSQL com:
pg_lsclusters
Exemplo de problema:
Ver Cluster Port Status Owner Data directory Log file
14 main 5432 down postgres /var/lib/postgresql/14/main /var/log/postgresql/postgresql-14-main.log
Neste caso, o PostgreSQL está com o cluster 14/main parado.
Isso pode fazer o sistema ficar offline, mesmo com PM2, Nginx e Docker aparentemente funcionando.
Para confirmar se o PostgreSQL está aceitando conexões, execute:
pg_isready
Resposta esperada quando estiver funcionando:
/var/run/postgresql:5432 - accepting connections
▶️ Etapa 15: Subir o cluster do PostgreSQL
Se o pg_lsclusters mostrar o cluster como down, execute:
systemctl start postgresql@14-main
Depois confira novamente:
pg_lsclusters
O resultado esperado é:
Ver Cluster Port Status Owner Data directory Log file
14 main 5432 online postgres /var/lib/postgresql/14/main /var/log/postgresql/postgresql-14-main.log
Depois teste:
pg_isready
Resposta esperada:
/var/run/postgresql:5432 - accepting connections
🔄 Etapa 16: Reiniciar backend após subir o banco
Depois que o PostgreSQL estiver online, reinicie o backend:
pm2 restart NOME DO SEU BACKEND
Exemplo:
pm2 restart sistema-backend
Depois confira:
pm2 status
Por fim, teste o sistema novamente no navegador.
🧩 Caso comum: sistema offline com PM2 online
Pode acontecer de o PM2 mostrar frontend e backend como online, mas mesmo assim o sistema não funcionar.
Exemplo:
pm2 status
sistema-backend online
sistema-frontend online
Nesse caso, primeiro verifique o status do PostgreSQL:
systemctl status postgresql
Depois verifique os clusters:
pg_lsclusters
Se aparecer:
14 main 5432 down
o problema está no banco de dados.
Para resolver, execute:
systemctl start postgresql@14-main
Depois confira novamente:
pg_lsclusters
Em seguida, reinicie o backend:
pm2 restart sistema-backend
⚠️ Possíveis causas quando o PostgreSQL está parado
O PostgreSQL pode parar por alguns motivos, como:
- Reinício inesperado da VPS;
- Falta temporária de memória;
- Falha no processo do banco;
- Atualização ou manutenção incompleta;
- Problemas no disco;
- Falha durante o boot da VPS;
- Travamento do serviço.
Sempre verifique o log do PostgreSQL se o cluster não subir:
tail -100 /var/log/postgresql/postgresql-14-main.log
E veja o status específico do cluster:
systemctl status postgresql@14-main --no-pager
🧭 Fluxo recomendado de solução
Siga esta ordem para diagnosticar o problema:
- Verifique se a VPS tem disco e memória disponíveis.
- Verifique se frontend e backend estão online no PM2.
- Verifique se os containers Docker estão ativos.
- Verifique se as portas do frontend e backend estão ouvindo.
- Teste o frontend localmente com
curl. - Teste o backend localmente com
curl. - Verifique se o Nginx está apontando para as portas corretas.
- Veja os logs do Nginx.
- Verifique o status do PostgreSQL com
systemctl status postgresql. - Verifique os clusters do PostgreSQL com
pg_lsclusters. - Se o banco estiver
down, suba o cluster correto. - Reinicie o backend no PM2.
- Teste o sistema novamente no navegador.
📌 Comandos principais
Ver PM2
pm2 status
Reiniciar PM2
pm2 restart all
Ver Docker
docker ps -a
Ver Nginx
systemctl status nginx
nginx -t
Ver logs do Nginx
tail -100 /var/log/nginx/error.log
Ver status do PostgreSQL
systemctl status postgresql
Ver clusters do PostgreSQL
pg_lsclusters
Subir PostgreSQL
systemctl start postgresql@14-main
Ver se o PostgreSQL aceita conexão
pg_isready
Reiniciar backend
pm2 restart nome-do-backend
✅ Finalização
Pronto! Agora você já sabe como diagnosticar os principais problemas quando o sistema estiver offline.
Nem sempre o problema está no PM2. Mesmo que o frontend e o backend estejam online, o sistema pode ficar indisponível se o banco de dados, Nginx, Docker, Redis ou alguma porta essencial estiver com problema.
Por isso, sempre siga o diagnóstico por etapas e valide cada serviço antes de aplicar alterações mais sensíveis na VPS.