Nginx 502 Bad Gateway Hatası Nasıl Çözülür? Linux İçin Güvenli Teşhis Rehberi

Nginx 502 Bad Gateway hatası, Nginx’in istemci isteğini aldığı ancak bu isteği işleyecek arka uç uygulamadan (upstream) geçerli bir HTTP yanıtı alamadığı anlamına gelir. Sorun PHP-FPM, Node.js, Python/Gunicorn, Java uygulaması, Apache veya başka bir proxy hedefinde olabilir. Bu hata her zaman Nginx yapılandırmasının bozuk olduğu anlamına gelmez; çoğu vakada arka uç servis durmuş, yanlış socket veya port tanımlanmış, zaman aşımına uğramış ya da sistem kaynakları tükenmiştir. Bu rehber, Linux sunucuda hatanın kaynağını log ve güvenli kontrollerle ayırmayı, yalnızca gerekli servise müdahale etmeyi ve sonucu doğrulamayı açıklar.

Belirti ve kapsam: 502 hatası neyi gösterir?

Tarayıcıda, API istemcisinde veya izleme sisteminde 502 Bad Gateway görülür. Yanıt sayfası Nginx tarafından üretildiği için Nginx genellikle çalışıyordur; ancak Nginx’in yönlendirdiği uygulama katmanında erişilebilirlik sorunu vardır.

Hata tek bir siteyi, belirli bir URI yolunu veya aynı sunucudaki tüm siteleri etkileyebilir. Bu ayrım, teşhisi hızlandırır:

• Tek site etkileniyorsa: İlgili virtual host, uygulama servisi, PHP-FPM havuzu, socket yolu veya uygulamaya ait kaynaklar incelenir.
• Tüm siteler etkileniyorsa: Ortak PHP-FPM servisi, paylaşılan upstream, Nginx yapılandırması, disk/RAM baskısı veya ağ katmanı öne çıkar.
• Yalnızca yoğunlukta oluşuyorsa: Uygulama kapasitesi, worker sınırları, zaman aşımı ve CPU/RAM/OOM kayıtları değerlendirilir.

Nginx 502 Bad Gateway hatası için hızlı teşhis özeti

Yapılandırma değiştirmeden veya servisleri topluca yeniden başlatmadan önce aşağıdaki sırayı izleyin. Üretim sisteminde yeniden başlatma, paket güncellemesi ve yapılandırma düzenlemesi için bakım penceresi planlayın. Uygulama yapılandırması ya da kalıcı veri içeren bir servis üzerinde işlem yapılacaksa güncel yedek ve geri dönüş planı olmadan ilerlemeyin.

1. Hatanın tek site mi, tüm sunucu mu olduğunu bir curl isteğiyle belirleyin.
2. Nginx error log içindeki connect(), upstream timed out veya permission denied satırını bulun.
3. Upstream servisinin durumunu, dinlediği portu ya da Unix socket’i doğrulayın.
4. Disk, inode, bellek ve çekirdek OOM kayıtlarını kontrol edin.
5. Yapılandırmayı test edin; yalnızca test başarılıysa kontrollü reload uygulayın.
6. İstek akışını hem Nginx üzerinden hem de mümkünse doğrudan upstream’e erişerek doğrulayın.

Olası nedenler ve log mesajlarının anlamı

Log veya belirti	Muhtemel neden	İlk güvenli kontrol
connect() failed (111: Connection refused)	Upstream servis durmuş veya belirtilen portta dinlemiyor.	Servis durumu ve dinleyen port/socket.
connect() to unix:... failed (2: No such file or directory)	Socket oluşmamış ya da Nginx’teki yol güncel değil.	Etkin Nginx yapılandırması ile socket listesini karşılaştırın.
permission denied	Socket/dizin izinleri veya SELinux politikası erişimi engelliyor.	Sahiplik, mod ve SELinux denetim kayıtları.
upstream timed out	Uygulama geç yanıtlıyor, kilitleniyor veya kapasitesi yetersiz.	Uygulama logları, kaynak kullanımı, yavaş istekler.
upstream prematurely closed connection	Arka uç süreç isteği bitmeden kapandı ya da çöktü.	Servis journal kayıtları ve OOM olayları.
Aralıklı 502, yüksek yükte artış	RAM/CPU baskısı, süreç limitleri, bağlantı veya kuyruk sınırları.	free, uptime, journalctl -k.

Loglar ve temel teşhis komutları

Önce dağıtımınızda etkin Nginx yapılandırmasını ve log yollarını teyit edin. Nginx paket kurulumlarında error log çoğunlukla /var/log/nginx/error.log altında bulunur; ancak özel derleme veya panel kurulumlarında yol farklı olabilir. Etkin yol, Nginx yapılandırmasındaki error_log direktifinden anlaşılır.

sudo nginx -T 2>&1 | less
sudo nginx -t
sudo systemctl status nginx --no-pager
sudo journalctl -u nginx -n 100 --no-pager

nginx -T tüm etkin yapılandırmayı ekrana döker ve ilgili server, fastcgi_pass veya proxy_pass satırlarını bulmayı sağlar. Parola, token veya özel üst bilgi içerebilecek yapılandırma çıktısını herkese açık kanallarda paylaşmayın.

Log yolunu doğruladıktan sonra hata anına yakın upstream mesajlarını inceleyin:

sudo tail -n 200 /var/log/nginx/error.log
sudo grep -Ei 'upstream|connect\(\)|timed out|permission denied|prematurely' /var/log/nginx/error.log | tail -n 100

İlgili alan adını doğrudan sunucuda sınamak, DNS veya harici CDN katmanından bağımsız ilk sonuç verir. TLS yapılandırmasını da sınamak için alan adını koruyarak yerel IP’ye yönlendirme yapabilirsiniz:

curl -I --max-time 15 http://127.0.0.1/
curl -k -I --resolve ornekalanadi.tld:443:127.0.0.1 https://ornekalanadi.tld/

ornekalanadi.tld ifadesini gerçek alan adınızla değiştirin. -k seçeneği sertifika doğrulamasını yalnızca teşhis amacıyla atlar; normal istemci erişiminde kalıcı olarak kullanılmamalıdır.

Kaynak ve işletim sistemi kayıtlarını kontrol edin

Diskin dolması, inode tükenmesi veya çekirdeğin bellek yetersizliği nedeniyle süreç sonlandırması, uygulamayı dolaylı biçimde erişilemez kılabilir.

df -h
df -i
free -h
uptime
sudo journalctl -k -b | grep -Ei 'out of memory|killed process|oom'

Disk veya inode %100 ise önce hangi dizinin büyüdüğünü, uygulamanın log döndürme ve geçici dosya düzenini inceleyin. Canlı uygulama verilerini, veritabanı dosyalarını veya bilinmeyen dosyaları alan açmak için silmeyin.

Adım adım güvenli çözüm

1. Upstream tanımını ve gerçek dinleme noktasını eşleştirin

PHP uygulamalarında fastcgi_pass, ters proxy uygulamalarında proxy_pass satırını ilgili server bloğunda bulun. Tanım bir TCP portuysa dinleyen süreci; Unix socket ise dosyanın varlığını ve erişim hakkını kontrol edin.

sudo nginx -T 2>&1 | grep -nE 'fastcgi_pass|proxy_pass'
sudo ss -ltnp
sudo ss -lxnp

Örneğin yapılandırma bir TCP hedefi gösteriyorsa, aynı portun ss -ltnp çıktısında dinlemede olması gerekir. Socket kullanılıyorsa ss -lxnp çıktısındaki socket adı, Nginx’te tanımlı yol ile uyuşmalıdır. Sadece benzer görünen bir socket yolunu tahmin ederek Nginx ayarını değiştirmeyin.

2. PHP-FPM kullanılıyorsa servis ve havuz kayıtlarını inceleyin

PHP-FPM servis adı dağıtıma ve PHP sürümüne göre değişir. Debian/Ubuntu sistemlerde sürüm içeren bir birim adı, RHEL ailesinde ise farklı bir PHP-FPM birimi kullanılabilir. Sistemdeki mevcut birimleri listeleyerek doğru adı bulun:

systemctl list-units --type=service --all | grep -i 'php.*fpm\|php-fpm'
sudo journalctl -u PHP_FPM_BIRIMI -n 150 --no-pager
sudo systemctl status PHP_FPM_BIRIMI --no-pager

PHP_FPM_BIRIMI yerine listede görünen gerçek birim adını yazın. Servis pasif veya başarısız durumdaysa, journal çıktısındaki ilk anlamlı hata satırını çözmeden tekrar tekrar başlatmayın. Yapılandırma veya uygulama hatası düzeltilmişse kontrollü yeniden başlatma uygulanabilir:

sudo systemctl restart PHP_FPM_BIRIMI
sudo systemctl is-active PHP_FPM_BIRIMI

Bu işlem o PHP-FPM birimindeki istekleri kısa süreli kesebilir. Birden fazla havuz veya site kullanılıyorsa etki alanını bakım penceresinde değerlendirin.

3. Socket izinleri ve SELinux engelini düzeltin

permission denied mesajında önce socket dosyası ile üst dizinlerin sahiplik ve izinlerini inceleyin. Nginx worker kullanıcısının adı dağıtıma göre değişebileceğinden, etkin Nginx yapılandırmasındaki user direktifini kontrol edin.

sudo nginx -T 2>&1 | grep -n '^user'
sudo namei -l /GERCEK/SOCKET/YOLU
sudo ls -l /GERCEK/SOCKET/YOLU

Buradaki yolu gerçek fastcgi_pass tanımından alın. Socket’i herkese açık hale getirmek için gelişigüzel chmod 777 uygulamayın; bu güvenlik riskidir. PHP-FPM havuzunun dinleme sahibi/grubu ve modu, Nginx worker kullanıcısının yalnızca gerekli erişimi alacağı şekilde düzenlenmelidir.

SELinux etkin RHEL türevlerinde erişim reddi politika kaynaklı olabilir. SELinux’u kalıcı veya geçici olarak kapatmak yerine denetim kayıtlarını inceleyin:

getenforce
sudo ausearch -m AVC,USER_AVC -ts recent

AVC kaydındaki kaynak ve hedef bağlamı doğrulanmadan geniş izin veren politika modülleri üretmeyin. Uygulamanın doğru dosya bağlamı ve beklenen ağ erişimi, kullandığınız dağıtımın SELinux politikasıyla uyumlu olmalıdır.

4. Proxy hedefi uzaktaysa bağlantıyı doğrudan test edin

proxy_pass başka bir sunucuya ya da yerel bir uygulama portuna yöneliyorsa, Nginx makinesinden hedefe erişimi sınayın. Aşağıdaki komutta gerçek IP veya ana makine adı ve doğru port kullanılmalıdır:

curl -v --max-time 10 http://UPSTREAM_ADRESI:PORT/SAGLIK_YOLU
nc -vz -w 5 UPSTREAM_ADRESI PORT

Sağlık yolu uygulamanızda gerçekten varsa kullanın; bilinmeyen bir URI ile uygulamanın sağlığını yorumlamayın. Bağlantı reddediliyorsa upstream servisi veya güvenlik duvarı, zaman aşımı varsa ağ yolu ya da hedef kapasitesi incelenir.

5. Zaman aşımı ve uygulama darboğazını kök nedene göre giderin

upstream timed out için yalnızca Nginx zaman aşımı değerlerini büyütmek kalıcı çözüm değildir. Önce uygulama loglarında yavaş sorgu, harici API beklemesi, kuyruk birikmesi, kilitlenme veya yetersiz worker belirtisi arayın. Kaynak kullanımı ve OOM bulguları da aynı zaman aralığında karşılaştırılmalıdır.

Uygulama normal koşullarda çalışıyor ancak uzun süren meşru istekler işliyorsa, ilgili virtual host için mevcut timeout değerlerini ve uygulamanın kendi zaman aşımı sınırlarını birlikte değerlendirin. Değişiklik öncesi etkin değeri kaydedin, küçük ve ölçülebilir bir değişiklik yapın, sonra yük ve hata oranını gözlemleyin. Global timeout artırımı diğer sitelerde bekleyen bağlantı sayısını ve kaynak tüketimini artırabilir.

Yapılandırmayı güvenle uygulama ve doğrulama

Bir Nginx dosyasında değişiklik yaptıysanız önce sözdizimini test edin. Test başarısızsa reload etmeyin; hata satırındaki dosya ve satırı düzeltin. Başarılı testten sonra reload, mevcut bağlantıları kesmeden yapılandırmayı yeniden yüklemeyi amaçlar.

sudo nginx -t
sudo systemctl reload nginx
sudo systemctl status nginx --no-pager

Ardından hem HTTP durumunu hem de hata logunu kontrol edin:

curl -sS -o /dev/null -w 'HTTP=%{http_code} toplam=%{time_total}s\n' https://ornekalanadi.tld/
sudo tail -n 50 /var/log/nginx/error.log

Başarılı doğrulama yalnızca 200 kodu görmek değildir. Uygulamanın giriş, API veya dinamik sayfa gibi daha önce 502 üreten gerçek işlevini de kontrol edin. Bir yük dengeleyici veya CDN varsa, origin üzerinde başarılı olan isteği dış erişimden de sınayın.

Önleme: 502 tekrarını azaltmak için izleme yaklaşımı

• Nginx error loglarında upstream bağlantı, zaman aşımı ve izin hataları için uyarı eşikleri oluşturun.
• PHP-FPM veya uygulama servisinin yeniden başlama sayısını, bellek tüketimini ve açık bağlantılarını izleyin.
• Disk alanı ile inode kullanımını birlikte izleyin; log rotasyonunun gerçekten çalıştığını düzenli doğrulayın.
• Uygulama dağıtımından önce yapılandırma testi, sağlık kontrolü ve geri dönüş planı kullanın.
• Socket yolu, servis birimi, port ve bağımlılıkları operasyon dokümantasyonunda güncel tutun.

Sonuç: Nginx 502 Bad Gateway hatasını kök nedene göre çözün

Nginx 502 Bad Gateway hatası için en güvenli yaklaşım, Nginx error logundaki upstream mesajını gerçek servis, socket, port, izin ve kaynak verileriyle eşleştirmektir. Servisi rastgele yeniden başlatmak geçici bir rahatlama sağlayabilir; ancak socket uyuşmazlığı, SELinux engeli, OOM olayı veya yavaş uygulama sorgusu çözülmedikçe hata yeniden oluşabilir. Önce kanıt toplayın, etki alanı sınırlı değişiklik yapın, nginx -t ile doğrulayın ve gerçek istekle sonucu ölçün.

Sık sorulan sorular

502 ile 504 arasındaki fark nedir?

502, Nginx’in upstream’den geçerli yanıt alamadığını; 504 ise upstream yanıtının tanımlı süre içinde gelmediğini gösterir. Uygulamada bazı kök nedenler ortak olabilir.

Nginx’i yeniden başlatmak 502 hatasını çözer mi?

Nginx çalışıyorsa çoğu 502 vakasında asıl sorun upstream’dedir. Önce error log ve upstream servis durumunu kontrol etmek daha güvenlidir.

PHP-FPM socket dosyası neden kaybolur?

PHP-FPM’in başlamaması, başarısız yapılandırma, süreç çökmesi veya çalışma zamanı diziniyle ilgili sorunlar socket’in oluşmamasına yol açabilir. Servis journal kayıtları nedenini gösterir.

Timeout değerini artırmak doğru çözüm müdür?

Yalnızca uzun isteklerin meşru olduğu ve uygulama kapasitesinin yeterli bulunduğu durumlarda değerlendirilebilir. Yavaş sorgu, harici servis gecikmesi veya kaynak darboğazı varken tek başına yeterli değildir.

502 hatası yalnızca tek bir URL’de görülüyorsa ne incelenmelidir?

İlgili uygulama rotasının logları, o isteğin kullandığı harici bağımlılıklar, uzun sorgular ve URI’ye özel proxy veya FastCGI kuralları öncelikli olarak kontrol edilmelidir.