visto em sites 502 Gateway deficiente e 504 Tempo limite do gateway os erros ocorrem frequentemente porque o servidor web não está a obter a resposta correta do serviço back-end. Este serviço pode ser PHP-FPM, backend Apache, aplicação Node.js, serviço API de painel de jogo ou outra aplicação por trás do proxy.

Estes erros são especialmente comuns em alojamento, painel de jogo, WHMCS, Pterodactyl, painel de administração personalizado e sistemas de arranque baseados na web.

1. Diferença entre o erro 502 e 504

• 502 Gateway inválido: O servidor web não consegue ligar-se ao serviço de back-end ou recebe uma resposta distorcida.
• Tempo limite do gateway 504: O serviço de backend parece estar a responder, mas a resposta não é devolvida a tempo.

Portanto, o 502 é mais uma falha de ligação/serviço e o 504 é um problema de lentidão ou de tempo limite.

2.º Verificando o estado do serviço

Primeiro, verifique se o servidor web e os serviços PHP estão em execução.

systemctl status nginx
systemctl status apache2
systemctl status php-fpm

Nos sistemas CentOS, AlmaLinux ou Rocky Linux, o serviço PHP-FPM pode ser designado por:

systemctl status php-fpm
systemctl status httpd

Se o serviço foi interrompido, reinicie-o:

systemctl restart nginx
systemctl restart php-fpm

3.º Revendo ficheiros de log

Não é correto avançar com suposições para os erros 502 e 504. O ficheiro de registo mostra a verdadeira causa do erro.

tail -n 100 /var/log/nginx/error.log
tail -n 100 /var/log/apache2/error.log

Em sistemas baseados em CentOS:

tail -n 100 /var/log/httpd/error_log

As seguintes declarações podem ser vistas nos logs:

• falha de ligação(): Não foi possível ligar ao serviço de back-end.
• o tempo limite do upstream expirou: O serviço de back-end responde com atraso.
• ligação recusada: O serviço está inativo ou há encaminhamento para a porta errada.
• permissão negada: Há um problema de socket ou de permissão de ficheiro.

4.º Socket PHP-FPM ou controlo de porta

O Nginx liga-se ao PHP-FPM via socket ou porta. O caminho do PHP-FPM no ficheiro de configuração do Nginx e o valor de escuta real do PHP-FPM devem ser os mesmos.

grep -R "fastcgi_pass" /etc/nginx/sites-enabled/
grep -R "listen =" /etc/php/*/fpm/pool.d/www.conf

Por exemplo, se o Nginx utilizar:

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

O mesmo socket deve ser ouvido no lado do PHP-FPM:

listen = /run/php/php8.2-fpm.sock

5. Aumentando as definições de tempo limite

Os erros 504 podem ser recebidos em grandes painéis de processamento, mercados de jogo, APIs ou scripts PHP de execução lenta. Os valores de tempo limite do Nginx podem ser aumentados.

nano /etc/nginx/nginx.conf

Os seguintes valores podem ser adicionados ao bloco http ou ao bloco do servidor relevante:

proxy_connect_timeout 300;
proxy_send_timeout 300;
proxy_read_timeout 300;
fastcgi_read_timeout 300;

Teste as definições e reinicie o Nginx:

nginx -t
systemctl restart nginx

6. Verificação dos limites do processo PHP-FPM

Quando o tráfego aumenta, os limites de transação do PHP-FPM podem ser insuficientes. Nesse caso, os pedidos são colocados em fila e ocorre um tempo limite.

nano /etc/php/8.2/fpm/pool.d/www.conf

Configurações de exemplo:

pm = dynamic
pm.max_children = 30
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 10

Estes valores terão de ser ajustados de acordo com a quantidade de RAM do servidor. Definir um valor demasiado elevado aumenta o consumo de RAM.

Erros Comuns

• Alterar as definições sem consultar o ficheiro de registo
• Não atualizar o caminho do socket Nginx mesmo que a versão do PHP tenha sido alterada
• Não corrigir a consulta lenta real aumentando o tempo limite
• Aumentar os limites do PHP-FPM sem calcular a RAM
• Reiniciar o serviço sem testar a configuração do Nginx

Perguntas frequentes

O erro 502 é sempre causado pelo Nginx?
O Nginx é apenas aquele que mostra o erro. O verdadeiro problema pode estar no PHP-FPM, no backend do Apache, na aplicação Node.js ou noutro serviço.

Aumentar o tempo limite é a solução definitiva para os erros 504?
Nem sempre. Aumentar o tempo limite proporciona um alívio temporário. A verdadeira solução é encontrar a consulta lenta, o processamento pesado ou o problema de desempenho.

É seguro reiniciar o PHP-FPM?
Geralmente é seguro, mas os pedidos ativos podem ser afetados por um curto período. Em sistemas ocupados, devem ser preferidas as horas de baixo tráfego.

Recomendações de desempenho

• Verifique a versão do PHP-FPM e o caminho do socket regularmente.
• Examine os registos de consultas lentas no painel web e nos serviços API.
• Se a RAM for insuficiente, não aumente o valor max_children do PHP-FPM inconscientemente.
• Reduza a carga de back-end utilizando um sistema de cache.
• Gira os registos de erros antes que cresçam com o logrotate.

Este artigo foi preparado especialmente para o PvPServer.