Nginx 502 Bad Gateway Hatası: Kapsamlı Analiz ve Çözüm Rehberi

Web sunucuları dünyasında, özellikle Nginx kullanan sistem yöneticileri ve yazılım geliştiricileri için en sık karşılaşılan ve bazen can sıkıcı olabilen hataların başında 502 Bad Gateway gelir. Bu hata, genellikle sunucunuzun ön yüzünde bulunan Nginx’in, arka planda çalışan (upstream) bir servisten hatalı veya eksik bir yanıt alması sonucu tetiklenir. Bu rehberde, 502 hatasının teknik temellerine inecek ve gerçek dünya senaryolarında bu sorunu nasıl izole edip çözeceğinizi ele alacağız.

502 Bad Gateway Hatası Nedir?

HTTP protokolünde 502 hata kodu, bir ağ geçidi (gateway) veya proxy görevi gören sunucunun, bir üst sunucudan (upstream server) aldığı yanıtın geçersiz olduğunu ifade eder. Yani Nginx düzgün çalışıyordur ancak PHP-FPM, Gunicorn, Node.js veya başka bir uygulama sunucusu, Nginx’in beklediği standartta bir yanıt döndürememiştir.

Adım 1: Log Dosyalarını İnceleme

Bir sorunu çözmenin ilk kuralı, hata mesajlarının ne söylediğini anlamaktır. Nginx’in hata günlükleri (error log), sorunun kaynağı hakkında size altın değerinde bilgiler verir.

Varsayılan olarak Nginx hata loglarını şu dizinde tutar: /var/log/nginx/error.log

Log dosyasını canlı olarak izlemek için şu komutu kullanabilirsiniz: tail -f /var/log/nginx/error.log

Eğer “connect() failed (111: Connection refused)” gibi bir hata görüyorsanız, upstream sunucusu çalışmıyor olabilir. Eğer “upstream sent too big header” gibi bir hata ile karşılaşıyorsanız, buffer limitlerinizi artırmanız gerekebilir.

Adım 2: Upstream Servisinin Durumu

Çoğu durumda 502 hatası, Nginx’in arkasındaki uygulamanın çökmesi veya yeniden başlatılması kaynaklıdır.

Örneğin, PHP-FPM kullanıyorsanız servis durumunu kontrol edin: systemctl status php8.1-fpm

Eğer servis aktif değilse, yeniden başlatın: systemctl restart php8.1-fpm

Adım 3: Soket Bağlantı Sorunları

Nginx ve uygulama sunucuları birbirleriyle TCP (port üzerinden) veya Unix Domain Socket (dosya üzerinden) haberleşirler. Eğer Nginx yapılandırmanızda yanlış bir soket yolu tanımlıysa veya dosya izinleri hatalıysa 502 hatası alırsınız.

Örnek bir Nginx yapılandırmasında upstream tanımı şöyledir:

upstream backend {
    server unix:/var/run/php/php8.1-fpm.sock;
}

Burada belirtilen .sock dosyasının fiziksel olarak var olduğunu ve www-data kullanıcısının bu dosyaya erişim izni olduğunu doğrulayın: ls -l /var/run/php/php8.1-fpm.sock

Adım 4: Timeout ve Buffer Ayarları

Bazen uygulama sunucusu çok ağır bir işlem (örneğin büyük bir veritabanı sorgusu) yaptığı için Nginx’in beklediği süreyi aşar. Bu durumda Nginx, zaman aşımı hatası nedeniyle bağlantıyı keser ve 502 üretir.

/etc/nginx/nginx.conf dosyanızda şu ayarları gözden geçirin:

proxy_connect_timeout 90s;
proxy_send_timeout 90s;
proxy_read_timeout 90s;
fastcgi_buffer_size 128k;
fastcgi_buffers 4 256k;

Bu değerleri sisteminizin ihtiyaçlarına göre kademeli olarak artırmak, karmaşık süreçlerin yarattığı hataları minimize edecektir.

Adım 5: Kaynak Tüketimi ve OOM Killer

Sunucunuzdaki RAM yetersizliği, Linux çekirdeğinin (kernel) RAM tüketen süreçleri (genellikle uygulama sunucusu) aniden sonlandırmasına (OOM Killer) neden olur. Uygulamanız aniden kapandığında Nginx 502 döndürür.

Sistemin son olaylarına bakmak için: dmesg | grep -i 'out of memory'

Eğer OOM Killer devreye girmişse, sunucunuzun RAM miktarını artırmanız veya uygulama içindeki bellek sızıntılarını (memory leak) optimize etmeniz gerekir.

Sonuç

Nginx 502 hatası korkutucu görünse de, sistematik bir yaklaşımla çözülmesi oldukça kolaydır. Sırasıyla:

1. Hata loglarını okuyun.
2. Arka plan servislerinin çalışıp çalışmadığını kontrol edin.
3. Soket ve port bağlantılarını doğrulayın.
4. Timeout ve buffer limitlerini optimize edin.

Bu adımları uygulayarak sunucunuzun kararlılığını artırabilir ve 502 Bad Gateway gibi hataları minimize edebilirsiniz. Unutmayın; iyi bir sistem yöneticisi logları okumayı alışkanlık haline getiren kişidir.

---

Bu yazı Gemini ile otomatik oluşturulmuştur.