nginx ayarları Değişince 502 Hatası Nasıl Çözülür?

nginx ayarları değişikliğinden sonra 502 Bad Gateway görüyorsanız önce Nginx’in arka uç uygulamasına bağlanıp bağlanamadığını ayırın. Yönetici erişiminiz olan sunucuda yapılandırmayı kaydetmeden önce doğrulayın, aynı isteğin saatine ait hata kaydını inceleyin ve tek bir değişiklik yapın. Paylaşımlı hosting panelinde ise bu dosyalara erişim olmayabilir; sağlayıcının Nginx ve uygulama günlüklerini istemeniz gerekir.

nginx ayarları ile uygulama arasındaki bağlantıyı ayırın

502 hatası, istemci ile Nginx arasındaki bağlantının mutlaka bozuk olduğunu göstermez. Nginx çoğu kurulumda ters proxy olarak çalışır: tarayıcıdan gelen isteği PHP-FPM, Node.js, Python uygulaması veya başka bir HTTP sunucusu gibi arka uca iletir. Nginx bu hedefe bağlanamazsa, hedef yanlış yanıt verirse ya da bağlantı beklenenden erken kapanırsa 502 üretebilir.

Bu nedenle önce ortamı netleştirin. Kendi yönettiğiniz VPS veya fiziksel sunucuda Nginx yapılandırmasına, ilgili uygulamanın durumuna ve hata günlüklerine erişmeniz gerekir. Bir hosting panelinde yalnızca alan adı, proxy veya uygulama ayarlarını değiştirebiliyorsanız sistem dosyalarını düzenlemeyin. Özellikle sağlayıcı tarafından yönetilen Nginx yapılandırmasında rastgele yeniden başlatma ya da servis ayarı değişikliği yerine destek kaydı açmak daha güvenlidir.

Değişiklikten önce kanıtı ve geri dönüş yolunu hazırlayın

Önce sitenin tam URL’sini, hatanın başladığı zamanı ve hangi işlemde görüldüğünü not edin. Yalnızca giriş sayfası etkileniyor, dosya yükleme sırasında mı hata oluşuyor, yoksa tüm alan adı mı yanıt vermiyor? Etkilenen Nginx sunucusunun hata günlüğünde aynı zaman aralığındaki yeni satırları bulun. Günlük konumu dağıtıma, sanal sunucu tanımına ve sağlayıcıya göre değişebilir; siteye ait error log ekranı ya da sunucu izleme paneli kullanılabilir.

Yapılandırma dosyasını değiştirmeden önce ilgili dosyanın bir kopyasını alın veya mevcut upstream hedefini, portu ve soket yolunu ayrı bir notta saklayın. Birden fazla ayarı aynı anda değiştirmeyin. Böylece yeni hata oluşursa hangi değişikliğin etkili olduğunu anlayabilir ve gerektiğinde yalnızca son değişikliği geri alabilirsiniz.

502 hatasını adım adım teşhis edin

1. Değişiklik kapsamını belirleyin. Nginx’in site veya sanal sunucu ayarlarında son değişen bölümü bulun; özellikle proxy_pass, upstream adresi, port, Unix soketi ve PHP-FPM hedefini inceleyin. Hata yalnızca değişiklikten hemen sonra başladıysa önceki değeri geri yüklemeden önce saklayın. Hata değişiklikten bağımsızsa yalnızca son düzenlemeyi suçlamayın; günlük kaydına geçin.
2. Yapılandırma sözdizimini test edin. Yönetici terminalinde, dağıtımın Nginx yapılandırma test komutunu çalıştırın: nginx -t. Başarılı sonuç yapılandırmanın okunabildiğini gösterir; arka uç uygulamasının çalıştığını kanıtlamaz. Bir dosya, parantez veya direktif hatası bildiriliyorsa servisi yeniden yüklemeyin; belirtilen dosya ve satırı düzeltin ya da son güvenli kopyaya dönün.
3. Nginx hata günlüğünü arka uç hedefiyle karşılaştırın. “connection refused” benzeri bir kayıt, hedef adresinde bağlantı kabul eden bir süreç bulunmadığını düşündürür. Önce uygulamanın gerçekten çalıştığını ve beklenen portta ya da sokette dinlediğini uygulamanın kendi yönetim ekranı, servis durumu veya sağlayıcı paneli üzerinden kontrol edin. Uygulama çalışıyor fakat Nginx eski portu gösteriyorsa yalnızca proxy hedefini güncel çalışan hedefle eşleştirin; tüm ağ kurallarını gevşetmeyin.
4. Alternatif günlük bulgularını ayırın. “No such file or directory” Unix soket yolunun bulunamadığını, “permission denied” ise Nginx kullanıcısının o sokete erişemediğini gösterebilir. İlk durumda uygulamanın güncel soket yolunu doğrulayıp Nginx hedefini buna göre düzeltin. İkinci durumda geniş izinler vermek yerine soketin sahibi, grubu ve sağlayıcının önerdiği erişim modelini kontrol edin. chmod 777 kullanmak güvenli bir düzeltme değildir.
5. Tek değişikliği kontrollü biçimde uygulayın. Düzenlenen dosyayı kaydedin ve yeniden nginx -t çalıştırın. Test başarılıysa yapılandırmayı sağlayıcının önerdiği yeniden yükleme yöntemiyle etkinleştirin; reload mümkün değilse paneldeki güvenli yapılandırma uygulama seçeneğini kullanın. Başarısız testte servisi etkilemeden önceki değere dönün.
6. Aynı isteği yeniden deneyip yeni kanıtı inceleyin. Daha önce 502 üreten aynı URL veya işlemi, mümkünse aynı koşullarla tekrar çalıştırın. Ardından hata günlüğünde test saatinden sonra oluşan yeni satırlara bakın. 502 kayboldu ve yeni bağlantı hatası oluşmadıysa değişiklik hedefi düzeltmiş olabilir; başka bir arka uç hatası çıktıysa ilk kaydın tüm nedeni açıkladığını varsaymayın. Sorun sürerse son değişikliği geri alın, özgün kaydı saklayın ve uygulama ile Nginx arasındaki hedef bilgilerini sağlayıcıya iletin.

Belirtiye göre doğru düzeltmeyi seçin

Hedef bağlantısı reddediliyorsa

Uygulama işlemi durmuşsa Nginx ayarını büyütmek veya zaman aşımını artırmak çözüm değildir. Önce uygulamayı kendi yönetim yöntemiyle güvenli biçimde çalışır duruma getirin; uygulama çalışıyor fakat port uyuşmuyorsa Nginx’te yalnız hedef portunu düzeltin. Aynı isteği tekrar ettikten sonra yeni hata kaydı bağlantının başarıyla kurulabildiğini göstermelidir.

Zaman aşımı görülüyorsa

“upstream timed out” kaydı, arka ucun yanıtı belirtilen süre içinde üretemediğini düşündürür. İşlem gerçekten uzun süren bir rapor veya dış servis çağrısıysa uygulama performansını ve ilgili işlemin bekleme nedenini inceleyin; kısa isteklerde görülüyorsa önce uygulama kilitlenmesi, veritabanı gecikmesi veya kaynak yetersizliği araştırılmalıdır. Zaman aşımını körlemesine yükseltmek, sorunu gizleyip bağlantıları daha uzun süre meşgul edebilir.

Örneğin yalnızca yönetim panelindeki rapor dışa aktarma işlemi 502 veriyor, normal sayfalar açılıyorsa Nginx’in genel alan adı yönlendirmesini değiştirmek yerine rapor isteğinin arka uç günlüklerini incelemek daha doğru olur. Günlük uygulamanın işlem sırasında kapandığını gösterirse uygulama kaynaklarını ve rapor sorgusunu ele alın; yalnızca Nginx zaman aşımı kaydı varsa ilgili işlem süresini uygulamanın gerçek davranışıyla karşılaştırın. Bu iki bulgu aynı ayarın artırılmasını otomatik olarak haklı çıkarmaz.

Değişiklik sonrası güvenli sınır

Yapılandırma testi başarılı olsa bile bu, uygulamanın doğru içerik ürettiği anlamına gelmez. Aynı URL’nin durum kodunu, sayfa içeriğini, giriş gerektiren işlemleri ve ilgili yeni günlük satırlarını birlikte kontrol edin. Kalıcı 502 sürüyorsa özgün ayarı geri yüklemek, daha fazla rastgele değişiklik yapmaktan güvenlidir. Sorun çözülene kadar yedek kopyayı ve zaman notlarını koruyun; teknik ayrıntıları paylaşırken parolaları, erişim belirteçlerini veya kişisel verileri göndermeyin. Sunucu yönetimi kapsamınızı netleştirmek için İyibirNet üzerindeki ilgili hosting bilgilerini de inceleyebilirsiniz.

Bir sonraki güvenli adım, hatayı yeniden üretip aynı dakikaya ait Nginx ve uygulama kayıtlarını yan yana karşılaştırmaktır. Kayıt hedef portu, soket yolu veya zaman aşımını açıkça ayırıyorsa yalnız o bulguya karşılık gelen ayarı değiştirin; ayrışmıyorsa önceki yapılandırmaya dönerek sağlayıcıdan sunucu tarafı bağlantı kanıtı isteyin.