Problemas comuns¶

Quando algo quebrar, siga a cadeia de fora para dentro: túnel → Nginx → API → banco. Descubra em qual elo está o problema antes de mexer em qualquer coisa.

Diagnóstico rápido¶

Na VM:

systemctl is-active postgresql braggo-api nginx cloudflared

Quem não aparecer como active é o suspeito. Veja o log dele com sudo journalctl -u NOME -n 80 --no-pager.

Para isolar a camada com problema:

curl -I http://127.0.0.1:5000/api/ROTA     # API direto
curl -I http://localhost/                  # Nginx + front
curl -i http://localhost/api/ROTA          # Nginx + API

Se a API direta funciona e a via Nginx não, o problema é a configuração do Nginx. Se o localhost funciona e o domínio não, o problema é o túnel ou o DNS.

Tabela de sintomas¶

Sintoma	Causa provável	O que fazer
Domínio não abre, erro 1033 ou 1016 da Cloudflare	túnel desconectado	`sudo systemctl status cloudflared`; reinicie com `sudo systemctl restart cloudflared`; confira se está Healthy no painel
Domínio dá erro 502 ou 530	túnel conectado, mas aponta para algo que não responde	confira se a rota publicada é `HTTP` → `localhost:80` e se o Nginx está ativo
Site abre, mas `/api/...` dá 502 Bad Gateway	Nginx não consegue falar com a API	`systemctl status braggo-api`; confirme a porta em `ASPNETCORE_URLS` e no `proxy_pass`
`/api/...` dá 404	prefixo errado no `proxy_pass`	veja a explicação do `proxy_pass` com e sem barra em Frontend e Nginx
Atualizar a página em uma rota do Angular dá 404	falta o `try_files ... /index.html`	confira o bloco `location /` do Nginx
Tela em branco depois do deploy	JS antigo em cache ou build na pasta errada	`Ctrl+F5`; confira se `index.html` está direto em `/var/www/braggo` (e não em uma subpasta `browser`)
Nginx devolve 403	permissão da pasta do front	`sudo chmod -R u=rwX,go=rX /var/www/braggo`
API cai logo ao iniciar	erro de configuração ou banco	`sudo journalctl -u braggo-api -n 80 --no-pager` e procure a primeira exceção
`status=203/EXEC` no systemd	caminho do `dotnet` ou da `.dll` errado	`which dotnet`; confira o nome da DLL em `/opt/braggo/api`; ajuste o `ExecStart` e rode `daemon-reload`
`Permission denied` ao ler arquivos	usuário `braggo` sem acesso	`sudo chmod -R u=rwX,go=rX /opt/braggo/api` e confira `ls -ld /opt/braggo` (grupo `braggo`)
`password authentication failed`	senha da connection string não bate com a do banco	veja `/etc/braggo/api.env`; para trocar a senha: `sudo -u postgres psql -c "ALTER USER braggo_user WITH PASSWORD 'NOVA';"`
`Connection refused` na porta 5432	PostgreSQL parado	`sudo systemctl start postgresql`
Cabeçalhos errados ou redirecionamento infinito para HTTPS	API não lê `X-Forwarded-Proto`	veja o `UseForwardedHeaders` em Deploy da API
Upload falha com 413	arquivo maior que o limite do Nginx	aumente `client_max_body_size` e recarregue
Não consigo mais conectar por SSH	IP da VM mudou	veja o IP no console da VM (`ip -br a`) e fixe o IP
Tudo parou depois de reiniciar o Windows	a VM não subiu	inicie a VM no VMware; veja a opção de iniciar junto com o Windows em Servidor base
Disco cheio	logs ou backups acumulados	`df -h`; `sudo journalctl --vacuum-time=14d`; revise `/var/backups/braggo`
Todos os usuários foram deslogados	`Jwt__Key` foi trocada	esperado; é só entrar de novo
`relation "..." does not exist` no log da API	banco sem tabelas ou migration não aplicada	aplique as migrations
Erro 500 com "não configurada" no log	variável ausente no `.env`	adicione em `/etc/braggo-api.env` e reinicie (Configuração)
E-mail não chega, ou o link abre `localhost`	domínio sem verificar, `From` ou `App__UrlFrontend` errados	E-mail (Resend)
Cloudflare mostra `Invalid nameservers`	Registro.br ainda em transição (cerca de 1h15)	esperar e usar Check nameservers
`/swagger` ou `/hangfire` abrem a tela do app	fallback do Nginx para o Angular	normal; para acessar de verdade, Acesso administrativo
`ls` em `/var/backups/braggo` dá `Permission denied`	a pasta é `700` (só root)	use `sudo`

Comandos de investigação¶

# o que está escutando em quais portas
sudo ss -tlnp

# log do Nginx
sudo tail -n 50 /var/log/nginx/error.log
sudo tail -n 50 /var/log/nginx/access.log

# espaço em disco e memória
df -h
free -h

# últimos erros da API
sudo journalctl -u braggo-api -p err -n 50 --no-pager

Quando nada resolve¶

Reverta a API com o rollback.
Se foi uma atualização do sistema, volte o snapshot da VM.
Se o banco foi corrompido, restaure o backup.

É por isso que snapshot antes de mudança grande e backup copiado para fora da VM valem o trabalho.