Nginx Ayarları: 502 Hatasını Güvenle Teşhis Etme

Nginx ayarları nedeniyle görülen 502 Bad Gateway hatasında ilk bakılacak yer tarayıcı değil, Nginx ile arka uç uygulaması arasındaki bağlantıdır. Önce hatanın saatini not edin, ilgili hata günlüğünü ve uygulamanın dinlediği adresi karşılaştırın. Yapılandırmayı yedekleyip tek bir değişiklik yaptıktan sonra aynı URL isteğini yeniden gönderin ve yeni zaman damgalı kaydı inceleyin.

Önce kapsamı ve erişimi belirleyin

Bu işlem, Nginx yapılandırmasına ve sunucu günlüklerine erişebildiğiniz, yöneticisi olduğunuz bir Linux sunucusu için geçerlidir. Paylaşımlı hosting panelinde global Nginx dosyalarını değiştiremezsiniz; böyle bir ortamda yalnızca panelin sunduğu alan adı, ters proxy veya uygulama ayarlarını kullanabilir ve sağlayıcıdan ilgili hata kaydını isteyebilirsiniz. Yetkisiz bir sunucuda servis yeniden başlatmaya ya da dosya değiştirmeye çalışmayın.

502, Nginx'in istemciden gelen isteği aldığını fakat arka uçtan kullanılabilir bir yanıt alamadığını gösterir. Bu arka uç bir PHP-FPM havuzu, Node.js uygulaması veya başka bir HTTP servisi olabilir. Connection refused kaydı uygulamanın çalışmadığını ya da yanlış porta yönlendirildiğini; upstream timed out kaydı yanıtın zamanında gelmediğini; geçersiz başlık veya protokol kaydı ise Nginx'in beklediği HTTP yanıtını alamadığını düşündürür. Bu belirtiler aynı düzeltmeyi gerektirmez.

502 hatasını güvenli biçimde ayırma adımları

1. Aynı isteği tanımlayın: Hata görülen alan adını, URL'yi ve yaklaşık saati not edin; mümkünse yalnızca sorunlu isteği yeni bir tarayıcı sekmesinde bir kez tekrarlayın. Ardından Nginx'in yapılandırmada tanımlanan error log kaynağında bu saate ait yeni satırı bulun. Kayıt yoksa yanlış sanal sunucuya bakıyor, farklı bir Nginx örneği kullanıyor veya istek Nginx'e ulaşmıyor olabilirsiniz; bu durumda yapılandırma dosyasındaki ilgili server bloğunu ve erişim günlüğünü doğrulamadan değişiklik yapmayın.
2. Upstream hedefini karşılaştırın: Hata satırındaki adresi, ilgili proxy_pass veya FastCGI hedefiyle karşılaştırın. Örneğin kayıt 127.0.0.1:3000 adresine bağlantının reddedildiğini söylüyorsa, uygulamanın gerçekten bu portta dinleyip dinlemediğini yönetim panelinden veya servis yöneticisinden kontrol edin. Uygulama başka bir portta çalışıyorsa düzeltme Nginx'in zaman aşımı değil, hedef adresinin uygulamanın gerçek dinleme adresiyle eşleştirilmesidir. Aynı anda birden fazla ayarı değiştirmeyin.
3. Uygulama durumunu ve protokolü kontrol edin: Uygulama çalışıyor ve hedef doğru olduğu hâlde hata sürüyorsa uygulama günlüğünde aynı dakikaya ait başlatma, çökme veya bağlantı reddi kaydını arayın. Nginx HTTP sunucusuna bağlanacak şekilde ayarlanmışken hedef yalnızca farklı bir protokol bekliyorsa geçersiz yanıt oluşabilir. Burada yalnızca kullanılan entegrasyonun dokümantasyonunda belirtilen protokolü ve soket/port eşleşmesini düzeltin; güvenlik denetimlerini devre dışı bırakmayın.
4. Zaman aşımı belirtisini ayrı ele alın: Kayıt bağlantının kurulduğunu fakat yanıtın belirli süre içinde gelmediğini söylüyorsa, önce uygulamanın yavaş sorgu, dış servis çağrısı veya kaynak beklemesi yaşayıp yaşamadığını inceleyin. Kısa bir istekte de aynı kayıt oluşuyorsa önce uygulamanın erişilebilirliğini ve kaynak durumunu düzeltin. Yalnızca işlem gerçekten uzun sürmesi beklenen bir işlemse, mevcut Nginx zaman aşımı değerini kaydedip küçük ve tek bir artış yapın; bu değişiklik yavaş uygulama kodunu hızlandırmaz ve istemci bağlantısının da ayrı sınırları olabilir.
5. Yapılandırmayı doğrulayıp sonucu ölçün: Değişiklikten önce ilgili dosyanın veya panel değerinin özgün hâlini güvenli bir yedek olarak saklayın. Nginx'in yapılandırma testini çalıştırın; test hata verirse servisi yeniden yüklemeyin ve sözdizimi hatasını düzeltin. Test başarılıysa yalnızca ilgili yapılandırmayı yeniden yükleyin. Sonra ilk adımda not ettiğiniz aynı URL'yi yeniden isteyin ve isteğin gerçekleştiği yeni saate ait Nginx hata günlüğünü kontrol edin. 2xx veya beklenen uygulama yanıtı ve yeni upstream hatasının oluşmaması olumlu işarettir; farklı bir hata çıktıysa önceki kaydın tüm nedeni açıkladığını varsaymayın.

Nginx ayarları içinde hangi düzeltme ne zaman uygundur?

Örneğin, varsayımsal bir Node.js uygulaması 3000 portunda çalışırken Nginx günlüğü sürekli olarak 127.0.0.1:8080 için connection refused kaydı üretsin. Uygulamanın dinleme portu doğrulanır ve 3000 olduğu görülürse hedef portunu 3000 ile eşleştirmek mantıklıdır; zaman aşımını yükseltmek bu bağlantı reddini çözmez. Değişiklik sonrası aynı URL başarılı olursa ve yeni logda reddedilen 8080 bağlantıları oluşmazsa düzeltme hedef eşleşmesine dayanır.

Buna karşılık hedef doğru, uygulama ayakta ve kayıt upstream timed out ise karar farklıdır. Kısa istekler de zaman aşımına uğruyorsa uygulama günlüğü, veritabanı beklemeleri ve işlemci/bellek baskısı incelenmelidir. Yalnızca rapor oluşturma gibi uzun sürmesi beklenen isteklerde süre sınırını ölçülü biçimde ele almak gerekir. Bir değeri artırmak yerine tüm limitleri topluca yükseltmek, kaynak tüketimini ve bekleyen bağlantı sayısını artırarak sorunu ağırlaştırabilir.

Değişiklik işe yaramazsa güvenli geri dönüş

Aynı istek yeni hata kaydı üretmeye devam ediyorsa son değiştirdiğiniz tek değeri özgün hâline döndürün; özellikle zaman aşımını artırdıysanız, uygulama düzelmeden yüksek değeri kalıcı bırakmayın. Yapılandırma testi başarısızsa önceki çalışan kopyaya dönmek, servisi zorla yeniden başlatmaktan daha güvenlidir. Hata başka bir upstream adresine, TLS katmanına veya uygulama içi yanıta işaret ediyorsa ilk düzeltmeyi genişletmeden yeni belirtiyi ayrı değerlendirin.

Sonraki güvenli adım

Sunucu yönetimi veya barındırma seçimiyle ilgili kapsamı netleştirmek için İyibirNet üzerindeki ilgili bilgileri inceleyebilirsiniz. Elinizdeki hata satırını paylaşmanız gerekiyorsa alan adı, IP, çerez, erişim belirteci ve kişisel verileri çıkardıktan sonra yalnızca gerekli zaman aralığını kullanın; kimlik bilgilerini veya tam günlük dosyalarını herkese açık yerlere göndermeyin.