502 Bad Gateway: příčiny a jak to opravit

Co chyba znamená

502 je odpověď od serveru, který funguje. Webový server vpředu (nginx, Apache, load balancer nebo CDN, například Cloudflare) přijal požadavek, předal ho aplikaci za sebou (PHP-FPM, proces Node.js nebo Pythonu, backendový server) a nedostal zpět použitelnou odpověď: spojení bylo odmítnuto, přerušeno nebo vrátilo nesmysl. „Gateway“ je server vpředu; „bad“ je to, co přišlo zezadu.

502 vám tedy říká dvě věci najednou: přední část běží a zadní je mimo provoz nebo rozbitá. To hledání značně zužuje.

Časté příčiny

1. Proces aplikace neběží. PHP-FPM spadl nebo byl zastaven, proces Node.js zemřel, kontejner skončil. Přední část se nemůže připojit vůbec.
2. Aplikace je přetížená. Všichni pracovníci PHP-FPM jsou zaneprázdnění, fronta je plná, nová spojení se odmítají. Často po špičce provozu nebo pomalém dotazu do databáze, který blokuje každého pracovníka.
3. Špatný socket nebo port v konfiguraci. Po aktualizaci nebo změně verze PHP míří nginx stále na php8.2-fpm.sock, zatímco nový pool naslouchá na php8.4-fpm.sock.
4. Příliš těsné časové limity. Backend odpovídá, ale později, než je přední část ochotna čekat. Některá nastavení to hlásí jako 502, jiná jako 504 Gateway Timeout.
5. Backend posílá příliš velkou hlavičku nebo neplatnou odpověď. Typické pro frameworky, které dávají hodně do cookies; nginx pak loguje „upstream sent too big header“.
6. CDN se nemůže dostat na váš server. S Cloudflare vpředu znamená stránka 502 s logem Cloudflare, že Cloudflare z vašeho původního serveru nedostal nic: firewall, špatná IP po přesunu, nebo server prostě nejede.

Pokud jste návštěvník

502 na cizím webu opravit nemůžete. Po minutě stránku jednou znovu načtěte; pokud přetrvává, musí zasáhnout majitel webu. U vlastního webu čtěte dál.

Pokud jde o váš web: nejdřív zkontrolujte

Nejede to pro všechny? Spusťte kontrolu dostupnosti webu. Ukáže stavový kód zvenčí a zda odpověděla CDN, nebo původní server.

Sdílený hosting nebo tvůrce webů? 502 je tam téměř vždy problém poskytovatele hostingu (přetížený pool PHP na sdíleném uzlu). Přeskočte na zprávu pro poskytovatele hostingu níže.

Váš vlastní server: přihlaste se přes SSH a zeptejte se webového serveru, co se pokazilo.

# nginx: the last errors, newest at the bottom
sudo tail -n 50 /var/log/nginx/error.log

# Apache (Debian/Ubuntu)
sudo tail -n 50 /var/log/apache2/error.log

Typické řádky a co znamenají:

• connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory): PHP-FPM neběží, nebo je špatná cesta k socketu.
• connect() failed (111: Connection refused) while connecting to upstream: port backendu nenaslouchá.
• upstream prematurely closed connection: proces backendu spadl při odpovídání, často fatální chyba PHP nebo nedostatek paměti.
• upstream sent too big header: zvětšete buffery (viz níže).
• (11: Resource temporarily unavailable): všichni pracovníci PHP-FPM jsou zaneprázdnění.

Opravy na vlastním serveru

1. Spusťte zastavenou službu

# find the PHP-FPM version you use
systemctl list-units --type=service | grep -E 'php|fpm'

systemctl status php8.3-fpm
sudo systemctl start php8.3-fpm

# Node.js or Python apps managed by systemd
sudo systemctl restart myapp

Pokud se služba odmítá spustit, důvod je v journalctl -u php8.3-fpm -n 50. Nejčastější je plný disk (df -h), druhý nejčastější syntaktická chyba v konfiguraci poolu (sudo php-fpm8.3 -t).

2. Opravte socket nebo port

Porovnejte, k čemu se nginx připojuje, s tím, na čem PHP-FPM naslouchá:

grep -r fastcgi_pass /etc/nginx/sites-enabled/
grep -r '^listen' /etc/php/*/fpm/pool.d/

Obojí musí souhlasit. Po změně vždy otestujte konfiguraci před reloadem:

sudo nginx -t && sudo systemctl reload nginx

U Apache a PHP-FPM přes mod_proxy_fcgi platí stejná kontrola pro řádek SetHandler "proxy:unix:/run/php/php8.3-fpm.sock|fcgi://localhost"; testujte příkazem sudo apachectl configtest.

3. Dejte PHP-FPM prostor

Pokud chybový log říká, že pracovníci jsou zaneprázdnění, nebo server reached pm.max_children, zvyšte limit v souboru poolu (/etc/php/8.3/fpm/pool.d/www.conf):

pm = dynamic
pm.max_children = 20
pm.start_servers = 4
pm.min_spare_servers = 2
pm.max_spare_servers = 6

Každý pracovník potřebuje paměť (u WordPressu často 30 až 80 MB); před zvýšením čísla zkontrolujte free -m a hledejte pomalý dotaz nebo plugin, který pracovníky vůbec zaměstnává.

4. Zvětšete buffery pro velké hlavičky

V bloku server v nginx:

fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;
proxy_buffers 8 16k;
proxy_buffer_size 32k;

5. Specifika WordPressu

502 hned po aktualizaci pluginu nebo šablony obvykle znamená, že PHP při každém požadavku dochází paměť nebo narazí na fatální chybu. Přejmenujte složku pluginu přes SFTP nebo SSH, abyste ho vypnuli (wp-content/plugins/plugin-name na plugin-name.off), a pak web znovu načtěte. Zvyšte memory_limit v poolu nebo php.ini, pokud journalctl ukazuje „Allowed memory size exhausted“. Pokud používáte WP-CLI: wp plugin deactivate plugin-name.

6. Za Cloudflare

Zkontrolujte, zda původní server odpovídá přímo: curl -I https://YOUR-SERVER-IP -H 'Host: example.com' -k. Pokud to funguje, firewall na serveru možná blokuje rozsahy adres Cloudflare, nebo záznam DNS v Cloudflare míří na starou IP.

Když je to problém poskytovatele hostingu

Na sdíleném hostingu PHP-FPM restartovat nemůžete. Pošlete poskytovateli tohle, s časem a přesnou chybou:

Dobrý den, můj web example.com vrací „502 Bad Gateway“ přibližně od 14:30 UTC. Externí kontrola to potvrzuje; na své straně jsem nic neměnil. Mohli byste prosím zkontrolovat procesy PHP a webový server na mém hostingovém účtu a dát mi vědět, až bude vše zase v provozu?

Jak předejít dalšímu

502 je téměř vždy zastavený nebo přetížený backend a obojí je vidět dřív, než si toho všimnou návštěvníci: zastavená služba PHP-FPM, docházející paměť, plnící se disk. Monitoring serverů s agentem hlásí přesně tohle zevnitř serveru a kontroly webu zvenčí zachytí 502 ve chvíli, kdy se objeví. Na vlastním serveru může Quick Fix restartovat zastavenou službu po úspěšném testu konfigurace; pokud je příčina hlubší, převezme to Deep Fix nonstop.