Błąd 502 Bad Gateway: przyczyny i naprawa

Co oznacza kod 502

Najczęściej Nginx, Apache, CDN albo load balancer działa jako proxy i nie może porozumieć się z usługą zaplecza. Tą usługą bywa PHP-FPM, aplikacja Node.js, serwer Java, kontener, API albo inny serwer. Dlatego nie należy zakładać, że każdy 502 oznacza ten sam problem.

• 500 zwykle oznacza błąd zwrócony przez samą aplikację,
• 502 wskazuje na nieprawidłową lub brakującą odpowiedź upstreamu,
• 504 częściej oznacza przekroczony czas oczekiwania na upstream.

Najpierw ustal zakres awarii

Zapisz godzinę wystąpienia, adres domeny i to, czy błąd dotyczy całej strony, tylko panelu, pojedynczego endpointu czy wszystkich aplikacji na serwerze. Sprawdź też, czy przed serwerem nie działa CDN, WAF lub dodatkowy proxy. Taka informacja pozwala oddzielić problem klienta, warstwy pośredniej i backendu.

Sprawdź logi serwera WWW i backendu

Log błędów z chwili wystąpienia 502 jest ważniejszy niż losowa zmiana konfiguracji. Użyj tylko ścieżek i nazw usług, które rzeczywiście istnieją na danym hoście.

journalctl -u nginx --since "15 minutes ago"
journalctl -u phpX.Y-fpm --since "15 minutes ago"
tail -n 100 /var/log/nginx/error.log
tail -n 100 /var/log/apache2/error.log

Szukaj komunikatów o odmowie połączenia, braku socketu, zakończonym procesie, braku pamięci, braku miejsca na dysku albo błędzie aplikacji. Jeżeli backendem nie jest PHP-FPM, sprawdź logi właściwej usługi.

PHP-FPM, socket i konfiguracja vhosta

Przy aplikacji PHP częstą przyczyną jest wyłączona pula FPM lub niezgodność między socketem ustawionym we vhoście a socketem utworzonym przez usługę. Test konfiguracji serwera WWW wykonuj przed jego przeładowaniem.

systemctl status phpX.Y-fpm
ls -l /run/php/
nginx -t
apachectl -t

Nie zmieniaj wersji PHP ani nazwy socketu na podstawie przykładu z Internetu. Najpierw potwierdź, jaka pula i jaka wersja są przypisane do konkretnej aplikacji.

Zasoby i zależności aplikacji

502 może pojawić się po wyczerpaniu pamięci, miejsca na dysku, inode lub limitu procesów. Przyczyną może być także niedostępna baza danych, Redis, kolejka lub zewnętrzne API. Te polecenia pomagają rozpocząć diagnozę, ale nie są naprawą samą w sobie.

free -h
df -h
df -ih
uptime

Jeżeli zasobów brakuje, najpierw ustal proces i przyczynę wzrostu. Dopiero potem podejmuj decyzję o limicie, skalowaniu albo zmianie konfiguracji.

Czego nie robić w ciemno

• nie uruchamiaj aktualizacji pakietów wyłącznie dlatego, że pojawił się 502,
• nie zmieniaj globalnie parametrów proxy ani buforów bez potwierdzenia przyczyny w logach,
• nie restartuj całego stosu usług przed zebraniem informacji potrzebnych do diagnozy,
• nie usuwaj cache ani danych aplikacji bez sprawdzonej kopii i zgody właściciela usługi.

Po przywróceniu działania warto objąć usługę monitoringiem i sprawdzić, czy alert wykryje błąd ponownie. Gdy problem wynika ze starego środowiska PHP lub systemu, bezpieczniej zaplanować migrację niż powtarzać doraźne restarty.