Nginx 502 Bad Gateway Hatası: Kök Neden Analizi ve Adım Adım Çözüm Yöntemleri

Sistem yöneticilerinin ve DevOps mühendislerinin günlük hayatlarında en sık karşılaştığı, kullanıcı tarafında ise ciddi bir erişim engeline işaret eden 502 Bad Gateway hatası, genellikle Nginx sunucunuz ile arkada çalışan uygulama sunucunuz (upstream) arasındaki iletişimin koptuğunu gösterir. “Bad Gateway” ifadesi, Nginx’in bir proxy olarak görev yaptığı ve yukarı akıştan (upstream) geçersiz bir yanıt aldığı anlamına gelir. Peki, bu kopukluk neden kaynaklanır ve nasıl çözülür?

502 Hatasının Temel Mantığı

Nginx, gelen istekleri (request) alır ve bunları proxy_pass direktifi ile genellikle Node.js, Python (Gunicorn/Uvicorn), PHP-FPM veya Go gibi bir backend servisine iletir. 502 hatası, Nginx’in bu servise bağlanamadığı, servisin çöktüğü veya servisin Nginx’in beklediği formatta bir yanıt döndüremediği durumlarda oluşur.

1. Adım: Hata Loglarını İnceleme

Sorunu tahmin ederek çözmeye çalışmak yerine her zaman kanıta dayalı ilerlemeliyiz. Nginx’in hata logları, hatanın tam olarak hangi aşamada gerçekleştiğini bize söyler.

Terminalde şu komutla logları takip edin:

sudo tail -f /var/log/nginx/error.log

Eğer “connect() failed (111: Connection refused)” gibi bir hata görüyorsanız, bu durum Nginx’in backend servisinin dinlediği IP ve port üzerinde herhangi bir işlem bulamadığı anlamına gelir. Yani, servisiniz kapalıdır.

Sık Karşılaşılan Senaryolar ve Çözümleri

1. Backend Servisinin Kapalı Olması

En yaygın sebep, arka planda çalışan uygulamanın (örneğin PM2 ile yönetilen bir Node.js süreci) crash olmasıdır.

• Çözüm: Servisin durumunu kontrol edin.

# Node.js/PM2 örneği
pm2 status
# Eğer servis durmuşsa:
pm2 restart all

2. Upstream Yapılandırmasında Yanlış Port veya IP

Nginx konfigürasyonunuzda tanımladığınız proxy_pass adresi ile uygulamanızın dinlediği port uyuşmuyor olabilir.

• Kontrol: Uygulamanızın .env veya konfigürasyon dosyasındaki portu kontrol edin.
• Kontrol: Nginx sites-available dosyasını kontrol edin:

location / {
    proxy_pass http://127.0.0.1:3000; # Buradaki portun uygulamanızla aynı olduğundan emin olun
}

3. Kaynak Tükenmesi (Timeout)

Uygulamanızın bir veritabanı sorgusu veya dış servis yanıtı için çok uzun süre beklemesi, Nginx’in bağlantıyı zaman aşımına uğratmasına neden olabilir. Nginx, proxy_read_timeout süresi dolduğunda bağlantıyı keser ve 502 döner.

• Çözüm: Nginx ayarlarınızda zaman aşımı değerlerini artırmayı deneyin:

location / {
    proxy_read_timeout 90;
    proxy_connect_timeout 90;
    proxy_send_timeout 90;
    proxy_pass http://127.0.0.1:3000;
}

4. PHP-FPM Soket Sorunları

Eğer bir PHP uygulaması yönetiyorsanız, 502 hatasının sebebi genellikle php-fpm servisinin soket dosyası erişim sorunu veya proses sınırlarıdır. /etc/php/8.x/fpm/pool.d/www.conf dosyasında listen değerinin Nginx konfigürasyonunuzdaki ile aynı olduğundan (Unix socket veya TCP port) emin olmalısınız.

İleri Seviye Hata Giderme: Firewall ve İzinler

Bazen her şey düzgün görünse de, sistem politikaları (SELinux gibi) Nginx’in backend servisine ağ üzerinden bağlanmasını engelleyebilir. CentOS veya RHEL tabanlı sistemlerde şu komut, Nginx’in ağ istekleri yapmasına izin verir:

setsebool -P httpd_can_network_connect 1

Ayrıca, backend servisinizin sadece 127.0.0.1 adresinden gelen isteklere mi yoksa dış dünyaya mı açık olduğunu kontrol edin. netstat -tulpn | grep LISTEN komutu ile uygulamanın doğru arayüzde dinleme yaptığını doğrulayabilirsiniz.

Önleyici Yaklaşım: Monitör ve Otomasyon

502 hatası ile bir daha karşılaşmamak veya daha hızlı müdahale etmek için şunları yapabilirsiniz:

1. Health Check: Uygulamanızın bir /health endpoint’i olsun.
2. Monitoring: Uptime Kuma veya Prometheus/Grafana gibi araçlar kullanarak servisin çalışıp çalışmadığını izleyin.
3. Restart Politikaları: Uygulamanızı mutlaka systemd veya pm2 gibi bir servis yöneticisiyle başlatın ve restart=always politikasını kullanın.

Sonuç

Nginx 502 hatası korkutucu görünse de, temelinde “bağlanamama” yatan bir iletişim sorunudur. Adım adım logları takip etmek, port uyumunu kontrol etmek ve servislerin durumunu doğrulamak, sorunun %90’ını çözmenizi sağlar. Teknik bir sorunla karşılaştığınızda karmaşık ayarlar değiştirmek yerine, her zaman en basit bağlantı noktalarından başlayarak debug yapmayı alışkanlık haline getirin.

Unutmayın, sistem yöneticiliğinde en büyük beceri, hata ile karşılaştığında panik yapmadan log dosyalarının rehberliğinde mantıksal bir eleme süreci işletmektir.

---

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