Nginx Ayarları ile 502 Hatası Nasıl Teşhis Edilir?

Nginx ayarları değiştirilmiş veya uygulama sunucusu yeniden başlatılmışsa görülen 502 Bad Gateway hatası çoğunlukla Nginx’in arka uç uygulamasından geçerli bir yanıt alamadığını gösterir. Önce hatanın saatini ve etkilenen URL’yi not edin; ardından upstream adresi, uygulamanın dinlediği port, soket erişimi ve yeni hata günlüğü kaydını birlikte kontrol edin.

İncelemeye başlamadan önce ortamı belirleyin

Bu işlem, Nginx yapılandırmasına ve sunucu günlüklerine erişebilen bir yönetici hesabı gerektirir. Paylaşımlı hosting panelinde yalnızca alan adı veya PHP sürümü gibi sınırlı seçenekler görünüyorsa ana Nginx dosyasını değiştiremezsiniz; ilgili kayıtları ve değişiklik talebini hosting sağlayıcısına iletmeniz gerekir. VDS, VPS veya özel sunucuda ise işletim sistemi yöneticisi ya da Nginx yapılandırmasına yetkili bir hesap gerekir.

Değişiklik yapmadan önce mevcut yapılandırma dosyasının yedeğini alın veya en azından değiştireceğiniz upstream, proxy_pass ve zaman aşımı değerlerini ayrı bir yere kaydedin. Aynı anda birden fazla ayarı değiştirmeyin. Böylece hatanın hangi değişiklikten sonra düzeldiği anlaşılır ve sorun sürerse önceki duruma güvenli biçimde dönebilirsiniz.

Nginx ayarları içinde önce hangi kanıtı aramalı?

1. Hatanın kapsamını netleştirin. Aynı URL’yi, hata oluştuğu saatle birlikte kaydedin. Sorun yalnızca bir uygulama yolu veya sanal host için ortaya çıkıyorsa ilgili sunucu bloğunu inceleyin; bütün siteler etkileniyorsa ortak Nginx, ağ veya uygulama katmanını değerlendirin. Bu ayrım, yanlış siteye ait ayarı değiştirmenizi önler.
2. Yeni hata günlüğü satırını bulun. Nginx’in error log kaydı genellikle yapılandırmada belirtilen günlük konumunda, sanal hosta ayrılmış log alanında veya dağıtımın sistem günlükleme hizmetinde tutulur. Aynı isteği yeniden göndermeden önce eski satırları saatleriyle ayırın. Connection refused uygulamanın portta dinlemediğini ya da yanlış port seçildiğini; timed out ise uygulamanın geç yanıt verdiğini, ağ filtresi bulunduğunu veya işlemin kilitlendiğini düşündürür. Bu iki bulgu aynı düzeltmeyi gerektirmez.
3. Upstream hedefini uygulamayla karşılaştırın. İlgili Nginx sunucu bloğunda proxy_pass veya upstream tanımının hangi adres, port ya da Unix soketine işaret ettiğini bulun. Uygulama yöneticisinin yapılandırmasında gerçekten hangi adreste dinleme yapıldığına bakın. Günlükte bağlantı reddedildiği ve Nginx’in 127.0.0.1:9000 gibi artık kullanılmayan bir porta gönderdiği görülüyorsa, uygulamanın güncel dinleme adresini doğrulayıp yalnızca upstream hedefini düzeltin; zaman aşımını artırmak bu durumda çözüm değildir.
4. Yapılandırma sözdizimini doğrulayın. Değişiklikten sonra, Nginx’in kurulu olduğu sunucuda yetkili bir kabukla yalnızca okuma ve doğrulama yapan nginx -t komutunu çalıştırabilirsiniz. Kullanılan kurulum farklı bir yapılandırma dosyası veya yönetim aracı belirtiyorsa aynı doğrulamayı o aracın sunduğu test işlevinden yapın. Beklenen sonuç sözdiziminin geçerli olduğunu ve testin başarılı tamamlandığını belirten bir çıktıdır; hata varsa servisi yeniden yüklemeyin, önce bildirilen dosya ve satırdaki değişikliği düzeltin.
5. Değişikliği kontrollü biçimde etkinleştirip doğrulayın. Sözdizimi testi başarılıysa Nginx’i durdurup başlatmak yerine, dağıtımınızın yapılandırmayı yeniden yükleme yöntemini kullanın; bu işlem mevcut bağlantıları gereksiz yere kesme riskini azaltır. Ardından aynı URL ve aynı işlemle 502 hatasını tekrar üretmeye çalışın. Yeni istek saatine ait Nginx error log satırını ve uygulama logunu birlikte inceleyin. 502 kaybolup uygulama yanıtı dönüyorsa düzeltme doğrulanmıştır; yeni bir hata oluşmuşsa ilk kaydın bütün nedeni açıkladığını varsaymadan yeni bulguyu ayrı değerlendirin.

Log sonucuna göre güvenli düzeltme

Bağlantı reddediliyor veya portta dinleme yok

Uygulama işlemi çalışmıyor, farklı bir portta dinliyor veya yalnızca başka bir arayüzde bağlantı kabul ediyor olabilir. Uygulama servisinin kendi durum ekranını ve başlangıç logunu kontrol edin. İşlem durmuşsa, sağlayıcının veya uygulamanın belgelenmiş yönetim yöntemiyle onu başlatın; Nginx’e rastgele port yazmayın. Uygulama yeni bir portta dinliyorsa önce mevcut değeri kaydedin, yalnızca upstream portunu bu doğrulanmış değerle değiştirin ve yapılandırma testini tekrarlayın.

Bağlantı zaman aşımına uğruyor

Bu bulgu, isteğin uygulamaya ulaştığı halde uygulamanın zamanında yanıt üretmediğini veya aradaki bağlantının engellendiğini gösterebilir. Uygulama logunda aynı zaman aralığında yavaş sorgu, kilitlenme ya da kaynak tükenmesi kaydı arayın. Yalnızca uzun süren ve beklenen bir işlem olduğu kanıtlanırsa ilgili proxy zaman aşımını küçük bir artışla ele alın; önce uygulamanın neden yavaşladığını incelemeden tüm zaman aşımı sınırlarını yükseltmeyin. Sorun bir güvenlik filtresinden kaynaklanıyorsa filtreyi kapatmak yerine izin verilen hedef ve port politikasını yönetin.

Hipotetik bir değerlendirme

Örneğin, varsayımsal bir mağaza uygulamasında yalnızca /checkout yolu 502 döndürsün ve Nginx günlüğünde bağlantının 127.0.0.1:8080 adresine reddedildiği görülsün. Uygulama logu ise işlemin 127.0.0.1:8081 üzerinde başlatıldığını gösteriyorsa en uygun adım, yalnızca checkout isteğinin kullandığı upstream portunu doğrulanmış 8081 değeriyle eşleştirmektir. Buna karşılık aynı kayıtta zaman aşımı görülseydi portu değiştirmek yerine checkout işleminin uygulama logundaki bekleme nedenini araştırmak gerekirdi.

Düzeltme sonrasında aynı checkout isteğini yeniden gönderin ve yeni zaman damgalı Nginx ile uygulama kayıtlarını kontrol edin. 2xx veya uygulamanın beklenen yönlendirmesi alınır ve yeni 502 satırı oluşmazsa işlem tamamlanabilir. Hata sürerse son değişikliği geri alıp kayıtları saklayın; ardından upstream’in ağ erişimi, uygulama servisi ve sağlayıcıya özgü proxy kuralları için destek alın. Yapılandırma yedeğini ve kimlik bilgilerini herkese açık kanallarda paylaşmayın.

Sunucu yönetimi, barındırma ortamı veya uygun yapılandırma yaklaşımını karşılaştırırken İyibirNet üzerindeki ilgili kaynaklara göz atabilirsiniz.