sudo systemctl status nginx --no-pager
sudo nginx -t

Se nginx -t der erro, normalmente ele informa o arquivo e o número da linha, por exemplo:

nginx: [emerg] invalid number of arguments in "proxy_pass" directive in /etc/nginx/sites-enabled/app.conf:18

Nesse momento, não adivinhe: abra diretamente o arquivo e a linha correspondentes.

Fluxo de publicação recomendado:

sudo nginx -t
sudo systemctl reload nginx

Não é recomendado começar com:

sudo systemctl restart nginx

Quando reload falha, os workers antigos geralmente continuam ativos e o serviço em produção pode não ser interrompido; quando restart falha, pode simplesmente não haver nenhum processo do Nginx atendendo.

Veja os logs:

sudo journalctl -u nginx -n 100 --no-pager
sudo tail -n 100 /var/log/nginx/error.log

Estrutura comum no Ubuntu / Debian:

/etc/nginx/nginx.conf
/etc/nginx/conf.d/*.conf
/etc/nginx/sites-available/
/etc/nginx/sites-enabled/

Liste os sites habilitados:

ls -l /etc/nginx/sites-enabled/

Problemas comuns:

• Há um link simbólico quebrado em sites-enabled;
• O mesmo server_name está escrito várias vezes;
• Vários sites escutam na mesma porta, mas não há site padrão;
• A ordem de carregamento dos nomes de arquivo faz a configuração padrão corresponder primeiro.

Você pode usar:

sudo nginx -T | less

Para ver a configuração completa como o Nginx realmente a carrega.

Se o navegador abre o site padrão, um site antigo ou um 404, verifique primeiro:

server {
    listen 80;
    server_name example.com www.example.com;
}

Também confirme que o DNS aponta para o VPS atual:

dig +short example.com

Se você também tem IPv6, não esqueça o registro AAAA. Às vezes o registro A está correto, mas o AAAA ainda aponta para a máquina antiga, causando problemas de acesso para alguns usuários.

Um erro comum em sites estáticos é entender errado como os caminhos de root / alias são concatenados.

Para cenários simples, use root:

location / {
    root /var/www/site;
    try_files $uri $uri/ =404;
}

alias é mais adequado para mapear um prefixo de URL para um diretório completamente diferente:

location /uploads/ {
    alias /data/uploads/;
}

A barra final em alias é importante; se escrita errada, causa 404 ou concatenação de caminho anormal.

Configuração comum de proxy reverso:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Diagnostique o backend:

curl -I http://127.0.0.1:3000
sudo ss -lntup | grep 3000

Se o backend não estiver escutando, o Nginx retornará 502 por mais correta que esteja a configuração.

Para um diagnóstico mais detalhado de 502/504, veja:

• O que fazer quando aparece 502 / 504 Bad Gateway no VPS (2026): checklist de diagnóstico de Nginx, PHP-FPM, Gunicorn e timeout do upstream

Erros comuns na configuração de certificados:

ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

Verifique se os arquivos existem:

sudo ls -l /etc/letsencrypt/live/example.com/

Verifique a renovação:

sudo certbot renew --dry-run

Caminho de certificado errado, domínio incompatível ou porta 80 bloqueada podem fazer a configuração HTTPS não entrar em vigor ou o reload falhar.

Confirme se o Nginx está escutando:

sudo ss -lntup | egrep ':80|:443'

Se a porta estiver ocupada pelo Apache, Caddy ou outro Nginx, os logs normalmente mostram bind() to 0.0.0.0:80 failed.

Verifique o UFW:

sudo ufw status verbose

Libere HTTP/HTTPS:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Verifique também o security group do provedor de nuvem; caso contrário, mesmo que a máquina local libere, o acesso externo pode continuar falhando.

Faça backup antes de cada alteração de configuração:

sudo cp /etc/nginx/sites-available/app.conf /etc/nginx/sites-available/app.conf.bak.$(date +%F-%H%M)

Ordem de publicação:

sudo nginx -t
sudo systemctl reload nginx
curl -I https://example.com

Se falhar, faça rollback:

sudo cp /etc/nginx/sites-available/app.conf.bak.时间戳 /etc/nginx/sites-available/app.conf
sudo nginx -t
sudo systemctl reload nginx

Não fique adivinhando e alterando na máquina de produção. Mantenha cada alteração e comando de rollback no histórico do shell ou em um registro de mudanças; o diagnóstico futuro será muito mais rápido.

1. sudo nginx -t para ver o arquivo e o número da linha;
2. journalctl -u nginx -n 100 para ver os erros do systemd;
3. tail /var/log/nginx/error.log para ver os erros de execução;
4. nginx -T para ver a configuração final carregada;
5. Verifique os links simbólicos de sites-enabled;
6. Verifique server_name e o DNS;
7. Verifique root/alias ou proxy_pass;
8. Verifique os caminhos dos certificados e o certbot;
9. Verifique a escuta em 80/443, o firewall e o security group;
10. Se necessário, faça rollback a partir do backup.

Leitura complementar:

• O serviço do VPS iniciou, mas não é acessível pela internet (2026): como diagnosticar portas, firewall, security group e endereço de escuta
• O que fazer quando a renovação do certificado Let's Encrypt falha no VPS (2026): checklist de certbot, Cloudflare, DNS-01 e porta 80

O princípio central para erros de configuração do Nginx é: primeiro nginx -t, depois reload, não restart diretamente. Para erros de sintaxe, veja o número da linha; para erros de execução, veja error.log; para problemas de proxy reverso, veja a escuta do backend; para problemas de HTTPS, veja os caminhos dos certificados e a acessibilidade das portas 80/443. Fixar o processo de publicação e rollback é mais confiável do que adivinhar a configuração na hora.