502 Bad Gateway: syyt ja korjaus

Mitä virhe tarkoittaa

502 on vastaus palvelimelta, joka toimii. Edessä oleva verkkopalvelin (nginx, Apache, kuormantasaaja tai CDN kuten Cloudflare) vastaanotti pyynnön, välitti sen sen takana olevalle sovellukselle (PHP-FPM, Node.js- tai Python-prosessi, taustapalvelin) eikä saanut käyttökelpoista vastausta: yhteys evättiin, katkesi tai palautti roskaa. ”Gateway” on edessä oleva palvelin; ”bad” on se, mitä takaa tuli.

502 kertoo siis kaksi asiaa kerralla: etuosa on pystyssä ja takaosa on alhaalla tai rikki. Se rajaa etsintää huomattavasti.

Yleiset syyt

1. Sovellusprosessi ei ole käynnissä. PHP-FPM kaatui tai pysäytettiin, Node.js-prosessi kuoli, kontti sulkeutui. Etuosa ei saa yhteyttä lainkaan.
2. Sovellus on ylikuormitettu. Kaikki PHP-FPM:n työprosessit ovat varattuja, jono on täynnä, uudet yhteydet evätään. Usein liikennepiikin tai hitaan tietokantakyselyn jälkeen, joka estää jokaisen työprosessin.
3. Väärä socket tai portti asetuksissa. Päivityksen tai PHP-version vaihdon jälkeen nginx osoittaa yhä tiedostoon php8.2-fpm.sock, vaikka uusi pooli kuuntelee osoitetta php8.4-fpm.sock.
4. Liian tiukat aikakatkaisut. Taustajärjestelmä vastaa, mutta myöhemmin kuin etuosa suostuu odottamaan. Jotkin kokoonpanot raportoivat tämän virheenä 502, toiset virheenä 504 Gateway Timeout.
5. Taustajärjestelmä lähettää liian suuren otsakkeen tai virheellisen vastauksen. Tyypillistä kehyksille, jotka laittavat paljon evästeisiin; nginx kirjaa tällöin ”upstream sent too big header”.
6. CDN ei tavoita palvelintasi. Kun edessä on Cloudflare, 502-sivu Cloudflaren logolla tarkoittaa, että Cloudflare ei saanut mitään alkuperäispalvelimeltasi: palomuuri, väärä IP-osoite siirron jälkeen tai palvelin on yksinkertaisesti alhaalla.

Jos olet kävijä

Toisen sivuston 502:ta ei voi korjata. Lataa sivu uudelleen minuutin kuluttua; jos virhe jatkuu, sivuston omistajan on toimittava. Oman sivustosi kohdalla lue eteenpäin.

Jos kyse on sinun sivustostasi: tarkista ensin

Onko se alhaalla kaikille? Aja sivuston saatavuuden tarkistin. Se näyttää tilakoodin ulkoa ja sen, vastasiko CDN vai alkuperäispalvelin.

Jaettu hosting tai sivustotyökalu? 502 on siellä lähes aina palveluntarjoajan ongelma (ylikuormitettu PHP-pooli jaetulla solmulla). Siirry alla olevaan viestiin palveluntarjoajalle.

Oma palvelin: kirjaudu SSH:lla ja kysy verkkopalvelimelta, mikä meni pieleen.

# nginx: viimeisimmät virheet, uusin alimpana
sudo tail -n 50 /var/log/nginx/error.log

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

Tyypilliset rivit ja mitä ne tarkoittavat:

• connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory): PHP-FPM ei ole käynnissä tai socketin polku on väärä.
• connect() failed (111: Connection refused) while connecting to upstream: taustajärjestelmän portti ei kuuntele.
• upstream prematurely closed connection: taustaprosessi kaatui vastatessaan, usein PHP:n vakava virhe tai muisti loppui.
• upstream sent too big header: kasvata puskureita (katso alla).
• (11: Resource temporarily unavailable): kaikki PHP-FPM:n työprosessit ovat varattuja.

Korjaukset omalla palvelimella

1. Käynnistä pysähtynyt palvelu

# etsi käyttämäsi PHP-FPM-versio
systemctl list-units --type=service | grep -E 'php|fpm'

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

# systemd:n hallinnoimat Node.js- tai Python-sovellukset
sudo systemctl restart myapp

Jos palvelu ei käynnisty, syy löytyy komennolla journalctl -u php8.3-fpm -n 50. Yleisin syy on täysi levy (df -h), toiseksi yleisin syntaksivirhe pooliasetuksissa (sudo php-fpm8.3 -t).

2. Korjaa socket tai portti

Vertaa, mihin nginx ottaa yhteyden ja mitä PHP-FPM kuuntelee:

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

Näiden on täsmättävä. Muutoksen jälkeen testaa asetukset aina ennen uudelleenlatausta:

sudo nginx -t && sudo systemctl reload nginx

Apachella ja PHP-FPM:llä mod_proxy_fcgin kautta sama tarkistus koskee riviä SetHandler "proxy:unix:/run/php/php8.3-fpm.sock|fcgi://localhost"; testaa komennolla sudo apachectl configtest.

3. Anna PHP-FPM:lle tilaa

Jos virhelokissa lukee, että työprosessit ovat varattuja, tai server reached pm.max_children, nosta rajaa pooli-tiedostossa (/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

Jokainen työprosessi tarvitsee muistia (WordPressillä usein 30–80 Mt); tarkista free -m ennen luvun nostamista ja etsi hidas kysely tai lisäosa, joka pitää työprosessit varattuina.

4. Kasvata puskureita suurille otsakkeille

nginxin server-lohkossa:

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

5. WordPress-erityispiirteet

502 heti lisäosan tai teeman päivityksen jälkeen tarkoittaa yleensä, että PHP:n muisti loppuu tai se kaatuu vakavaan virheeseen jokaisella pyynnöllä. Nimeä lisäosan kansio uudelleen SFTP:llä tai SSH:lla sen poistamiseksi käytöstä (wp-content/plugins/plugin-name nimeksi plugin-name.off) ja lataa sivusto uudelleen. Nosta memory_limit poolissa tai php.inissä, jos journalctl näyttää ”Allowed memory size exhausted”. Jos käytät WP-CLI:tä: wp plugin deactivate plugin-name.

6. Cloudflaren takana

Tarkista, vastaako alkuperäispalvelin suoraan: curl -I https://YOUR-SERVER-IP -H 'Host: example.com' -k. Jos se toimii, palvelimen palomuuri voi estää Cloudflaren osoitealueet tai Cloudflaren DNS-tietue osoittaa vanhaan IP-osoitteeseen.

Kun ongelma on palveluntarjoajan

Jaetussa hostingissa PHP-FPM:ää ei voi käynnistää uudelleen. Lähetä palveluntarjoajalle tämä, ajankohdan ja tarkan virheen kanssa:

Hei, verkkosivustoni example.com palauttaa ”502 Bad Gateway” noin klo 14.30 UTC alkaen. Ulkopuolinen tarkistus vahvistaa sen; en ole muuttanut mitään omalla puolellani. Pyydän tarkistamaan hosting-tilini PHP-prosessit ja verkkopalvelimen ja kertomaan minulle, kun se toimii taas.

Seuraavan ehkäiseminen

502 johtuu lähes aina pysähtyneestä tai ylikuormitetusta taustajärjestelmästä, ja molemmat näkyvät ennen kuin kävijät huomaavat: pysähtynyt PHP-FPM-palvelu, muisti loppumassa, levy täyttymässä. Palvelimen valvonta agentilla raportoi juuri nämä palvelimen sisältä, ja ulkoa tehtävät verkkosivutarkistukset havaitsevat 502:n heti, kun se ilmestyy. Omalla palvelimellasi Quick Fix voi käynnistää pysähtyneen palvelun uudelleen, kun sen asetustesti on läpäisty; jos syy on syvemmällä, Deep Fix ottaa asian hoitaakseen kellon ympäri.