502 Bad Gateway: co to znaczy i jak to naprawić

Otwierasz swoją stronę, a zamiast treści widzisz komunikat 502 Bad Gateway. Wygląda groźnie, ale w większości przypadków naprawa jest dość prosta. Wyjaśniamy, co się dzieje i jak przywrócić stronę do działania.

Co tak naprawdę oznacza 502?

Kiedy użytkownik otwiera stronę, żądanie przechodzi zazwyczaj przez dwie warstwy: serwer frontend (najczęściej Nginx) i serwer aplikacji backend (PHP-FPM, Apache, Node.js lub inny). Nginx odbiera żądanie, przekazuje je do backendu i czeka na odpowiedź.

502 Bad Gateway oznacza, że Nginx próbował uzyskać odpowiedź od backendu, ale otrzymał coś nieprawidłowego lub nie otrzymał odpowiedzi wcale. Backend albo się zawiesił, albo odmówił połączenia, albo zwrócił coś, czego Nginx nie potrafił zinterpretować.

informacja

Częste nieporozumienie: 502 nie oznacza, że serwer nie działa. Sam serwer jest sprawny - to aplikacja za Nginx'em ma problem.

Najczęstsze przyczyny

Usługa backendu się zatrzymała. To najczęstsza przyczyna. PHP-FPM się zawiesił, Apache przestał odpowiadać lub proces Node.js cicho umarł. Nginx nie ma z czym się komunikować.

Serwerowi brakuje pamięci RAM. Gdy pamięci jest mało, Linux może automatycznie zabijać procesy zużywające dużo zasobów. Ten mechanizm nazywa się OOM killer, a PHP-FPM i MySQL są zwykle jego pierwszymi ofiarami. Jeśli zdarza się to regularnie, warto rozważyć dodanie pliku swap jako zabezpieczenia.

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

Nieprawidłowo skonfigurowany socket lub port. Nginx szuka PHP-FPM na konkretnym Unix socket'cie lub porcie TCP. Jeśli ścieżka w konfiguracji Nginx nie zgadza się z konfiguracją PHP-FPM, błąd 502 pojawi się natychmiast po każdej zmianie.

Jak to zdiagnozować

Aby wykonać poniższe kroki, połącz się z serwerem przez SSH. Jak to zrobić, opisaliśmy w naszym artykule o SSH.

Krok 1. Sprawdź, czy backend działa

Sprawdź status usługi backendowej:

sudo systemctl status php8.2-fpm

Zamień php8.2-fpm na właściwą wersję PHP lub nazwę usługi. Jeśli w wyniku widzisz inactive (dead) lub failed, to jest Twój problem. Zrestartuj usługę:

sudo systemctl restart php8.2-fpm

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

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

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

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

Jeśli korzystasz z FASTPANEL®, logi możesz przeglądać bezpośrednio w panelu: otwórz kartę strony, przejdź do sekcji "Logs" i sprawdź zakładkę "Frontend Error Log".

Oto najczęstsze komunikaty błędów i ich znaczenie:

connect() failed - Connection refused - usługa backendu nie działa. Zrestartuj ją zgodnie z krokiem 1.

connect() failed - No such file or directory - Nginx próbuje połączyć się z Unix socket'em, który nie istnieje. Sprawdź, czy ścieżka do socketu w konfiguracji Nginx jest zgodna z tym, co faktycznie tworzy PHP-FPM.

upstream sent too big header - backend zwrócił zbyt duże nagłówki HTTP. Dodaj poniższe linie do konfiguracji Nginx wewnątrz bloku server:

fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;

Po edycji sprawdź 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, serwerowi prawdopodobnie brakuje RAM. Sprawdź, co zużywa pamięć:

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

warning

Jeśli przyczyną jest brak pamięci, najszybszym tymczasowym rozwiązaniem jest dodanie pliku swap. Swap na dysku jest jednak znacznie wolniejszy od RAM i nie powinien być traktowany jako rozwiązanie stałe. Jeśli serwerowi regularnie brakuje pamięci, czas zoptymalizować aplikacje lub przejść na plan z większą ilością RAM.

Podsumowanie

502 Bad Gateway to prawie zawsze problem backendu - zatrzymana usługa, wyczerpane workery lub brak pamięci. Sprawdź status backendu, przeczytaj logi Nginx i zbadaj zużycie zasobów. W zdecydowanej większości przypadków odpowiedź znajdziesz w kilka minut.

Jeśli wolisz nie zajmować się tym samodzielnie, w kodu.cloud zapewniamy darmowe wsparcie techniczne 24/7 z każdym VPS i serwerem dedykowanym. Wszyscy nasi klienci otrzymują również FASTPANEL® Extended bez dodatkowych kosztów, co znacznie ułatwia analizę logów i zarządzanie usługami przez przeglądarkę.