Błąd 504 w WordPressie: hosting czy strona

#Co oznacza błąd 504 w WordPressie?

MDN, za RFC 9110, definiuje 504 jako sytuację, w której serwer działający jako brama lub proxy “did not get a response in time from the upstream server”. Różni się to od 502 Bad Gateway: tam odpowiedź przyszła, ale była nieprawidłowa. W 504 nie przyszło nic.

Na typowym hostingu WordPressa łańcuch wygląda tak: przeglądarka, opcjonalnie CDN, nginx, PHP-FPM, baza danych i ewentualnie cache obiektowy. Kod 504 generuje ogniwo, które czekało. Samo to mówi, gdzie szukać. Jeśli nginx czeka na PHP, problem leży w PHP, bazie albo w kolejce do PHP. Jeśli czeka CDN, problem leży w serwerze źródłowym.

Dokumentacja MDN zaznacza też, że przyczyn jest wiele i naprawa zwykle wymaga analizy po stronie administratora serwera. Dlatego dalej nie ma jednej magicznej poprawki, jest kolejność kontroli.

#Czy 504 to wina hostingu, czy strony?

Pytanie rozstrzyga zakres błędu. Poniższa tabela to skrót decyzyjny, nie wyrok.

Odpowiedzialność hostingu zaczyna się tam, gdzie limity (liczba workerów, pamięć, CPU) są za małe na normalny ruch strony. Odpowiedzialność strony zaczyna się tam, gdzie pojedyncze żądanie robi tyle pracy, że blokuje workera na dziesiątki sekund. W praktyce często działa oba naraz: wolne żądania zajmują workerów, a mała pula nie ma zapasu.

#Jak sprawdzić, gdzie żądanie utknęło?

Zacznij od trzech miejsc, w tej kolejności.

1. Log błędów serwera WWW z godziny awarii. W nginx wpis upstream timed out potwierdza, że serwer czekał na PHP.
2. Log PHP-FPM. Komunikat o osiągnięciu pm.max_children oznacza, że pula była pełna i kolejne żądania stały w kolejce. Opcja pm.max_children, jak opisuje dokumentacja PHP, wyznacza limit jednoczesnych żądań obsługiwanych przez pulę.
3. Log WordPressa. Ustaw w wp-config.php WP_DEBUG na true, WP_DEBUG_LOG na true i WP_DEBUG_DISPLAY na false. Błędy trafią do wp-content/debug.log zamiast na ekran. Tak opisuje to dokumentacja WordPressa. Wyłącz debug po diagnozie.

Gdy hosting daje dostęp do slowloga PHP-FPM, ustaw request_slowlog_timeout, a PHP zapisze backtrace żądań, które trwają dłużej niż limit. Domyślnie opcja jest wyłączona (wartość 0). Backtrace pokazuje, w której funkcji wtyczki albo motywu PHP czekał.

Na hostingu współdzielonym często nie ma dostępu do tych logów. Wtedy dostęp do nich i do metryk puli PHP to pierwsza rzecz, o którą trzeba poprosić support, razem z godziną awarii i adresem, który zwrócił 504.

#Dlaczego zbyt mała pula PHP-FPM daje 504?

Każde żądanie dynamiczne zajmuje jednego workera PHP-FPM do końca odpowiedzi. Gdy wszyscy workerzy są zajęci, nowe żądania czekają. Jeśli czekają dłużej niż limit proxy, odwiedzający widzi 504.

Domyślny fastcgi_read_timeout w nginx wynosi 60 sekund, a dokumentacja nginx zaznacza, że limit liczy się między dwoma kolejnymi odczytami z serwera FastCGI, nie dla całej odpowiedzi. Na hostingach zarządzanych wartość bywa inna, więc nie zakładaj, że u Ciebie to akurat 60 sekund.

Podniesienie pm.max_children pomaga tylko wtedy, gdy serwer ma na to pamięć. Każdy worker WordPressa z kilkoma wtyczkami zajmuje jej wyraźny kawałek, więc zbyt wysoka wartość kończy się wyczerpaniem RAM i zabijaniem procesów, czyli gorszym stanem niż kolejka. Konfiguracja puli to zadanie dla administratora, który widzi zużycie pamięci.

#Jak wolne zapytania i autoloadowane opcje powodują 504?

Gdy 504 dotyczy całej strony, a pula nie jest pełna od ruchu, sprawdź bazę. Dokumentacja WordPressa zwraca uwagę, że WordPress powtarza wiele zapytań przy każdym żądaniu, a opcje oznaczone jako autoload wczytują się przy każdym wejściu. Zaleca trzymanie ich poniżej 800 KB, a pełne zalecenia opisano w poradniku optymalizacji. Wtyczka, która zapisuje duże dane w wp_options z autoloadem, wpycha je do każdego żądania. Rozmiar autoloadu sprawdzisz zapytaniem SQL po kolumnie autoload w tabeli opcji.

Do namierzenia wolnych zapytań służy stała SAVEQUERIES. Zapisuje ona każde zapytanie, czas wykonania i funkcję, która je wywołała, w $wpdb->queries. Kosztuje wydajność, więc włącz ją na krótko i na stagingu, jeśli to możliwe.

#Kiedy cache obiektowy i Redis powodują 504?

Trwały cache obiektowy zmniejsza liczbę zapytań do bazy i zwykle przyspiesza stronę. Wymaga jednak działającego serwera cache oraz pliku drop-in wp-content/object-cache.php.

Awaria działa w drugą stronę, gdy ten plik istnieje, a serwer Redis nie odpowiada. Każde żądanie próbuje wtedy połączyć się z cache, czeka na timeout połączenia i dopiero potem idzie dalej albo się poddaje. Objaw to 504 zaraz po restarcie albo awarii usługi cache po stronie hostingu, mimo że sam kod strony się nie zmienił.

Test jest prosty: zmień nazwę object-cache.php na inną. Jeśli 504 znika, winny jest cache, a nie WordPress. Przywróć plik dopiero po naprawie usługi.

#Jak WP-Cron, admin-ajax i zewnętrzne API wywołują 504?

Trzy źródła pojedynczych, wolnych żądań warto sprawdzić osobno.

• WP-Cron. Dokumentacja WordPressa wyjaśnia, że WP-Cron uruchamia się przy wejściu na stronę, nie jako stały proces. Zaległe, ciężkie zadania (kopie zapasowe, import, wysyłka) mogą więc obciążyć zwykłe żądanie odwiedzającego. Przeniesienie wywołań na systemowego crona hostingu odciąża front.
• admin-ajax.php. Wtyczki wysyłają tu żądania z panelu i z frontu. Jeśli 504 pojawia się właśnie tu, szukaj wtyczki, która robi ciężką operację w tle.
• Zewnętrzne API. Wtyczka czekająca na wolny system zewnętrzny (płatności, ERP, wysyłka) trzyma workera tak długo, jak on odpowiada. Brak własnego, krótkiego timeoutu w tej wtyczce zamienia cudzą awarię w Twoje 504.

#Czym różni się 504 od 502 i 524?

• 502 Bad Gateway: serwer za proxy odpowiedział, ale odpowiedź była nieprawidłowa. Często to padnięty proces PHP-FPM.
• 504 Gateway Timeout: brak odpowiedzi w czasie. Najczęściej przeciążenie lub wolne żądanie.
• 524: kod Cloudflare. Dokumentacja Cloudflare podaje, że pojawia się, gdy serwer źródłowy nie odpowie w domyślnych 125 sekundach. Cloudflare radzi poprosić hosting o sprawdzenie długich procesów i przeciążenia, a duże operacje przenieść na kanał bez proxy.

Za CDN-em możesz więc zobaczyć dwa różne kody dla tej samej przyczyny, zależnie od tego, które ogniwo pierwsze straciło cierpliwość.

#Kiedy podnosić timeout, a kiedy nie?

Podniesienie fastcgi_read_timeout albo limitu czasu PHP jest uzasadnione dla jednej, świadomie długiej operacji, na przykład ręcznego importu. Dla strony, która wyświetla 504 odwiedzającym, to maskowanie: wolne żądanie nadal zajmuje workera, tylko dłużej, a pula zapełnia się szybciej.

PHP-FPM ma osobny bezpiecznik, request_terminate_timeout. Dokumentacja opisuje go jako limit, po którym proces obsługujący żądanie jest zabijany, i podaje domyślną wartość 0, czyli wyłączony. Ustawiony rozsądnie, zabezpiecza pulę przed jednym zawieszonym skryptem.

#Jak naprawić 504 krok po kroku?

1. Ustal zakres: cała strona, jeden adres czy tylko wp-admin.
2. Przeczytaj logi serwera i PHP-FPM z godziny awarii.
3. Włącz debug.log i odtwórz błąd.
4. Wyłącz wtyczki (przez WP-CLI albo zmianą nazwy katalogu), potem włączaj po jednej i mierz czas odpowiedzi.
5. Jeśli istnieje object-cache.php, wyłącz go na próbę.
6. Sprawdź autoloadowane opcje i zaległe zadania WP-Cron.
7. Dopiero na końcu rozważ zwiększenie puli albo timeoutów, razem z administratorem hostingu.

Jeśli 504 pojawił się zaraz po aktualizacji, zajrzyj też do poradnika o odzyskiwaniu WordPressa po nieudanej aktualizacji.

#Kiedy to robota dla specjalisty?

Gdy logi wskazują na pulę PHP-FPM, ale hosting nie daje dostępu do jej konfiguracji. Gdy 504 wraca po każdej naprawie. Gdy sklep traci zamówienia w czasie awarii. Przy audycie, który ma oddzielić koszt hostingu od kosztu kodu, pomaga optymalizacja wydajności strony WordPress. Gdy strona leży teraz, a przyczyna jest nieznana, ratunkiem jest naprawa i wsparcie techniczne WordPressa.