502 Błąd Bramy: co to właściwie oznacza i jak to naprawić
Otwierasz swoją witrynę i zamiast treści widzisz pustą stronę z napisem 502 Bad Gateway. Wygląda to strasznie, ale w większości przypadków rozwiązanie jest proste. Rozbijmy to, co się dzieje i jak przywrócić Twoją witrynę do działania.
Co właściwie oznacza 502?
Kiedy odwiedzający żąda strony, żądanie zazwyczaj przechodzi przez dwie warstwy: serwer WWW frontendowy (zazwyczaj Nginx) i serwer aplikacji backendowy (PHP-FPM, Apache, Node.js lub coś innego). Nginx odbiera żądanie, przekazuje je do backendu i oczekuje na odpowiedź.
502 Bad Gateway oznacza, że Nginx próbował uzyskać odpowiedź od backendu, ale otrzymał coś nieprawidłowego lub wcale nie otrzymał odpowiedzi. Backend albo się zawiesił, odmówił połączenia, albo zwrócił coś, czego Nginx nie mógł zrozumieć.
Powszechne nieporozumienie: 502 nie oznacza, że Twój serwer jest wyłączony. Sam serwer działa prawidłowo – to aplikacja stojąca za Nginx ma problemy.
Najczęstsze przyczyny
Usługa backendowa została zatrzymana. To jest najczęstszy powód. PHP-FPM uległ awarii, Apache zablokował się, lub proces Node.js cicho się zakończył. Nginx nie ma z kim rozmawiać.
Serwerowi brakuje pamięci RAM. Gdy pamięć się kończy, Linux może automatycznie zabić procesy obciążające zasoby. Ten mechanizm nazywa się OOM killer, a jego pierwszymi ofiarami zazwyczaj są PHP-FPM lub MySQL. Jeśli to się regularnie zdarza, rozważ dodanie pliku wymiany jako zabezpieczenie.
Pula procesów roboczych PHP-FPM jest wyczerpana. Jeśli Twoja witryna otrzymuje więcej jednoczesnych żądań, niż PHP-FPM jest w stanie obsłużyć, nowe żądania trafiają do kolejki i ostatecznie wygasają. Często zdarza się to, gdy boty wyszukiwarek zbyt agresywnie indeksują Twoją witrynę – pisaliśmy o tym w naszym przewodniku po blokowaniu botów.
Nieprawidłowa konfiguracja gniazda lub portu. Nginx oczekuje, że PHP-FPM będzie dostępny pod określonym gniazdem Unix lub portem TCP. Jeśli ścieżka w konfiguracji Nginx nie pasuje do konfiguracji PHP-FPM, zobaczysz błędy 502 natychmiast po każdej zmianie.
Jak to zdiagnozować
Aby wykonać poniższe kroki, połącz się ze swoim serwerem przez SSH. Jak to zrobić, dowiesz się w naszym artykule 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ą faktyczną wersją PHP lub nazwą usługi backendowej. Jeśli wyjście brzmi inactive (dead) lub failed, to jest Twój problem. Uruchom ją ponownie:
sudo systemctl restart php8.2-fpm
Następnie ponownie sprawdź status, upewniając się, że uruchomiła się pomyślnie.
Krok 2. Sprawdź log błędów Nginx
Log błędów prawie zawsze mówi dokładnie, co poszło nie tak:
sudo tail -30 /var/log/nginx/error.log
Jeśli korzystasz z FASTPANEL®, możesz również przeglądać logi bezpośrednio w interfejsie internetowym: otwórz kartę witryny, przejdź do sekcji „Logi” i sprawdź zakładkę „Log błędów frontendu”.
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 gniazdem Unix, które nie istnieje. Sprawdź, czy ścieżka gniazda w konfiguracji Nginx pasuje do tego, 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 witryny Nginx w 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, Twój serwer prawdopodobnie wyczerpuje pamięć RAM. Sprawdź, co ją zużywa:
ps aux --sort=-%mem | head -10
Jeśli główną przyczyną jest presja pamięci, najszybszym tymczasowym rozwiązaniem jest dodanie pliku wymiany. Jednak wymiana na dysku jest znacznie wolniejsza niż RAM i nie powinna być traktowana jako rozwiązanie stałe. Jeśli Twój serwer regularnie wyczerpuje pamięć, czas albo zoptymalizować swoje aplikacje, albo przejść na plan z większą ilością RAM.
Podsumowanie
502 Bad Gateway to prawie zawsze problem z backendem – awaria usługi, wyczerpani pracownicy lub niewystarczająca ilość pamięci. Sprawdź status backendu, przeczytaj log błędów Nginx i przyjrzyj się zużyciu zasobów. W zdecydowanej większości przypadków znajdziesz odpowiedź w ciągu kilku minut.
Jeśli wolisz nie radzić sobie z tym sam, w kodu.cloud zapewniamy bezpłatne wsparcie techniczne 24/7 dla każdego VPS i dedykowanego serwera. Wszyscy nasi klienci otrzymują również FASTPANEL® Extended bez dodatkowych kosztów, co znacznie ułatwia analizę logów i zarządzanie usługami za pomocą interfejsu webowego.