Nginx 502 Bad Gateway Hatası Neden Oluşur?

502 Bad Gateway ne anlama gelir?

Nginx üzerinde görülen 502 Bad Gateway hatası, çoğunlukla Nginx’in arkasındaki uygulama veya servisten geçerli bir cevap alamadığını gösterir.

Bu hata her zaman Nginx’in çalışmadığı anlamına gelmez. Kullanıcıya 502 sayfasını gösterebildiğine göre Nginx çoğu durumda isteği kabul etmiş, fakat isteği yönlendirdiği backend servisle sağlıklı iletişim kuramamıştır.

Kullanıcı → Nginx → Backend uygulama → Veritabanı veya diğer servisler

Backend uygulamanın çalışmaması

Nginx isteği belirli bir IP adresine, porta veya Unix socket’e yönlendirir. Uygulama durmuşsa, sürekli yeniden başlıyorsa veya beklenen portu dinlemiyorsa Nginx bağlantı kuramaz.

Yalnızca Nginx’i yeniden başlatmak bu durumda kalıcı çözüm sağlamaz. Öncelikle upstream uygulamanın neden erişilemez olduğu belirlenmelidir.

• Deployment sonrasında başlamayan uygulama
• Sürekli yeniden başlayan container
• Yanlış portta çalışan servis
• Bellek yetersizliği nedeniyle sonlandırılan process
• Trafik almaya henüz hazır olmayan uygulama

Yanlış proxy_pass adresi veya portu

Adres, port veya protokol yanlışsa Nginx backend servise bağlantı kuramaz. Uygulamanın portu değişmiş fakat Nginx konfigürasyonu güncellenmemiş olabilir.

HTTP bekleyen bir servise HTTPS ile veya HTTPS bekleyen bir servise HTTP ile bağlanmak da geçerli cevap alınamamasına neden olabilir.

Docker network veya servis adı problemi

Nginx ve uygulama farklı container’larda çalışıyorsa localhost, Nginx container’ının kendisini ifade eder; backend uygulamayı değil.

Container’ın yalnızca Up görünmesi yeterli değildir. Nginx’in bulunduğu network bağlamından backend servise gerçekten erişilebildiği doğrulanmalıdır.

• Container’ların aynı network üzerinde olmaması
• Compose servis adının değişmesi
• Backend container’ın başlamaması
• Uygulamanın yalnız 127.0.0.1 üzerinde dinlemesi
• Nginx’in eski IP adresini kullanması

Backend servisin bağlantıyı erken kapatması

Nginx backend servise bağlanabilir, ancak uygulama geçerli bir HTTP cevabı göndermeden bağlantıyı kapatabilir. Error logunda upstream prematurely closed connection ifadesi görülebilir.

Bu kayıt yalnızca bağlantının kesildiğini söyler. Asıl kök neden çoğunlukla aynı zaman aralığındaki uygulama logunda bulunur.

• Beklenmeyen uygulama hatası
• Worker process’in çökmesi
• Bellek yetersizliği
• Uygulama içi timeout
• Veritabanı bağlantı problemi
• Deployment sırasında process’in sonlandırılması

Unix socket izinleri

Nginx; PHP-FPM, Gunicorn veya benzeri servislerle Unix socket üzerinden haberleşebilir. Socket mevcut olsa bile Nginx worker kullanıcısının gerekli erişim izni bulunmayabilir.

İzinleri incelemeden herkese yazma yetkisi vermek hatayı geçici olarak gizleyebilir, fakat ciddi bir güvenlik problemi oluşturabilir.

• Socket sahibi ve grubu
• Dosya ve üst dizin izinleri
• Nginx worker kullanıcısı
• Uygulamanın socket oluşturma ayarları

Kaynak yetersizliği

Backend çalışıyor görünse bile CPU, bellek, disk veya bağlantı limitleri nedeniyle isteklere cevap veremeyebilir.

Bu durumda timeout değerlerini artırmak problemi çözmek yerine kullanıcıların daha uzun süre beklemesine neden olabilir.

• OOM ve bellek baskısı
• Dolu disk veya inode alanı
• Aşırı CPU kullanımı
• Tükenen veritabanı connection pool’u
• Yetersiz worker sayısı
• Dosya tanımlayıcı limitleri

502 ile 504 arasındaki fark

502 Bad Gateway, Nginx’in upstream servisten geçerli bir cevap alamadığını; 504 Gateway Timeout ise upstream servisin beklenen süre içinde cevap vermediğini ifade eder.

Gerçek kök neden yalnız HTTP durum koduna bakılarak belirlenemez. Nginx error logu, uygulama logu ve olay zaman çizelgesi birlikte incelenmelidir.

Güvenli ilk kontroller

Production ortamında değişiklik yapmadan önce hatanın kapsamı, başlangıç zamanı ve son değişikliklerle ilişkisi belirlenmelidir.

• Hata bütün URL’lerde mi, belirli bir endpoint’te mi?
• Backend beklenen IP ve portu dinliyor mu?
• Nginx’in bulunduğu ortamdan backend’e erişilebiliyor mu?
• Hata deployment sonrasında mı başladı?
• Nginx ve uygulama logları aynı zaman aralığında ne söylüyor?
• CPU, bellek, disk veya bağlantı baskısı var mı?
• Sorun sürekli mi, yalnız yoğun trafik altında mı oluşuyor?

Kaçınılması gereken müdahaleler

Kanıt toplanmadan yapılan müdahaleler kök nedeni gizleyebilir veya kesintiyi büyütebilir.

• Nginx’i sürekli yeniden başlatmak
• Bütün timeout değerlerini artırmak
• Socket izinlerini kontrolsüz biçimde açmak
• Firewall’u tamamen kapatmak
• Container ve volume’leri silmek
• Logları almadan deployment’ı geri çevirmek

Ne zaman uzman desteği alınmalı?

Hata aralıklı tekrarlanıyorsa, birden fazla servis etkileniyorsa veya müdahalenin kesinti ve veri kaybı riski bulunuyorsa sorun yalnızca bir Nginx ayarı olarak değerlendirilmemelidir.

Nginx, uygulama, container ağı, veritabanı ve sistem kaynaklarının aynı zaman çizelgesinde incelenmesi kalıcı çözüm için gereklidir.