Chyba 502 Bad Gateway: príčiny a oprava

Čo chyba znamená

502 je odpoveď od servera, ktorý funguje. Webový server vpredu (nginx, Apache, load balancer alebo CDN ako Cloudflare) prijal požiadavku, odovzdal ju aplikácii za sebou (PHP-FPM, proces Node.js alebo Pythonu, backendový server) a nedostal späť použiteľnú odpoveď: spojenie bolo odmietnuté, prerušené alebo vrátilo nezmysly. „Gateway“ je server vpredu; „bad“ je to, čo prišlo zozadu.

502 vám teda hovorí dve veci naraz: predok funguje a zadok nefunguje alebo je pokazený. To hľadanie značne zúži.

Bežné príčiny

1. Proces aplikácie nebeží. PHP-FPM spadol alebo bol zastavený, proces Node.js zomrel, kontajner skončil. Predok sa nedokáže pripojiť vôbec.
2. Aplikácia je preťažená. Všetci workeri PHP-FPM sú zaneprázdnení, fronta je plná, nové spojenia sa odmietajú. Často po špičke návštevnosti alebo pomalom databázovom dotaze, ktorý blokuje každého workera.
3. Nesprávny socket alebo port v konfigurácii. Po aktualizácii alebo zmene verzie PHP nginx stále ukazuje na php8.2-fpm.sock, kým nový pool počúva na php8.4-fpm.sock.
4. Príliš tesne nastavené časové limity. Backend odpovie, ale neskôr, než je predok ochotný čakať. Niektoré nastavenia to hlásia ako 502, iné ako 504 Gateway Timeout.
5. Backend posiela obrovskú hlavičku alebo neplatnú odpoveď. Typické pre frameworky, ktoré dávajú veľa do cookies; nginx potom zaloguje „upstream sent too big header“.
6. CDN sa nedokáže dostať na váš server. S Cloudflare vpredu stránka 502 s logom Cloudflare znamená, že Cloudflare nedostal od vášho pôvodného servera nič: firewall, nesprávna IP po presune alebo server jednoducho nefunguje.

Ak ste návštevník

Chybu 502 na cudzom webe neopravíte. Po minúte stránku raz načítajte znova; ak pretrváva, musí konať majiteľ webu. Ak ide o váš vlastný web, čítajte ďalej.

Ak ide o váš web: najprv skontrolujte

Nefunguje to pre všetkých? Spustite kontrolu dostupnosti webu. Ukáže stavový kód zvonku a či odpovedal CDN alebo pôvodný server.

Zdieľaný hosting alebo nástroj na tvorbu webov? 502 je tam takmer vždy problém poskytovateľa (preťažený pool PHP na zdieľanom uzle). Preskočte na správu pre poskytovateľa nižšie.

Váš vlastný server: prihláste sa cez SSH a spýtajte sa webového servera, čo sa pokazilo.

# nginx: posledné chyby, najnovšie dole
sudo tail -n 50 /var/log/nginx/error.log

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

Typické riadky a čo znamenajú:

• connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory): PHP-FPM nebeží alebo je cesta k socketu nesprávna.
• connect() failed (111: Connection refused) while connecting to upstream: port backendu nepočúva.
• upstream prematurely closed connection: proces backendu spadol počas odpovedania, často fatálna chyba PHP alebo nedostatok pamäte.
• upstream sent too big header: zväčšite buffery (pozri nižšie).
• (11: Resource temporarily unavailable): všetci workeri PHP-FPM sú zaneprázdnení.

Opravy na vlastnom serveri

1. Spustite zastavenú službu

# zistite používanú verziu PHP-FPM
systemctl list-units --type=service | grep -E 'php|fpm'

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

# aplikácie Node.js alebo Python spravované cez systemd
sudo systemctl restart myapp

Ak sa služba odmieta spustiť, dôvod je v journalctl -u php8.3-fpm -n 50. Najčastejší je plný disk (df -h), druhou je syntaktická chyba v konfigurácii poolu (sudo php-fpm8.3 -t).

2. Opravte socket alebo port

Porovnajte, na čo sa pripája nginx, s tým, na čom počúva PHP-FPM:

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

Obe musia súhlasiť. Po zmene vždy otestujte konfiguráciu pred opätovným načítaním:

sudo nginx -t && sudo systemctl reload nginx

Pri Apache a PHP-FPM cez mod_proxy_fcgi platí rovnaká kontrola pre riadok SetHandler "proxy:unix:/run/php/php8.3-fpm.sock|fcgi://localhost"; testujte cez sudo apachectl configtest.

3. Dajte PHP-FPM priestor

Ak chybový log hovorí, že workeri sú zaneprázdnení, alebo server reached pm.max_children, zvýšte limit v súbore 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ý worker potrebuje pamäť (pri WordPresse často 30 až 80 MB); skôr než číslo zvýšite, skontrolujte free -m a hľadajte pomalý dotaz alebo plugin, ktorý workerov zamestnáva.

4. Zväčšite buffery pre veľké hlavičky

V bloku server v nginx:

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

5. Osobitosti WordPressu

502 hneď po aktualizácii pluginu alebo témy zvyčajne znamená, že PHP dochádza pamäť alebo pri každej požiadavke narazí na fatálnu chybu. Premenujte priečinok pluginu cez SFTP alebo SSH, aby sa vypol (wp-content/plugins/plugin-name na plugin-name.off), a potom web znova načítajte. Zvýšte memory_limit v pooli alebo php.ini, ak journalctl ukazuje „Allowed memory size exhausted“. Ak používate WP-CLI: wp plugin deactivate plugin-name.

6. Za Cloudflare

Skontrolujte, či pôvodný server odpovedá priamo: curl -I https://YOUR-SERVER-IP -H 'Host: example.com' -k. Ak to funguje, firewall na serveri môže blokovať rozsahy adries Cloudflare alebo záznam DNS v Cloudflare ukazuje na starú IP.

Keď je to problém vášho poskytovateľa

Na zdieľanom hostingu PHP-FPM reštartovať nemôžete. Pošlite poskytovateľovi toto, s časom a presnou chybou:

Dobrý deň, môj web example.com vracia „502 Bad Gateway“ približne od 14:30 UTC. Externá kontrola to potvrdzuje; na svojej strane som nič nemenil. Mohli by ste prosím skontrolovať procesy PHP a webový server na mojom hostingovom účte a dať mi vedieť, keď to bude opäť fungovať?

Ako predísť ďalšej

502 je takmer vždy zastavený alebo preťažený backend a oboje je vidieť skôr, než si to všimnú návštevníci: zastavená služba PHP-FPM, dochádzajúca pamäť, napĺňajúci sa disk. Monitoring serverov s agentom hlási presne toto zvnútra servera a kontroly webu zvonku zachytia 502 v okamihu, keď sa objaví. Na vlastnom serveri môže Quick Fix reštartovať zastavenú službu po úspešnom teste konfigurácie; ak je príčina hlbšia, prevezme to Deep Fix nepretržite.