502 Bad Gateway Açıklaması: Ne Anlama Gelir, Neden Olur ve Nasıl Sorun Giderilir

Anahtar Kelimeler

Bu hızlı sözlük, daha derin açıklama aşamasında en çok kafa karışıklığına yol açabilecek altyapı terimlerini kapsamaktadır.

502 Hatasının Neden Bu Kadar Rahatsız Edici Hissettirdiği

Bir dağıtım yaparsınız, siteyi yeniden yüklersiniz ve alan adı anında yanıt verir — ama uygulamanızla değil. Ya da bir müşteri Ödeme’ye tıklar, sayfa yüklenir ve işlem sert bir 502 Bad Gateway mesajının arkasında çöker. Bu hatayı bu kadar stresli yapan da budur: site erişilebilir durumdadır, ancak aktarımı tamamlayacak kadar sağlıklı değildir.

502, garip bir orta durumda yer alır. Tam bir kaybolma gibi görünmez, ama çalışan bir hizmet gibi de davranmaz. Geliştiriciler için bozuk bir dağıtım veya API zinciri anlamına gelebilir. İşletme sahipleri için kayıp güven veya kesintiye uğrayan gelir. Ekipler için ise en kötü kısım genellikle sahiplik sorusudur: sorunu aslında hangi katman üstleniyor?

Bu konuya yaklaşmanın yararlı yolu tahmin yürütmemektir. Önce hatanın ne anlama geldiğini tanımlayın. Ardından istek zincirinde nerede yer aldığını belirleyin. Sonra arızayı mantıksal olarak, her aktarımı tek tek ele alarak giderin. Zinciri görebildiğinizde hata rastgele görünmeyi bırakır.

502 Bad Gateway Gerçekte Ne Anlama Gelir

Bir 502 Bad Gateway hatası genellikle gateway veya proxy olarak görev yapan bir sunucunun, arkasındaki bir sonraki katmandan aldığı yanıtı kullanamadığı anlamına gelir. Sade bir dille ifade etmek gerekirse: bir sunucu isteğinizi başka bir sunucuya iletmeye çalıştı ve bu aktarım, ön yüzlü sunucunun normal bir sonuç döndüremeyeceği kadar kötü bir şekilde başarısız oldu.

📝 Not: Upstream kendi geçerli HTTP hatasını döndürürse, proxy bu hatayı genellikle iletir. Uygulama gerçek bir 503 Service Unavailable döndürürse, ön katman normalde o 503‘ü aktarmalı, 502 üretmemelidir. 502, yanıtın kendisinin kullanılamaz olduğu anlamına gelir. Zamanında kullanılabilir bir yanıt gelmezse, bu çoğunlukla 504 olur.

5xx hatalarını yanlış yorumlamayı bırakmanın en hızlı yolu, bunları arızanın nerede yaşandığına ve hangi soruyu önce tetiklediğine göre ayırt etmektir:

⚠️ Uyarı: 500, 502, 503 ve 504‘ü tek bir genel “sunucu çöktü” kategorisinde toplamayın. Bunlar farklı arıza biçimlerine işaret eder ve bu durum önce neyi kontrol etmeniz gerektiğini değiştirir.

Bu tanım netleştikten sonra bir sonraki soru çok daha kullanışlı hale gelir: gerçek bir yığında bu başarısız aktarım tam olarak nerede gerçekleşir?

Hata Gerçek Bir İstek Zincirinde Nerede Oluşur

Modern isteklerin çoğu tarayıcıdan uygulamaya doğrudan gitmez. Katmanları aşar: tarayıcıdan CDN veya edge’e, edge’den reverse proxy veya load balancer’a, proxy’den uygulama sürecine. 502, bu aktarım noktalarından birinde görünür hale gelir.

Basitleştirilmiş istek zinciri: Tarayıcı → CDN/Edge → Reverse Proxy / Load Balancer → Uygulama / Süreç

Bir reverse proxy, genel isteği kabul eder ve dahili olarak iletir. Bir load balancer da benzer bir şey yapar, ancak birden fazla sağlıklı hedef arasında seçim yapabilir. Her iki durumda da ön katman, iş mantığını kendisi yürütmek yerine isteği yönlendirmektedir.

Resepsiyon analojisi burada iyi çalışır. Proxy’yi bir ofis binasındaki resepsiyon olarak düşünün. Ziyaretçiyi karşılar, doğru ofisi arar ve ziyaretçiyi oraya yönlendirmeye çalışır. Ofis yanıt vermezse, yanlış hattan yanıt verirse veya resepsiyonun kullanamayacağı bir yanıt dönerse, resepsiyon başarısızlığı bildirir. Bu nedenle görünür hata, daha derin neden başka bir yerde olsa bile genellikle proxy katmanında ortaya çıkar.

📝 Not: Proxy çoğunlukla arızanın habercisidir, asıl nedeni değil.

Bu resepsiyonun arkasındaki “bir sonraki sunucu” bir port üzerinde normal bir HTTP hizmeti, 127.0.0.1:3000 gibi bir uygulama dinleyicisi veya PHP-FPM gibi yerel socket tabanlı bir süreç olabilir. Temel sorunun proxy’de bulunması gerekmez. Kötü bir dağıtım, çökmüş bir uygulama işçisi veya hatta bir veritabanı arızası, backend’i 502’nin yalnızca yüzeye çıktığı yer olan proxy’yi etkileyecek kadar bozabilir.

Edge hizmetleri bir katman daha ekler. Cloudflare gibi bir CDN, yığınınızın derinliklerinden gelen origin taraflı bir 502’yi iletebilir ya da edge’den origin’e aktarım başarısız olduğunda kendi başına bir 502 üretebilir. Bu nedenle “bu hatayı kim döndürdü?” sorusu sonradan akla gelen bir şey değil, ilk pratik sorudur.

502 Hatalarının Neden Oluştuğu: Ana Arıza Kategorileri

502’yi tek bir gizemli olay olarak ele almayı bıraktığınızda, neden ortamı çok daha yönetilebilir hale gelir. Olayların çoğu üç yeniden kullanılabilir kategoriye girer: upstream kullanılamaz durumda, aktarımın kendisi yanlış yapılandırılmış veya yanıt gateway’in kullanamayacağı bir biçimde geri dönüyor.

Birinci kategori açık olanıdır: upstream kullanılabilir durumda değildir. Belki uygulama dağıtımdan sonra çöktü. Belki hizmet hiç yeniden başlatılmadı. Belki bir PHP-FPM havuzu öldü ya da bir hedef sağlıksız olarak işaretlenip rotasyondan çıkarıldı. Bu klasik “hizmet çöktü” senaryosudur, ancak 502 ortamının yalnızca bir dilimidir.

İkinci kategori aktarım uyumsuzluğudur. Burada her iki katman da çalışıyor olabilir, ancak birbirlerine nasıl ulaşacakları konusunda anlaşmazlık yaşarlar. Proxy yanlış porta işaret ediyor olabilir. Bir ana bilgisayar adı yanlış çözümlenebilir. Bir güvenlik duvarı yolu engelleyebilir. Bir katman HTTPS beklerken diğeri yalnızca düz HTTP konuşuyor olabilir. Bir socket yolu değişmiş olabilir. Bu durumlarda uygulama sağlıklı olabilir ve katmanlar arasındaki bağlantı yine de bozuk olabilir.

Üçüncü kategori daha karmaşıktır: upstream yanıt verir, ancak gateway’in kullanabileceği bir biçimde değil. Bir hedef TCP bağlantısını sıfırlayabilir, çok erken kapatabilir, hatalı biçimlendirilmiş veya aşırı büyük başlıklar gönderebilir ya da yük altında kısmi çıktı döndürebilir. Uygulama basitçe “kapalı” değildir; gateway’in aldığını reddedecek kadar kötü yanıt vermektedir.

Bu aynı zamanda 502’nin yalnızca bir zaman aşımı hikayesi olmadığının da nedenidir. Bazı zaman aşımı durumları 502 değil 504 Gateway Timeout olur. Cloudflare, origin bağlantısı veya sıkıştırma bozulduğunda edge tarafından üretilen 502’leri yüzeye çıkarabilir. Load balancer’lar, kayıt silme zamanlama sorunları veya TLS el sıkışma hataları sırasında 502 yayabilir. “Hizmet çöktü” bir neden kategorisidir, hatanın tanımı değil.

Bu zihinsel model, bir yapılandırma dosyasına dokunmadan önce size gerçek bir kontrol listesi sunar. Muhtemelen hangi kategoride olduğunuzu sorun, ardından kanıt arayın. Bu, sorun giderme dizisini ritüelistik yerine mantıklı hissettiren şeydir.

502 Hataları için Akıllı Bir Sorun Giderme Dizisi

Bir 502’yi gidermenin en hızlı yolu, hangi katmanın döndürdüğünü belirlemek, ardından herhangi bir şeyi değiştirmeden önce o katmanın arkasındaki bir sonraki atlamayı test etmektir. Amaç, başarısız aktarımın nerede yaşandığını kanıtlamaktır.

💡 İpucu: Herhangi bir şeyi yeniden başlatmadan veya düzenlemeden önce, 502‘yi kimin döndürdüğünü belirleyin. Temiz bir atıf adımı, insanların baskı altında denediği ilk beş “düzeltme”den genellikle daha fazla zaman kazandırır.

Aşama 1: Katmanı belirleyin

İnternete bakan katmanın gerçekte ne döndürdüğünü sorarak genel taraftan başlayın:

curl -I https://example.com

Bu, genel URL’den HTTP durumunu ve başlıkları gösterir. Başlıklar açıkça bir CDN, load balancer veya reverse proxy’ye aitse, ilk ipucunuzu elde etmişsinizdir. Hata sayfası Cloudflare markalıysa, Cloudflare 502’yi kendisi üretmiş olabilir; markasızsa, edge yalnızca origin taraflı bir arızayı iletiyor olabilir. cf-error-type veya cf-error-origin gibi başlıklar Cloudflare tarafından üretilen hata sayfalarında görünebilir; bu, tam olarak her 502’de görünmedikleri için kullanışlıdır.

📝 Not: Yalnızca bir ziyaretçi hatayı görürken diğerleri siteye erişebiliyorsa, yerel VPN, proxy, güvenlik duvarı veya DNS ayarları yine de sorunun bir parçası olabilir. 502 genellikle sunucu taraflıdır, ancak izole edilmiş bir istemci yolu gözlemlediğiniz şeyi bulanıklaştırabilir.

Aşama 2: Upstream yolunu doğrulayın

Hangi katmanın 502 döndürdüğünü öğrendikten sonra, arkasındaki bir sonraki atlamayı test edin. Bir reverse proxy söz konusuysa, hem proxy’nin hem de backend hizmetinin çalıştığını doğrulayın ve beklenen dinleyicinin var olduğunu onaylayın:

systemctl status nginx
systemctl status <app-service>
ss -tlnp

<app-service> yerine backend hizmet adınızı yazın. systemctl status, proxy veya uygulama sürecinin çalışıp çalışmadığını, başarısız olup olmadığını veya yeniden başlatılıp başlatılmadığını söyler. ss -tlnp, beklediğiniz portta gerçekten bir şeyin dinleyip dinlemediğini gösterir.

Ardından backend’in proxy olmadan doğrudan yanıt verip vermediğini test edin:

curl -i http://127.0.0.1:3000

Doğrudan istek çalışıyor ancak genel URL hâlâ 502 döndürüyorsa, backend sağlıklı olabilir ve asıl sorun aktarım olabilir. Bu, sizi yalnızca uygulama kodundan ziyade proxy hedef ayarlarına, protokol uyumsuzluklarına, upstream ana bilgisayar adlarına, TLS beklentilerine veya güvenlik duvarı kurallarına yönlendirir.

Aşama 3: Komutları tören olarak değil kanıt olarak kullanın

Doğrudan kontrollerden sonra, aktarımın neden başarısız olduğunu açıklayan kanıtlara geçin:

journalctl -u nginx -u <app-service> --since "15 min ago"
dig +short example.com
nginx -t

Bu üç kontrol farklı soruları yanıtlar. journalctl, son çökmeleri, sıfırlamaları, zaman aşımı ipuçlarını ve dağıtımla ilgili arızaları ortaya çıkarır. dig +short, bağımlı olduğunuz ana bilgisayar adının sunucunun beklediği şekilde çözümlenip çözümlenmediğini söyler. nginx -t, herhangi bir şeyi yeniden yüklemeden önce reverse-proxy sözdizimini doğrular; bu önemlidir çünkü hatalı bir upstream tanımı, backend sağlıklı olsa bile 502 üretebilir.

Pratik sinyaller genellikle şöyle görünür:

Hatırlanması gereken temel model budur: katmanı belirleyin, bir sonraki atlamayı doğrulayın, ardından uyumsuzluğu açıklamak için günlükleri ve doğrudan testleri kullanın. Önce kanıt. Sonra ayarlar.

Sorun Giderme Yolunun Hosting Modeline Göre Nasıl Değiştiği

502 sonrasındaki bir sonraki adım, yığının ne kadarını kontrol ettiğinize bağlıdır. Sorun giderme mantığı aynı kalır, ancak kendiniz inceleyebileceğiniz miktar paylaşımlı hosting, VPS, dedicated sunucular ve edge-proxy kurulumları arasında büyük ölçüde değişir.

📝 Not: Paylaşımlı hostingde yükseltme yapmak kaçamak değildir. Genellikle doğru teknik adımdır, çünkü 502 için en önemli katmanlar görünürlüğünüzün dışında olabilir.

Paylaşımlı hostingde yapabileceğiniz en yararlı şey kanıt toplamaktır: zaman, etkilenen URL, hatanın sürekli mi yoksa aralıklı mı olduğu ve bir dağıtım veya yapılandırma değişikliğinden sonra mı başladığı. Bu, desteğe eyleme geçirilebilir bir şey verir. Reverse proxy’yi, uygulama hizmetini veya sunucu günlüklerini kontrol etmiyorsanız, anlamlı katman katman tanı hızla sona erer.

Bir VPS’te, hizmetleri, dinleyicileri, günlükleri ve proxy yapılandırmasını doğrudan inceleyebildiğiniz için tam iş akışı gerçekçi hale gelir. Reverse-proxy sorun giderme işleminin ait olduğu yer burasıdır. AlexHost VPS altyapısında systemctl, journalctl, ss, upstream hedefleri ve Nginx yapılandırmasını kontrol etmek, her zaman destek arkasında gizlenen bir şey değil, normal sahipliğin bir parçasıdır.

Dedicated sunucu size aynı görünürlüğü sağlar, ancak daha fazla sorumlulukla birlikte. Tam yığının daha fazlasına ve muhtemelen çevresindeki ağ varsayımlarının da daha fazlasına sahipsinizdir. Önüne bir CDN veya başka bir edge hizmeti eklerseniz, ilk sahiplik sorusu aynı kalır: edge 502’yi kendisi mi üretti, yoksa origin taraflı bir arızayı mı iletti? Daha fazla kontrol, sorun gidermeyi varsayılan olarak daha basit yapmaz. Size inceleyecek daha fazla yer verir.

Panikle Değil, Katmanlarla Düşünün

Bir 502 Bad Gateway hatası, genellikle ne olduğunu kabul ettiğinizde gizemli olmaktan çıkar: rastgele bir tarayıcı olayı değil, başarısız bir sunucudan sunucuya aktarım. Tarayıcı yalnızca fark ettiğiniz yerdir. Gerçek hikaye, isteği bir sonrakine ileten ve kullanılabilir bir şey geri alamayan katmanda yaşar.

Bu nedenle diziyi basit tutun: katmanı belirleyin, bir sonraki atlamayı kontrol edin, doğrudan testler ve günlüklerle doğrulayın ve yalnızca kanıt belirli bir yere işaret ettiğinde ayarları değiştirin. Tekrarlayan olaylar sizi daha derin günlük, proxy ve hizmet görünürlüğüne doğru itmeye devam ediyorsa, bu daha yüksek kontrollü ortamların — AlexHost VPS veya dedicated sunucular dahil — pazarlama nedenleriyle değil, operasyonel nedenlerle kullanışlı hale geldiği noktadır. Burada yöntem, ezberi geçer.