502 Bad Gateway: co to właściwie oznacza i jak to naprawić

Otwierasz swoją stronę internetową i zamiast treści widzisz pustą stronę z komunikatem 502 Bad Gateway. Wygląda to groźnie, ale w większości przypadków naprawa jest prosta. Omówmy, co się dzieje i jak przywrócić działanie Twojej strony.

Co właściwie oznacza 502?

Gdy użytkownik żąda strony, żądanie zwykle przechodzi przez dwie warstwy: frontendowy serwer WWW (zwykle Nginx) i backendowy serwer aplikacji (PHP-FPM, Apache, Node.js lub coś innego). Nginx odbiera żądanie, przekazuje je do backendu i czeka na odpowiedź.

502 Bad Gateway oznacza, że Nginx próbował uzyskać odpowiedź z backendu, ale otrzymał coś nieprawidłowego albo nie otrzymał żadnej odpowiedzi. Backend albo uległ awarii, albo odrzucił połączenie, albo zwrócił coś, czego Nginx nie potrafił zinterpretować.

informacja

Częste nieporozumienie: 502 nie oznacza, że Twój serwer nie działa. Sam serwer działa poprawnie — problem ma aplikacja działająca za Nginx.

Najczęstsze przyczyny

Usługa backendowa została zatrzymana. To najczęstsza przyczyna. PHP-FPM uległ awarii, Apache się zawiesił albo proces Node.js zakończył się bez żadnego komunikatu. Nginx nie ma z czym się komunikować.

Na serwerze kończy się RAM. Gdy zaczyna brakować pamięci, Linux może automatycznie zakończyć procesy intensywnie zużywające zasoby. Mechanizm ten nazywa się OOM killer, a PHP-FPM lub MySQL zwykle padają jego pierwszymi ofiarami. Jeśli dzieje się to regularnie, rozważ dodanie pliku swap jako zabezpieczenia.

Pula workerów PHP-FPM jest wyczerpana. Jeśli Twoja strona otrzymuje więcej jednoczesnych żądań, niż PHP-FPM jest w stanie obsłużyć, nowe żądania ustawiają się w kolejce i ostatecznie przekraczają limit czasu. Często dzieje się tak, gdy boty wyszukiwarek zbyt agresywnie indeksują Twoją stronę — pisaliśmy o tym, jak sobie z tym radzić, w naszym przewodniku blokowania botów.

Nieprawidłowo skonfigurowany socket lub port. Nginx oczekuje, że znajdzie PHP-FPM pod określonym socketem Unix lub portem TCP. Jeśli ścieżka w konfiguracji Nginx nie zgadza się z konfiguracją PHP-FPM, zobaczysz błędy 502 od razu po wprowadzeniu zmian.

Jak to zdiagnozować

Aby wykonać poniższe kroki, połącz się ze swoim serwerem przez SSH. Możesz dowiedzieć się, jak to zrobić, z naszego artykułu o SSH.

Krok 1. Sprawdź, czy backend działa

Sprawdź status swojej usługi backendowej:

sudo systemctl status php8.2-fpm

Zastąp php8.2-fpm swoją rzeczywistą wersją PHP lub nazwą usługi backendowej. Jeśli wynik pokazuje inactive (dead) lub failed, to właśnie jest problem. Uruchom ją ponownie:

sudo systemctl restart php8.2-fpm

Następnie ponownie sprawdź status, aby upewnić się, że usługa uruchomiła się poprawnie.

Krok 2. Sprawdź log błędów Nginx

Log błędów prawie zawsze dokładnie mówi, co poszło nie tak:

sudo tail -30 /var/log/nginx/error.log

Jeśli używasz FASTPANEL®, możesz także przeglądać logi bezpośrednio w interfejsie WWW: otwórz kartę strony, przejdź do sekcji „Logi” i sprawdź kartę „Frontend Error Log”.

Oto najczęstsze komunikaty o błędach i ich znaczenie:

connect() failed - Connection refused — usługa backendowa nie działa. Uruchom ją ponownie, jak pokazano w Kroku 1.

connect() failed - No such file or directory — Nginx próbuje połączyć się z socketem Unix, który nie istnieje. Sprawdź, czy ścieżka socketu w konfiguracji Nginx odpowiada temu, co faktycznie tworzy PHP-FPM.

upstream sent too big header — backend zwrócił nagłówki HTTP, które są zbyt duże dla domyślnego bufora. Dodaj te linie do konfiguracji strony w Nginx wewnątrz bloku server:

fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;

Po edycji przetestuj konfigurację i przeładuj Nginx:

sudo nginx -t && sudo systemctl reload nginx

Krok 3. Sprawdź zasoby serwera

free -h

Jeśli kolumna available pokazuje mniej niż 100-200 MB wolnej pamięci, prawdopodobnie na Twoim serwerze kończy się RAM. Sprawdź, co ją zużywa:

ps aux --sort=-%mem | head -10

warning

Jeśli główną przyczyną jest presja pamięci, najszybszym tymczasowym rozwiązaniem jest dodanie pliku swap. Jednak swap na dysku jest znacznie wolniejszy niż RAM i nie należy traktować go jako trwałego rozwiązania. Jeśli na Twoim serwerze regularnie kończy się pamięć, czas albo zoptymalizować aplikacje, albo przejść na plan z większą ilością RAM.

Podsumowanie

502 Bad Gateway prawie zawsze oznacza problem z backendem — awarię usługi, wyczerpaną pulę workerów albo zbyt mało pamięci. Sprawdź status backendu, przeczytaj log błędów Nginx i sprawdź wykorzystanie zasobów. W zdecydowanej większości przypadków znajdziesz odpowiedź w ciągu kilku minut.

Jeśli wolisz nie zajmować się tym samodzielnie, w kodu.cloud zapewniamy bezpłatne wsparcie techniczne 24/7 do każdego VPS i serwera dedykowanego. Wszyscy nasi klienci otrzymują również FASTPANEL® Extended bez żadnych dodatkowych opłat, co znacząco ułatwia analizę logów i zarządzanie usługami przez interfejs WWW.