Solucionando Erros Comuns do Nginx: Um Guia Prático

Solucionar erros comuns do Nginx fica muito mais fácil quando você para de tratar o código de status como o problema inteiro. Um 502 pode ser um aplicativo travado, um caminho de socket errado ou um backend que retornou cabeçalhos quebrados. Um 403 pode ser permissões de arquivo, um arquivo de índice ausente ou uma regra de negação que correspondeu a mais do que você esperava.

Comece com evidências: o log de erros, o log de acesso, nginx -t e os logs do backend se o Nginx estiver fazendo proxy para um aplicativo. Adivinhar apenas pela página do navegador perde tempo.

Comece com as Verificações Rápidas

Execute estes comandos antes de alterar a configuração:

sudo nginx -t
sudo systemctl status nginx --no-pager
sudo tail -n 80 /var/log/nginx/error.log
sudo tail -n 80 /var/log/nginx/access.log

nginx -t informa se a configuração pode ser analisada. O status do serviço informa se o Nginx está em execução. Os logs informam o que o Nginx viu ao processar a solicitação.

Se o problema estiver vinculado a uma URL, reproduza-o com curl para ver os cabeçalhos e o status claramente:

curl -I https://example.com/problem/path
curl -v https://example.com/problem/path

Se o problema ocorrer apenas para um nome de host específico, inclua-o:

curl -I -H 'Host: app.example.com' http://127.0.0.1/

Isso separa o roteamento do Nginx do comportamento de DNS, CDN e balanceador de carga.

O Nginx Não Inicia ou Recarrega

Uma falha na inicialização geralmente é um erro de sintaxe, diretiva duplicada no contexto errado, arquivo de inclusão ausente ou problema no caminho do certificado.

Use:

sudo nginx -t
sudo journalctl -u nginx -n 100 --no-pager

Mensagens comuns são diretas:

• unknown directive significa um erro de digitação, módulo não suportado ou diretiva colocada na compilação errada do Nginx.
• directive is not allowed here significa que a diretiva está no contexto errado, como colocar uma diretiva exclusiva de http dentro de server.
• cannot load certificate significa que o caminho está errado, o arquivo está ausente ou as permissões impedem o Nginx de lê-lo.
• bind() to 0.0.0.0:80 failed geralmente significa que outro processo já está usando a porta.

Verifique as portas com:

sudo ss -tulnp | grep ':80\|:443'

Não recarregue até que nginx -t passe. Um recarregamento com falha geralmente mantém o processo de trabalho antigo em execução, mas uma reinicialização com falha pode derrubar o site.

(13: Permission denied) e 403 Forbidden

Permission denied aparece no log de erros quando o usuário do processo de trabalho do Nginx não pode ler um arquivo ou percorrer um diretório. Um navegador pode ver 403 Forbidden.

Primeiro, encontre o usuário do processo de trabalho:

grep -R '^user ' /etc/nginx/nginx.conf

No Debian e Ubuntu, geralmente é www-data. Em sistemas compatíveis com RHEL, geralmente é nginx.

Para uma raiz estática como /var/www/html, o Nginx precisa de permissão de execução em todos os diretórios pai e permissão de leitura no arquivo:

sudo find /var/www/html -type d -exec chmod 755 {} \;
sudo find /var/www/html -type f -exec chmod 644 {} \;

Evite executar reflexivamente chown -R www-data:www-data em diretórios de aplicativos. Isso pode fazer o erro desaparecer enquanto dá ao servidor web acesso de gravação que ele não precisa. Um padrão mais seguro é manter a propriedade de implantação separada e conceder ao Nginx acesso de leitura.

Se as permissões parecerem corretas, verifique se a solicitação é para um diretório sem arquivo de índice:

location / {
    root /var/www/html;
    index index.html index.htm;
}

Se /docs/ não tiver index.html e autoindex estiver desligado, o Nginx retorna 403. Esse é o comportamento correto.

O SELinux também pode causar falhas de permissão em sistemas da família RHEL. Se as permissões de arquivo estiverem corretas, mas o Nginx ainda não puder ler ou fazer proxy, verifique os logs de auditoria antes de desabilitar o SELinux:

sudo ausearch -m avc -ts recent

(111: Connection refused) e 502 Bad Gateway

Connection refused significa que o Nginx tentou se conectar a um upstream e o destino o recusou ativamente. O aplicativo pode estar inativo, ouvindo em um endereço diferente ou usando um caminho de socket que não existe.

Para este proxy:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

verifique:

sudo ss -tulnp | grep 3000
curl -I http://127.0.0.1:3000
sudo systemctl status your-app --no-pager

Se o Nginx usar um socket Unix, verifique o arquivo de socket:

ls -l /run/gunicorn/app.sock

O usuário do processo de trabalho deve ser capaz de ler e gravar o socket.

Um 502 Bad Gateway é mais amplo. O Nginx alcançou algo upstream, mas a resposta foi inválida, incompleta, fechada muito cedo ou não era o que o Nginx esperava. Verifique os logs do aplicativo no mesmo timestamp do erro do Nginx. Essa correspondência de timestamp é importante; caso contrário, você acaba perseguindo a exceção de ontem.

Para PHP-FPM, verifique se fastcgi_pass corresponde ao socket ou porta do pool configurado. Por exemplo:

fastcgi_pass unix:/run/php/php8.3-fpm.sock;

Em seguida, verifique:

sudo systemctl status php8.3-fpm --no-pager
ls -l /run/php/php8.3-fpm.sock

504 Gateway Timeout

Um 504 significa que o Nginx esperou pelo upstream e não obteve uma resposta em tempo hábil. Aumentar os timeouts pode ser válido para relatórios, importações ou operações administrativas lentas, mas não deve ser a única correção para um endpoint público que é lento em todas as solicitações.

location /api/reports/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_connect_timeout 10s;
    proxy_send_timeout 60s;
    proxy_read_timeout 180s;
}

Em seguida, observe o tempo do backend. Adicione o tempo upstream aos logs de acesso se você ainda não o tiver:

log_format proxy_timing '$remote_addr "$request" $status '
                        'request_time=$request_time '
                        'upstream_time=$upstream_response_time';

Se $upstream_response_time for alto, o aplicativo ou banco de dados é provavelmente onde focar. Se o Nginx mostrar timeouts, mas os logs do aplicativo disserem que respondeu rapidamente, verifique os saltos de rede, rede de contêineres, resolução de DNS dentro do host ou um balanceador de carga entre o Nginx e o aplicativo.

413 Request Entity Too Large

413 geralmente é direto: o corpo da solicitação é maior do que o Nginx permite. Uploads, grandes payloads JSON e postagens de formulário podem acioná-lo.

Defina client_max_body_size no lugar mais restrito útil:

server {
    server_name example.com;

    location /upload/ {
        client_max_body_size 100M;
        proxy_pass http://127.0.0.1:3000;
    }
}

Definir um limite global enorme raramente é uma boa ideia. A maioria das rotas não precisa disso, e corpos permitidos maiores aumentam a quantidade de trabalho que um cliente mal-intencionado pode forçar em sua pilha.

Erros de SSL e Certificado

Falhas de TLS geralmente parecem diferentes dependendo de onde você as percebe. O Nginx pode falhar ao recarregar, os navegadores podem avisar sobre o certificado ou os clientes podem falhar em um handshake.

Verifique as datas do certificado:

openssl x509 -in /etc/letsencrypt/live/example.com/fullchain.pem -noout -dates -subject -issuer

Verifique o que o serviço público apresenta:

openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null | openssl x509 -noout -dates -subject -issuer

Se esses dois comandos mostrarem certificados diferentes, um balanceador de carga, CDN ou host diferente pode estar servindo o tráfego.

400 Bad Request e Problemas de Cabeçalho

400 geralmente significa que o Nginx não aceitou a sintaxe da solicitação. Com navegadores reais, é menos comum, mas bots, clientes antigos, proxies incomuns ou cabeçalhos muito grandes podem causá-lo.

Procure mensagens como client sent too large request header. Se um cookie SSO ou de aplicativo legítimo for muito grande, pode ser necessário ajustar as configurações do buffer de cabeçalho. Trate isso como uma correção direcionada, não como uma primeira resposta. Cookies muito grandes geralmente são melhor corrigidos no aplicativo.

Uma Ordem Prática de Operações

Quando um problema do Nginx está ativo, use uma ordem repetível:

1. Confirme a URL exata, host, código de status e hora.
2. Verifique nginx -t e o status do serviço.
3. Corresponda a solicitação no log de acesso.
4. Corresponda o mesmo timestamp no log de erros.
5. Se estiver fazendo proxy, verifique o status e os logs do serviço upstream.
6. Teste o upstream diretamente do host do Nginx.
7. Faça a menor alteração de configuração que se encaixe na evidência.
8. Execute nginx -t, recarregue e observe os logs enquanto testa novamente.

A maioria dos problemas do Nginx se torna comum quando você sabe onde a falha aconteceu: antes do Nginx, dentro do Nginx, entre o Nginx e o upstream ou dentro do serviço upstream.