Jak naprawić błąd 504 Gateway Timeout: skuteczne sposoby

Zrozumienie błędu i szybka diagnoza

Jak naprawić błąd 504 Gateway Timeout? Najpierw zrozum, co naprawdę go powoduje i gdzie szukać źródła problemu.

Błąd 504 to informacja, że serwer pośredniczący (np. reverse proxy, load balancer, CDN) nie doczekał się odpowiedzi od serwera docelowego w wyznaczonym czasie. W praktyce oznacza to, że Twoja aplikacja, backend API, baza danych lub zewnętrzna usługa odpowiedziały zbyt wolno albo w ogóle nie odpowiedziały.

To nie zawsze “awaria Internetu”. Często winny jest zbyt długi czas przetwarzania zapytania (np. ciężkie raporty, eksporty danych, źle zoptymalizowane zapytania SQL), niewłaściwe ustawienia timeoutów, blokady na firewallu, przeciążenie zasobów czy problemy po stronie dostawcy (np. Cloudflare, AWS ALB). Dobra wiadomość: 504 da się uporządkować metodycznie i w większości przypadków szybko zredukować liczbę błędów lub wyeliminować je całkowicie.

Zanim przejdziesz do zmian, ustal: czy dotyczy to pojedynczego użytkownika, konkretnej ścieżki (endpointu), pory dnia, czy całego serwisu. Ta informacja natychmiast zawęzi poszukiwania.

Symptomy i rozróżnienia

Nie każdy błąd bramki oznacza to samo — rozróżnij 504 od pokrewnych kodów, by nie leczyć nie tego, co trzeba.

504 Gateway Timeout: reverse proxy nie doczekało się odpowiedzi upstreamu. Problemem bywa wolny backend lub zbyt agresywne timeouty.
502 Bad Gateway: otrzymano nieprawidłową odpowiedź z upstreamu (błąd protokołu, crash procesu, niepoprawny nagłówek).
503 Service Unavailable: serwis chwilowo niedostępny (przeciążenie, maintenance, brak wolnych workerów).
Cloudflare 522/524: pokrewne do 504, ale specyficzne dla Cloudflare (brak połączenia do origin albo przekroczenie czasu po stronie origin).

Wnioski: jeśli problem nasila się przy długotrwałych operacjach (raporty, eksporty, ciężkie filtrowanie), najczęściej chodzi o 504 i konieczność skrócenia czasu odpowiedzi lub dopasowania timeoutów.

Jak naprawić błąd 504 Gateway Timeout? Działania po stronie użytkownika

Zanim napiszesz do supportu, sprawdź kilka prostych rzeczy — to często oszczędza czas i nerwy.

Odśwież stronę i wymuś załadowanie bez cache (Ctrl/Cmd+Shift+R). Czasem to chwilowy skok opóźnień.
Sprawdź inną przeglądarkę lub tryb incognito. Wykluczysz problem z rozszerzeniami i pamięcią podręczną.
Wyłącz VPN/proxy i przetestuj inną sieć (hotspot w telefonie). Zbyt długi lub niestabilny tor sieciowy potrafi wywołać 504.
Zweryfikuj, czy serwis nie ma ogólnej awarii (status page, DownDetector).
Wyczyść cache DNS lub zrestartuj router. Dla Windows: ipconfig /flushdns. Dla macOS: sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder.
Spróbuj ponownie po chwili. Jeśli to skok obciążenia po stronie serwisu, problem może ustąpić.

Jeśli jako użytkownik sprawdziłeś powyższe i błąd trwa, zgłoś go właścicielowi strony z informacją o czasie, adresie URL oraz krokach prowadzących do błędu. Im precyzyjniejszy opis, tym szybsza diagnoza.

Administratorzy: diagnoza backendu i warstwy pośredniej

Logi i metryki powiedzą prawdę — znajdź wąskie gardło zamiast “na ślepo” podnosić limity.

Sprawdź monitoring: CPU, RAM, I/O, liczbę połączeń, czas odpowiedzi, queue length, saturację bazy. Skoki w tym samym czasie co 504 to cenna wskazówka.
Przejrzyj logi serwera pośredniego i aplikacji:
- NGINX error.log: “upstream timed out” z informacją o endpointach i czasie.
- Apache error_log i logi modułów proxy/FastCGI.
- Logi aplikacji (timeouty, wyjątki, blokady DB).
Zidentyfikuj “gorące” endpointy (np. /report, /export, /search) i sprawdź, które żądania trwają najdłużej.
Powtórz ruch testowy narzędziem curl/k6 i zmierz realny czas wykonania. To pozwala jasno określić, czy czas przetwarzania przekracza limity.

Kluczowa zasada: najpierw skróć czas przetwarzania, dopiero potem podnoś timeouty — nie odwrotnie.

Konfiguracja serwera i timeouty

Dopasuj limity do realnych czasów i charakteru ruchu, ale nie maskuj nimi problemów wydajnościowych.

NGINX jako reverse proxy

Ustaw rozsądne timeouty i pilnuj kolejki połączeń do upstreamu.

Sprawdź i ewentualnie podnieś:
- proxy_connect_timeout (np. 5–10s) — czas na nawiązanie połączenia z upstreamem
- proxy_send_timeout (np. 60s) — czas wysyłania żądania do upstreamu
- proxy_read_timeout (np. 60–120s) — czas oczekiwania na odpowiedź upstreamu
Dla PHP-FPM/ FastCGI: fastcgi_read_timeout (np. 60–120s).
Włącz keepalive dla upstreamów i ustaw sensowną liczbę workerów. Zbyt mała może dławić ruch, zbyt duża — połączenia będą się marnować.
Po zmianach zrób reload i monitoruj logi. Nie ustawiaj timeoutów “na nieskończoność” — zwiększaj etapami.

Apache/HTTPD i proxy

Zadbaj o spójność ustawień z backendem i load balancerem.

Timeout (np. 60s) i ProxyTimeout (np. 60s) — dopasuj do realnych czasów operacji.
Dla FastCGI/FCGID: FcgidIOTimeout i powiązane parametry workerów.
Sprawdź MaxRequestWorkers/ServerLimit, aby uniknąć blokady przy skokach ruchu.

PHP-FPM i skrypty

Długie skrypty to zaproszenie do 504 — ogranicz je lub zrób asynchronicznie.

max_execution_time (np. 60–90s) w php.ini — w większości aplikacji powinien być krótki.
request_terminate_timeout w PHP-FPM (np. 60–120s) — twarde ucięcie zbyt długich żądań.
Użyj slowlogów PHP-FPM, by wychwycić pliki i linie kodu spowalniające wykonanie.
Sprawdź ustawienia puli (pm, pm.max_children, pm.max_requests), by uniknąć wyczerpania workerów.

Bazy danych i zapytania

Indeksy, plan wykonania i limity połączeń decydują o szybkości.

Włącz slow query log i użyj EXPLAIN, by zoptymalizować zapytania.
Dodaj brakujące indeksy, ogranicz SELECT *, paginuj duże wyniki.
Zadbaj o connection pool i limity, aby aplikacja nie “dławiła” bazy burstem połączeń.
Rozważ cachowanie wyników drogich zapytań (Redis/Memcached).

Warstwa sieci i bezpieczeństwo

Firewalle, WAF-y i load balancery mają własne limity — niespójność ustawień rodzi 504.

WAF/Firewall:
- Sprawdź reguły blokujące długie odpowiedzi lub połączenia keepalive.
- Dodaj allowlist dla adresów load balancera/CDN do originu.
CDN (np. Cloudflare):
- 504/524 często oznacza, że origin przestał odpowiadać w limicie (zwykle do 100 s dla planów non‑Enterprise).
- Test: tymczasowo “wyszarz” rekord (omijaj proxy) i sprawdź, czy 504 znika. Jeśli tak — kwestia leży między CDN a originem.
Load balancer (AWS ALB/NLB, GCP, Azure):
- Zsynchronizuj idle timeout i health checki z backendem.
- Upewnij się, że target group ma zdrowe instancje i wystarczającą pojemność.
- Rozważ sticky sessions jeśli aplikacja tego wymaga (ale docelowo dąż do bezstanowości).
DNS:
- Zbyt długie/niestabilne rozwiązywanie nazw może wydłużyć czas pierwszego bajtu. Monitoruj i ewentualnie skróć TTL w fazie zmian.

Architektura aplikacji i dobre praktyki

Skróć czas odpowiedzi poprzez zmianę sposobu pracy aplikacji, nie tylko parametryzację serwera.

Asynchroniczność: przenieś długie zadania (generowanie raportów, eksporty, integracje) do kolejki (RabbitMQ, SQS, Celery, Sidekiq). Zwracaj użytkownikowi od razu 202 Accepted i udostępnij status joba.
Caching: reverse proxy cache, CDN, cache aplikacyjny. Każdy trafiony cache to żądanie mniej do backendu.
Paginacja i lazy loading: nie pobieraj tysięcy rekordów “na raz”. Dziel na strony, streamuj odpowiedź.
Idempotencja i retry: w integracjach zewnętrznych stosuj potwierdzenia i bezpieczne ponowień, by uniknąć kaskad timeoutów.
Circuit breaker i limitowanie: w razie problemów z usługą zewnętrzną szybko odcinaj ruch i serwuj degradację funkcjonalną (np. starsze dane z cache).

Checklist: szybkie kroki naprawcze

Skondensowany plan działania, gdy licznik 504 rośnie.

Zweryfikuj, czy problem dotyczy wszystkich, czy wybranych endpointów/okresów.
Podejrzyj logi NGINX/Apache i aplikacji pod “timed out” oraz powolne zapytania.
Zmierz czas realnego wykonania (curl, k6) i porównaj z timeoutami po drodze (CDN/LB/proxy/app).
Tymczasowo podnieś timeouty o rozsądny margines i obserwuj metryki.
Zoptymalizuj najwolniejsze zapytania/raporty, wprowadź cache/paginację lub kolejkowanie.
Sprawdź firewalle/WAF i reguły między CDN/LB a originem.
Zwiększ zasoby lub autoscaling, jeśli to problem z wydajnością w piku.
Po stabilizacji cofnij nadmierne limity, zostaw monitoring i alerty.

Najczęstsze pytania

Krótko i rzeczowo o pułapkach związanych z 504.

Czy zawsze wystarczy podnieść timeout?
Nie. Podnoszenie timeoutów maskuje problem i może pogorszyć sytuację przy większym ruchu. Najpierw optymalizacja, potem rozsądne limity.
Czy 504 szkodzi SEO?
Tak, częste i długotrwałe błędy serwera wpływają negatywnie. Warto wdrożyć cache i mechanizmy degradacji, by roboty dostawały odpowiedź 200 lub 304.
Ile wynosi limit czasowy w Cloudflare?
W standardowych planach około 100 s na odpowiedź od originu. Długie operacje wymagają architektury asynchronicznej lub innych rozwiązań.
Jak testować problematyczny endpoint?
Użyj curl z pomiarem czasu (np. -w ‘%{time_total}’) i sprawdź, gdzie rośnie opóźnienie (DNS, connect, TTFB). Potem skonfrontuj to z logami.

Podsumowanie

504 to objaw, nie przyczyna — naprawa zaczyna się od mądrej diagnozy i krótkiej ścieżki odpowiedzi.

Błąd 504 pojawia się, gdy serwer pośredni nie doczekał się odpowiedzi od backendu. Najczęściej wygrywasz z nim, łącząc trzy elementy: optymalizację aplikacji, spójne timeouty w całym łańcuchu (CDN/LB/proxy/app) oraz odporność architektury (cache, kolejki, ograniczanie ruchu).

Zacznij od logów i metryk, namierz najcięższe endpointy, uprość i przyspiesz zapytania. Dopiero potem dopasuj limity — ostrożnie, etapami. Zadbaj o warstwę sieci i bezpieczeństwa, zsynchronizuj konfiguracje. A dla długich operacji przejdź na model asynchroniczny. Dzięki temu 504 stanie się rzadkim wyjątkiem, a nie codziennym problemem.