502 Bad Gateway: co se rozbilo za proxy a jak to najít

Kdo vrací 502 a proč

RFC 9110 definuje 502 pro server fungující jako brána nebo proxy, který dostal neplatnou odpověď od vnitřního serveru, na který se obrátil při snaze splnit požadavek. Každý moderní zásobník má aspoň jeden takový mezikrok: nginx nebo Apache před aplikačním serverem, load balancer před flotilou, CDN před vaším originem, nebo všechny tři.

Právě toto vrstvení je klíč ke čtení 502. Komponenta, která odpověděla, je dost zdravá na to, aby vygenerovala chybovou stránku. Komponenta za ní zdravá není. 502 tedy váš zásobník vždy rozdělí na fungující polovinu a rozbitou polovinu, a vaším úkolem je zjistit, kde leží hranice.

Sousední kódy říkají něco užšího. 504 Gateway Timeout znamená, že byl backend dostupný, ale příliš pomalý. 500 znamená, že backend sám proběhl a vyhodil chybu. 502 znamená, že backend dal špatnou odpověď, nebo žádnou. Úplné srovnání je v přehledu 5xx.

Běžné příčiny

• Proces backendu neběží. Spadlý aplikační server, zastavený pool PHP-FPM, kontejner, který skončil nebo neprošel health check. Proxy se připojuje na port, na kterém nikdo nenaslouchá.
• Backend spadl uprostřed požadavku. Zabití kvůli nedostatku paměti nebo segmentation fault uzavře spojení dřív, než jsou hlavičky odpovědi kompletní.
• Špatná adresa nebo port upstreamu. Konfigurace mířící na starý port po změně, nebo na hostitele, který se už nepřekládá.
• Neshoda protokolů. Proxy mluví obyčejné HTTP na port, který čeká TLS, nebo naopak. Bajty se nedají naparsovat, takže proxy odpověď označí za neplatnou.
• Příliš velké hlavičky odpovědi. Nadměrné cookie nebo neobvykle dlouhá hlavička překročí buffer proxy, a odpověď se odmítne místo předání dál.
• Neshoda keep-alive. Proxy znovu použije nečinné spojení, které backend už zavřel, což způsobí sporadické 502 i za jinak normální zátěže.
• Restarty a nasazení. Jakékoli okno, kdy starý proces skončil a nový ještě nepřijímá spojení.
• Všechny backendy nezdravé. Load balancer bez jediného funkčního člena nemá kam požadavek poslat.

Čtení logu proxy, které obvykle vyšetřování ukončí

Stavový kód je obecný, ale řádek v logu proxy je konkrétní. U nginx stojí za to znát tyto zprávy:

[error] connect() failed (111: Connection refused) while connecting to upstream,
        upstream: "http://127.0.0.1:8080/"

[error] upstream prematurely closed connection while reading response header
        from upstream

[error] recv() failed (104: Connection reset by peer) while reading response
        header from upstream

[error] upstream sent too big header while reading response header from upstream

[error] no live upstreams while connecting to upstream

Každá ukazuje jinam:

• connect() failed (111: Connection refused). Na dané adrese a portu nikdo nenaslouchá. Backend je zastavený, navázaný na jiné rozhraní, nebo na jiném portu, než říká konfigurace.
• upstream prematurely closed connection. Backend požadavek přijal a pak spadl nebo se zasekl ještě před dokončením odpovědi. Hledejte pády, zabíjení kvůli nedostatku paměti nebo timeout workeru uvnitř aplikace, ne u nginx.
• connection reset by peer. Podobné, ale spojení bylo aktivně resetováno. Často firewall mezi nimi, nebo backend, který zavřel spojení z poolu, které proxy pořád považovala za otevřené.
• upstream sent too big header. Problém s velikostí bufferu v proxy, ne chyba backendu. Odpověď je platná, jen větší, než na kolik je proxy nastavená.
• no live upstreams. Health checky označily každý backend jako nedostupný.

Jak to opravit

1. Otestujte backend přímo, obejděte proxy. Z hostitele proxy si vyžádejte přímo adresu upstreamu:

   curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8080/

   200 zde a 502 na veřejné URL znamená, že chyba je v konfiguraci proxy nebo ve spojení mezi nimi. Odmítnuté spojení znamená, že backend je skutečně nedostupný.
2. Zkontrolujte, že backend běží a naslouchá na adrese, kterou proxy očekává. Navázání na 127.0.0.1, zatímco proxy volá adresu kontejneru, bývá častá příčina.
3. Přečtěte si chybový log proxy a než cokoli v konfiguraci změníte, spárujte zprávu se seznamem výše.
4. Pak si přečtěte log backendu. Pád, zabití kvůli nedostatku paměti nebo timeout workeru ve stejnou sekundu potvrdí případ "prematurely closed". Ticho ukazuje zpátky na konektivitu.
5. Ověřte adresu, port a schéma upstreamu v konfiguraci proxy, obzvlášť po migraci nebo přestavbě kontejneru.
6. Zvyšte buffery hlaviček proxy, pokud log hlásí, že byla hlavička příliš velká, a zvlášť zjistěte, proč hlavička narostla.
7. Nechte nasazení se překrývat. Spusťte nový proces, počkejte, až projde health check, pak vyprázdněte a zastavte starý. Postupné nasazení podmíněné zdravím zcela odstraní okno restartu, které způsobuje 502 v době nasazení.

Jak zachytit 502, které trvá dvacet sekund

502 v době nasazení a při smyčce pádů bývají krátké. Backend se restartuje, dvacet sekund chybuje a zotaví se, takže než to kdokoli zkontroluje, web je v pořádku a není co zkoumat. Naplánovaná HTTP kontrola běžící nepřetržitě taková okna zaznamená s časovými značkami, což promění "dnes ráno to na chvíli bylo divné" ve vzor, který lze porovnat s nasazeními a restarty. 502 může přijít i z edge uzlu CDN místo z vašeho originu, takže kontrola z více regionů odliší globální selhání backendu od problému na edge postihujícího jen část vaší návštěvnosti, na což slouží distribuovaný monitoring dostupnosti.