502 Bad Gateway: okok és javítás

Mit jelent a hiba

A 502 egy működő szerver válasza. Az elöl álló webszerver (nginx, Apache, terheléselosztó vagy CDN, például a Cloudflare) megkapta a kérést, továbbadta a mögötte lévő alkalmazásnak (PHP-FPM, Node.js- vagy Python-folyamat, háttérszerver), és nem kapott használható választ: a kapcsolatot elutasították, megszakították, vagy értelmetlen adat jött vissza. A „gateway” (átjáró) az elöl álló szerver; a „bad” (rossz) az, ami hátulról érkezett.

A 502 tehát egyszerre két dolgot mond: az eleje működik, a háta leállt vagy hibás. Ez jelentősen leszűkíti a keresést.

Gyakori okok

1. Az alkalmazásfolyamat nem fut. A PHP-FPM összeomlott vagy leállították, a Node.js-folyamat meghalt, a konténer kilépett. Az eleje egyáltalán nem tud csatlakozni.
2. Az alkalmazás túlterhelt. Minden PHP-FPM-worker foglalt, a sor megtelt, az új kapcsolatokat elutasítják. Gyakran forgalmi csúcs vagy egy lassú adatbázis-lekérdezés után, amely minden workert blokkol.
3. Hibás socket vagy port a konfigurációban. Frissítés vagy PHP-verzióváltás után az nginx még mindig a php8.2-fpm.sock fájlra mutat, miközben az új pool a php8.4-fpm.sock fájlon figyel.
4. Túl szűkre állított időtúllépések. A háttér válaszol, de később, mint ameddig az eleje hajlandó várni. Egyes beállítások ezt 502-ként jelzik, mások 504 Gateway Timeout-ként.
5. A háttér túl nagy fejlécet vagy érvénytelen választ küld. Jellemző azokra a keretrendszerekre, amelyek sokat tesznek a sütikbe; az nginx ilyenkor naplózza: „upstream sent too big header”.
6. A CDN nem éri el a szerverét. Ha a Cloudflare áll elöl, a Cloudflare logójával ellátott 502-es oldal azt jelenti, hogy a Cloudflare semmit nem kapott az origin szerverről: tűzfal, költözés után hibás IP-cím, vagy a szerver egyszerűen leállt.

Ha látogató

Egy idegen oldal 502-es hibáját nem tudja megjavítani. Egy perc múlva töltse újra egyszer; ha marad, az oldal tulajdonosának kell cselekednie. A saját oldalához olvasson tovább.

Ha a saját oldala: először ellenőrizze

Mindenkinek leállt? Futtassa a weboldal-leállás ellenőrzőt. Megmutatja az állapotkódot kívülről, és hogy a CDN vagy az origin válaszolt-e.

Megosztott tárhely vagy weboldalszerkesztő? Ott a 502 szinte mindig a tárhelyszolgáltató problémája (egy megosztott csomóponton túlterhelt PHP-pool). Ugorjon lent a tárhelyszolgáltatójának szóló üzenethez.

Saját szerver: jelentkezzen be SSH-val, és kérdezze meg a webszervert, mi ment félre.

# nginx: az utolsó hibák, a legújabb alul
sudo tail -n 50 /var/log/nginx/error.log

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

Tipikus sorok és jelentésük:

• connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory): a PHP-FPM nem fut, vagy a socket útvonala hibás.
• connect() failed (111: Connection refused) while connecting to upstream: a háttérport nem figyel.
• upstream prematurely closed connection: a háttérfolyamat válaszolás közben összeomlott, gyakran PHP végzetes hiba vagy memóriahiány miatt.
• upstream sent too big header: növelje a puffereket (lásd lent).
• (11: Resource temporarily unavailable): minden PHP-FPM-worker foglalt.

Javítások a saját szerveren

1. Indítsa el a leállt szolgáltatást

# keresse meg a használt PHP-FPM-verziót
systemctl list-units --type=service | grep -E 'php|fpm'

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

# systemd által kezelt Node.js- vagy Python-alkalmazások
sudo systemctl restart myapp

Ha a szolgáltatás nem indul el, az ok a journalctl -u php8.3-fpm -n 50 kimenetében van. A leggyakoribb a megtelt lemez (df -h), a második egy szintaktikai hiba a pool konfigurációjában (sudo php-fpm8.3 -t).

2. Javítsa a socketet vagy a portot

Vesse össze, mire csatlakozik az nginx, és min figyel a PHP-FPM:

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

A kettőnek egyeznie kell. Módosítás után az újratöltés előtt mindig tesztelje a konfigurációt:

sudo nginx -t && sudo systemctl reload nginx

Apache és PHP-FPM esetén mod_proxy_fcgi-n keresztül ugyanez az ellenőrzés vonatkozik a SetHandler "proxy:unix:/run/php/php8.3-fpm.sock|fcgi://localhost" sorra; teszteljen a sudo apachectl configtest paranccsal.

3. Adjon helyet a PHP-FPM-nek

Ha a hibanapló szerint a workerek foglaltak, vagy server reached pm.max_children szerepel benne, emelje a korlátot a pool fájlban (/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

Minden workernek memória kell (WordPressnél gyakran 30–80 MB); a szám emelése előtt ellenőrizze a free -m kimenetét, és keresse meg azt a lassú lekérdezést vagy bővítményt, amely eleve lefoglalja a workereket.

4. Emelje a puffereket nagy fejlécekhez

Az nginx server blockjában:

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

5. WordPress-sajátosságok

Egy bővítmény- vagy sablonfrissítés utáni 502 általában azt jelenti, hogy a PHP kifogy a memóriából, vagy minden kérésnél végzetes hibába ütközik. Nevezze át a bővítmény mappáját SFTP-n vagy SSH-n a kikapcsoláshoz (wp-content/plugins/plugin-name átnevezése plugin-name.off-ra), majd töltse újra az oldalt. Emelje a memory_limit értékét a poolban vagy a php.ini fájlban, ha a journalctl „Allowed memory size exhausted” üzenetet mutat. Ha a WP-CLI-t használja: wp plugin deactivate plugin-name.

6. Cloudflare mögött

Ellenőrizze, hogy az origin közvetlenül válaszol-e: curl -I https://YOUR-SERVER-IP -H 'Host: example.com' -k. Ha ez működik, a szerver tűzfala blokkolhatja a Cloudflare címtartományait, vagy a Cloudflare DNS-rekordja egy régi IP-címre mutat.

Ha a tárhelyszolgáltató problémája

Megosztott tárhelyen nem tudja újraindítani a PHP-FPM-et. Küldje el ezt a tárhelyszolgáltatójának, az idővel és a pontos hibával:

Üdvözlöm! Az example.com weboldalam kb. 14:30 UTC óta „502 Bad Gateway” hibát ad. Egy külső ellenőrzés megerősíti; a magam oldalán nem módosítottam semmit. Kérem, nézzék meg a PHP-folyamatokat és a webszervert a tárhelyfiókomon, és értesítsenek, ha újra működik.

A következő megelőzése

A 502 szinte mindig leállt vagy túlterhelt háttér, és mindkettő látható, mielőtt a látogatók észrevennék: leállt PHP-FPM-szolgáltatás, fogyó memória, megtelő lemez. A szervermonitorozás az ügynökkel pontosan ezeket jelenti a szerver belsejéből, a kívülről végzett weboldal-ellenőrzések pedig abban a pillanatban elkapják a 502-t, ahogy megjelenik. Saját szerveren a Quick Fix sikeres konfigurációs teszt után újraindíthatja a leállt szolgáltatást; ha az ok mélyebb, a Deep Fix átveszi, éjjel-nappal.