Nginx 502 Bad Gateway Hatası: PHP-FPM ve Sunucu Bağlantısını Nasıl Kontrol Edebilirsiniz?

Siteyi açtınız ve karşınıza “502 Bad Gateway” çıktı. Birkaç dakika önce çalışan uygulamanın bir anda cevap vermemesi insanı doğrudan servisleri yeniden başlatmaya yöneltebilir. Ama ilk iş olarak hatanın nerede oluştuğunu anlamak, sorunu çözmek ve tekrarlamasını önlemek açısından daha faydalıdır.

Bu yazıda Linux üzerinde Nginx ve PHP-FPM kullanan bir uygulamada 502 hatasını nasıl araştırabileceğinizi adım adım ele alacağım. Örnekler Ubuntu ve Debian benzeri sistemleri temel alıyor. HestiaCP, cPanel veya başka bir yönetim paneli kullanıyorsanız dosya yolları ve servis adları farklı olabilir.

502 ne anlama geliyor?

Nginx, isteği kendisinden sonraki bir servise ilettiğinde geçerli bir yanıt alamazsa 502 döndürebilir. Bu servis PHP-FPM olabileceği gibi Apache, Node.js veya başka bir uygulama sunucusu da olabilir. Eğer sitenin önünde bir CDN ya da başka bir proxy varsa, hatayı bu katman da göstermiş olabilir.

Bu yüzden “502 gördüm, kesin PHP bozuldu” demek doğru olmaz. Önce isteğin hangi katmanlardan geçtiğini öğrenin. Bu rehberde şu basit yolu ele alıyoruz:

Ziyaretçi → Nginx → PHP-FPM → Uygulama

Gerçek sisteminizde Nginx ile PHP-FPM arasında Apache bulunabilir ya da önlerinde Cloudflare gibi bir katman olabilir. İstek zincirini bilmek, yanlış serviste arama yapmanızı önler.

1. Hatanın kapsamını belirleyin

Sorun tüm sitede mi, yalnızca belirli bir sayfada mı? Statik görseller ve CSS dosyaları açılırken PHP sayfaları hata veriyorsa uygulama katmanına bakmak mantıklıdır. Ancak bu durum tek başına PHP-FPM'nin suçlu olduğunu kanıtlamaz.

İlk kontrol için kendi alan adınızda basit bir GET isteği yapabilirsiniz:

curl -sS -o /dev/null -w 'HTTP: %{http_code}\n' \
  --max-time 15 https://example.com/

example.com yerine kendi adresinizi yazın. Bazı koruma sistemleri otomatik isteklere farklı yanıt verebilir; sonucu tarayıcıdaki durumla birlikte değerlendirin. HEAD istekleri bazı sitelerde farklı işlendiği için bu örnekte normal GET kullanıyoruz. Önbellek veya CDN devredeyse gördüğünüz yanıt doğrudan uygulamadan gelmeyebilir.

2. İlgili servisleri bulun ve durumlarını inceleyin

Önce Nginx'in durumuna bakın:

systemctl status nginx --no-pager

Ardından yüklü PHP servislerini listeleyin:

systemctl list-units --type=service --all | grep -i php

Listede örneğin php8.3-fpm.service görüyorsanız onu ayrıca inceleyebilirsiniz:

systemctl status php8.3-fpm --no-pager

Buradaki sürüm sadece örnektir; kendi çıktınızdaki servis adını kullanın. Ayrıca terminaldeki php -v sonucunun web sitesinin kullandığı PHP-FPM sürümüyle aynı olması gerekmez. Bir sunucuda birden fazla PHP sürümü veya siteye özel havuz bulunabilir.

Servisin “active” görünmesi iyi bir işarettir ama her isteği sağlıklı işlediği anlamına gelmez. İlgili havuz, bağlantı yolu veya uygulama yine sorunlu olabilir.

3. Hata kayıtlarını zamanla eşleştirin

Kayıtlara bakarken sorunun yaşandığı zamanı bilmek işinizi kolaylaştırır. Aşağıdaki komutlar son yarım saatteki servis günlüklerinden sınırlı sayıda kayıt gösterir:

sudo journalctl -u nginx --since '30 minutes ago' -n 80 --no-pager
sudo journalctl -u php8.3-fpm --since '30 minutes ago' -n 80 --no-pager

Servis adını kendi sisteminize göre değiştirin. Nginx veya PHP hataları sistem günlüğü yerine siteye özel dosyalara da yazılıyor olabilir. Yönetim panelinizin alan adı için tanımladığı hata günlüğünü de kontrol edin.

Günlüklerde şu ipuçlarına bakın:

• No such file or directory: Nginx'in ulaşmaya çalıştığı soket dosyası bulunamıyor olabilir.
• Permission denied: Soket veya ilgili dizin izinlerini incelemek gerekir.
• Connection refused: Hedefte dinleyen servis olmayabilir ya da bağlantı farklı bir adrese yönleniyor olabilir.
• Primary script unknown: Uygulamaya iletilen dosya yolu ve belge kökü incelenmelidir.

Bunların her biri bir başlangıç noktasıdır; tek bir mesajı görüp bütün sistemin nedenini kesinleştirmeyin. Günlükleri başkalarıyla paylaşmadan önce istemci verilerini, gizli URL parametrelerini ve diğer hassas bilgileri ayıklayın.

4. Nginx ile PHP-FPM aynı adrese mi bakıyor?

PHP-FPM bağlantısı bir Unix soketi veya TCP adresi kullanabilir. Nginx'teki fastcgi_pass değeriyle ilgili PHP-FPM havuzunun listen değeri birbiriyle uyumlu olmalıdır.

Örnek olarak aşağıdaki satır bir soket adresini gösterir:

fastcgi_pass unix:/run/php/php8.3-fpm.sock;

Bu satırı doğrudan kendi yapılandırmanıza kopyalamayın: yol, sürüm ve havuz adı sunucuya göre değişir. PHP-FPM TCP üzerinde de dinliyor olabilir. Nginx'in bu iki bağlantı biçimini nasıl kullandığını resmî FastCGI modülü belgelerinde inceleyebilirsiniz.

Gerçek soket yolunu öğrendikten sonra varlığını ve izinlerini kontrol edin:

ls -l /run/php/

Dosyanın var olması tek başına yeterli değildir; Nginx veya bağlantıyı yapan servisin sokete ve yol üzerindeki dizinlere erişebilmesi gerekir. İzin hatası gördüğünüzde bütün dizinlere geniş yazma yetkisi vermek yerine, ilgili servis kullanıcısını, grup üyeliğini ve PHP-FPM havuz ayarlarını inceleyin.

5. Kaynakları ve yapılandırmayı kontrol edin

Diskin veya inode'ların dolması da farklı servis hatalarına yol açabilir. Bellek ve disk durumunu hızlıca görmek için:

df -h
df -i
free -h

Sunucu kaynakları sağlıklı görünse de uygulama düzeyinde bir hata bulunabilir. PHP-FPM ve Nginx günlüklerinin yanında uygulamanın kendi hata kayıtlarına da bakın.

Nginx yapılandırmasında bir değişiklik yaptıysanız, uygulamadan önce sözdizimini kontrol edin:

sudo nginx -t

Bu test sözdizimi ve bazı erişim sorunlarını yakalar; uygulamanın uçtan uca çalıştığını garanti etmez. Bir yönetim paneli yapılandırmaları yeniden oluşturuyorsa, değişikliği panelin desteklediği yöntemle yapın. Aksi hâlde elle yapılan düzeltme sonraki yeniden oluşturmada kaybolabilir.

Yeniden başlatmak neden ilk adım olmamalı?

Bir servis yeniden başlatıldığında site geçici olarak düzelebilir. Ancak sorun bellek baskısı, hatalı soket yolu veya uygulamanın belli bir istekte kilitlenmesiyse aynı durum yeniden yaşanabilir. Önce zaman damgasını, servis durumunu ve ilgili hata mesajını kaydetmek sonraki inceleme için değerli olur.

Sorunu giderdikten sonra yalnızca ana sayfayı değil, hata veren asıl sayfayı da yeniden deneyin. Yönetim paneli, API veya kuyruk gibi farklı bileşenler varsa, yaptığınız değişikliğin onları etkileyip etkilemediğini ayrıca kontrol edin.

502, tek bir nedene işaret eden sihirli bir hata kodu değil; isteğin geçtiği katmanlardan birinde cevap beklediğiniz gibi gelmediğini söyleyen bir başlangıç noktasıdır. Katmanları sırayla incelemek, rastgele ayar değiştirmekten çok daha açıklayıcı sonuç verir.