502 Bad Gateway: nedenleri ve nasıl çözülür

Hata ne anlama gelir

502, çalışan bir sunucudan gelen bir yanıttır. Öndeki web sunucusu (nginx, Apache, bir yük dengeleyici veya Cloudflare gibi bir CDN) isteği aldı, arkasındaki uygulamaya (PHP-FPM, bir Node.js veya Python işlemi, bir arka uç sunucusu) iletti ve kullanılabilir bir yanıt alamadı: bağlantı reddedildi, koptu ya da anlamsız bir şey döndü. "Gateway" öndeki sunucudur; "bad" ise arkadan gelen şeydir.

Yani 502 size aynı anda iki şey söyler: ön taraf ayakta, arka taraf kapalı veya bozuk. Bu, aramayı epeyce daraltır.

Yaygın nedenler

1. Uygulama işlemi çalışmıyor. PHP-FPM çöktü veya durduruldu, Node.js işlemi öldü, konteyner sonlandı. Ön taraf hiç bağlanamaz.
2. Uygulama aşırı yüklü. Tüm PHP-FPM işçileri meşgul, kuyruk dolu, yeni bağlantılar reddediliyor. Çoğunlukla bir trafik artışından veya her işçiyi bloke eden yavaş bir veritabanı sorgusundan sonra olur.
3. Yapılandırmada yanlış bir soket veya port. Bir güncellemeden veya PHP sürüm değişikliğinden sonra nginx hâlâ php8.2-fpm.sock adresini gösterirken yeni havuz php8.4-fpm.sock üzerinde dinler.
4. Çok sıkı ayarlanmış zaman aşımları. Arka uç yanıt verir ama ön tarafın beklemeye razı olduğundan geç. Bazı kurulumlar bunu 502, bazıları 504 Gateway Timeout olarak bildirir.
5. Arka uç aşırı büyük bir başlık veya geçersiz bir yanıt gönderiyor. Çerezlere çok şey koyan çatılar için tipiktir; nginx bu durumda "upstream sent too big header" loglar.
6. CDN sunucunuza ulaşamıyor. Önünüzde Cloudflare varsa, Cloudflare logolu bir 502 sayfası, Cloudflare'in kaynak sunucunuzdan hiçbir şey alamadığı anlamına gelir: güvenlik duvarı, taşımadan sonra yanlış IP veya sunucunun basitçe kapalı olması.

Ziyaretçiyseniz

Başkasının sitesindeki bir 502'yi düzeltemezsiniz. Bir dakika sonra bir kez yeniden yükleyin; sürerse sitenin sahibinin harekete geçmesi gerekir. Kendi siteniz için okumaya devam edin.

Kendi siteniz ise: önce kontrol edin

Herkes için mi kapalı? Web sitesi çökme kontrolünü çalıştırın. Durum kodunu dışarıdan ve bir CDN'in mi yoksa kaynak sunucunun mu yanıt verdiğini gösterir.

Paylaşımlı hosting veya site oluşturucu mu? Orada 502 neredeyse her zaman hosting firmasının sorunudur (paylaşımlı bir düğümde aşırı yüklü bir PHP havuzu). Aşağıdaki hosting firmanız için mesaja geçin.

Kendi sunucunuz: SSH ile giriş yapın ve web sunucusuna neyin ters gittiğini sorun.

# nginx: son hatalar, en yenisi en altta
sudo tail -n 50 /var/log/nginx/error.log

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

Tipik satırlar ve anlamları:

• connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory): PHP-FPM çalışmıyor veya soket yolu yanlış.
• connect() failed (111: Connection refused) while connecting to upstream: arka uç portu dinlemiyor.
• upstream prematurely closed connection: arka uç işlemi yanıt verirken çöktü; çoğunlukla bir PHP fatal hatası veya bellek yetersizliği.
• upstream sent too big header: tamponları artırın (aşağıya bakın).
• (11: Resource temporarily unavailable): tüm PHP-FPM işçileri meşgul.

Kendi sunucunuzda çözümler

1. Durmuş hizmeti başlatın

# kullandığınız PHP-FPM sürümünü bulun
systemctl list-units --type=service | grep -E 'php|fpm'

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

# systemd tarafından yönetilen Node.js veya Python uygulamaları
sudo systemctl restart myapp

Hizmet başlamayı reddediyorsa nedeni journalctl -u php8.3-fpm -n 50 içindedir. En yaygın neden dolu bir disktir (df -h), ikincisi bir havuz yapılandırmasındaki söz dizimi hatasıdır (sudo php-fpm8.3 -t).

2. Soketi veya portu düzeltin

nginx'in bağlandığı yeri PHP-FPM'in dinlediği yerle karşılaştırın:

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

İkisi eşleşmelidir. Bir değişiklikten sonra yeniden yüklemeden önce yapılandırmayı her zaman test edin:

sudo nginx -t && sudo systemctl reload nginx

mod_proxy_fcgi üzerinden PHP-FPM kullanan Apache'de aynı kontrol SetHandler "proxy:unix:/run/php/php8.3-fpm.sock|fcgi://localhost" satırı için geçerlidir; sudo apachectl configtest ile test edin.

3. PHP-FPM'e alan açın

Hata logu işçilerin meşgul olduğunu veya server reached pm.max_children yazıyorsa, havuz dosyasındaki (/etc/php/8.3/fpm/pool.d/www.conf) sınırı yükseltin:

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

Her işçi bellek gerektirir (WordPress için çoğunlukla 30 ila 80 MB); sayıyı yükseltmeden önce free -m komutuna bakın ve işçileri en baştan meşgul eden yavaş sorguyu veya eklentiyi arayın.

4. Büyük başlıklar için tamponları artırın

nginx server bloğunda:

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

5. WordPress'e özgü

Bir eklenti veya tema güncellemesinden hemen sonra gelen 502, genellikle PHP'nin belleğinin tükendiği veya her istekte bir fatal hataya takıldığı anlamına gelir. Eklenti klasörünü SFTP veya SSH ile yeniden adlandırarak kapatın (wp-content/plugins/plugin-name yerine plugin-name.off), sonra siteyi yeniden yükleyin. journalctl "Allowed memory size exhausted" gösteriyorsa havuzdaki veya php.ini içindeki memory_limit değerini yükseltin. WP-CLI kullanıyorsanız: wp plugin deactivate plugin-name.

6. Cloudflare arkasında

Kaynağın doğrudan yanıt verdiğini kontrol edin: curl -I https://YOUR-SERVER-IP -H 'Host: example.com' -k. Bu çalışıyorsa, sunucudaki güvenlik duvarı Cloudflare'in adres aralıklarını engelliyor olabilir veya Cloudflare'deki DNS kaydı eski bir IP'yi gösteriyor olabilir.

Sorun hosting firmanızdaysa

Paylaşımlı hostingde PHP-FPM'i yeniden başlatamazsınız. Hosting firmanıza, saat ve tam hatayla birlikte şunu gönderin:

Merhaba, example.com web sitem yaklaşık 14:30 UTC'den beri "502 Bad Gateway" döndürüyor. Dışarıdan yapılan bir kontrol bunu doğruluyor; benim tarafımda hiçbir şeyi değiştirmedim. Lütfen hosting hesabımdaki PHP işlemlerini ve web sunucusunu kontrol edip yeniden çalıştığında bana haber verebilir misiniz?

Bir sonrakini önlemek

502 neredeyse her zaman durmuş veya aşırı yüklü bir arka uçtur ve ikisi de ziyaretçiler fark etmeden önce görülebilir: durmuş bir PHP-FPM hizmeti, tükenen bellek, dolmakta olan bir disk. Ajanlı sunucu izleme tam olarak bunları sunucunun içinden bildirir ve dışarıdan yapılan web sitesi kontrolleri 502'yi göründüğü anda yakalar. Kendi sunucunuzda bir Quick Fix durmuş hizmeti yapılandırma testi geçtikten sonra yeniden başlatabilir; neden daha derindeyse bir Deep Fix günün her saatinde devralır.