Nginx 504 Gateway Timeout Hatası Nasıl Çözülür? Nedenleri ve Çözümleri

Nginx 504 Gateway Timeout hatası, Nginx'in proxy olarak bağlandığı backend sunucudan belirlenen süre içerisinde yanıt alamadığını gösterir. Node.js uygulamasının yavaşlaması, uzun süren veritabanı sorguları, harici API gecikmeleri, yüksek CPU veya RAM kullanımı ve yanlış timeout ayarları bu hataya neden olabilir.

504 hatasında ilk yapılması gereken şey timeout süresini hemen artırmak değil, backend'in neden zamanında cevap veremediğini bulmaktır.

504 ile 502 arasındaki fark nedir?

Bu iki hata sıkça karıştırılır.

502 Bad Gateway: Nginx backend'den geçerli bir yanıt alamıyor veya backend'e bağlantı kurulamıyor olabilir.

504 Gateway Timeout: Nginx backend'e ulaşmış olabilir ancak gerekli yanıt belirlenen süre içerisinde tamamlanmamıştır.

Bu ayrım sorunun kaynağını bulmayı kolaylaştırır.

İlk olarak Nginx error logunu kontrol edin

Yaygın log konumu:

/var/log/nginx/error.log

Son kayıtları görmek için:

sudo tail -n 100 /var/log/nginx/error.log

Canlı takip:

sudo tail -f /var/log/nginx/error.log

504 oluştuğu anda loglarda:

upstream timed out

benzeri kayıtlar görülebilir.

Bu durumda Nginx'in hangi upstream'i beklediğini belirlemek önemlidir.

Backend uygulaması çalışıyor mu?

Node.js uygulamanız PM2 ile çalışıyorsa:

pm2 status

kullanın.

Ardından:

pm2 logs uygulama-adi

ile logları inceleyin.

Uygulama online görünse bile düzgün ve hızlı cevap verdiği anlamına gelmez.

Process çalışıyor ancak bir sorgu veya işlem nedeniyle uzun süre cevap veremiyor olabilir.

Backend'i doğrudan test edin

Örneğin uygulamanız:

127.0.0.1:3000

üzerinde çalışıyorsa:

curl -i http://127.0.0.1:3000/

ile doğrudan test edebilirsiniz.

Sorun belirli bir endpoint'te oluşuyorsa:

curl -i http://127.0.0.1:3000/api/ornek

gibi ilgili yolu test edin.

Backend doğrudan çağrıldığında da çok geç cevap veriyorsa sorun büyük ihtimalle Nginx'ten önce uygulama veya onun bağımlılıklarında aranmalıdır.

Yanıt süresini ölçün

Daha ayrıntılı test için:

curl -o /dev/null -s -w 'Toplam: %{time_total}s\n' http://127.0.0.1:3000/

kullanabilirsiniz.

Bu şekilde backend'in isteği yaklaşık ne kadar sürede tamamladığını görebilirsiniz.

Belirli bir route diğerlerinden çok daha yavaşsa problem o endpoint'in gerçekleştirdiği işlemlerde olabilir.

PostgreSQL sorguları 504 oluşturabilir

Backend bir HTTP isteğini işlerken PostgreSQL sorgusunun tamamlanmasını bekliyorsa yavaş sorgu bütün isteğin gecikmesine neden olabilir.

Olası nedenler:

- Eksik indeks

- Çok büyük tablo taraması

- Ağır JOIN işlemleri

- Çok fazla sorgu

- Kilit bekleyen transaction

- Yoğun veritabanı yükü

- Verimsiz sorgu yapısı

olabilir.

Bu durumda Nginx timeout değerini artırmak sorguyu hızlandırmaz.

Asıl çözüm veritabanındaki yavaşlığın nedenini bulmaktır.

Veritabanı kilitleri önemli olabilir

Bir transaction başka bir işlemin tuttuğu kilidi bekliyorsa sorgu uzun süre tamamlanmayabilir.

Kullanıcı tarafında bu durum sayfanın uzun süre yüklenmesi ve sonunda 504 vermesi şeklinde görülebilir.

Özellikle yalnızca belirli işlemlerde 504 oluşuyorsa ilgili veritabanı sorguları ve transaction davranışı araştırılmalıdır.

Harici API yavaşsa 504 oluşabilir

Backend uygulamanız bir isteği işlerken:

- Ödeme servisi

- E-posta servisi

- Başka bir web API

- Dosya depolama servisi

- Harici veri kaynağı

ile iletişim kuruyor olabilir.

Harici servis yanıt vermediğinde Node.js uygulaması onu uzun süre bekliyorsa Nginx'in timeout süresi dolabilir.

Bu nedenle uygulama tarafında harici isteklere de uygun timeout ve hata yönetimi uygulanmalıdır.

CPU kullanımını kontrol edin

Sunucu işlemcisi aşırı yük altındaysa backend istekleri zamanında işleyemeyebilir.

Kontrol:

top

veya:

htop

En fazla CPU kullanan process'leri görmek için:

ps aux --sort=-%cpu | head

kullanabilirsiniz.

CPU sürekli yüksekse hangi process'in kaynak tükettiğini belirleyin.

RAM kullanımını kontrol edin

Bellek baskısı ve yoğun swap kullanımı da uygulama performansını ciddi şekilde düşürebilir.

Kontrol:

free -h

Özellikle:

- available RAM

- Swap kullanımı

değerlerine dikkat edin.

PM2 uygulamasının RAM kullanımı:

pm2 status

ile de izlenebilir.

Disk problemi 504'e neden olabilir mi?

Doğrudan her 504 hatasının nedeni disk değildir ancak yoğun disk I/O veya tamamen dolmuş disk backend performansını etkileyebilir.

Kontrol:

df -h

Inode:

df -i

CPU düşük olduğu halde uygulama çok yavaşsa disk ve I/O tarafı da araştırılmalıdır.

PM2 uygulaması restart oluyor mu?

Kontrol:

pm2 status

Restart sayısı sürekli artıyorsa:

pm2 logs uygulama-adi

ile nedeni bulunmalıdır.

Uygulama istek sırasında çöküyor veya yeniden başlıyorsa kullanıcı farklı gateway hatalarıyla karşılaşabilir.

Nginx timeout ayarları nelerdir?

Reverse proxy yapılandırmalarında kullanılabilen ayarlardan bazıları:

proxy_connect_timeout

proxy_send_timeout

proxy_read_timeout

şeklindedir.

Örneğin belirli bir uygulamanın gerçekten uzun süren ve geçerli bir işlemi varsa proxy_read_timeout ihtiyaca göre düzenlenebilir.

Ancak değerleri rastgele çok yüksek seviyelere çıkarmak doğru değildir.

proxy_read_timeout ne işe yarar?

proxy_read_timeout, Nginx'in upstream'den veri okurken iki okuma işlemi arasındaki bekleme davranışıyla ilgilidir.

Bu ayarı yalnızca:

“504 geliyor, o halde süreyi artırayım.”

mantığıyla değiştirmek gerçek performans problemini gizleyebilir.

Örneğin normalde 500 ms sürmesi gereken bir API isteği 70 saniye sürüyorsa önce API'nin neden bu kadar yavaş olduğu araştırılmalıdır.

Timeout artırmak ne zaman mantıklı olabilir?

Bazı işlemler doğası gereği uzun sürebilir.

Örneğin:

- Büyük rapor oluşturma

- Uzun veri işleme

- Büyük dosya operasyonu

- Kontrollü import veya export işlemleri

normal web isteklerinden daha uzun sürebilir.

Bu tür işlemlerde uygun timeout ayarı gerekebilir.

Ancak çok uzun süren görevleri HTTP isteği açık tutarak gerçekleştirmek yerine bazı mimarilerde background job sistemi kullanmak daha doğru olabilir.

Timeout değerini değiştirdikten sonra ne yapılmalı?

Öncelikle yapılandırmayı test edin:

sudo nginx -t

Test başarılıysa:

sudo systemctl reload nginx

kullanılabilir.

nginx -t başarısızsa mevcut çalışan Nginx yapılandırmasını bozacak şekilde reload veya restart yapılmamalıdır.

Nginx'i restart etmek 504 sorununu çözer mi?

Bazen geçici bir durum düzelebilir ancak kalıcı çözüm değildir.

Sorun:

- Yavaş Node.js kodu

- Ağır PostgreSQL sorgusu

- Harici API

- Yüksek CPU

- Bellek baskısı

- Ağ problemi

ise Nginx'i yeniden başlatmak gerçek nedeni ortadan kaldırmaz.

504 yalnızca belirli sayfalarda oluşuyorsa

Bu önemli bir ipucudur.

Örneğin:

- Ana sayfa hızlı

- Profil hızlı

- Arama hızlı

- Rapor sayfası 504

ise genel Nginx probleminden ziyade rapor sayfasının gerçekleştirdiği işlem araştırılmalıdır.

İlgili route'un:

- Veritabanı sorguları

- Harici istekleri

- Dosya işlemleri

- CPU yoğun işlemleri

kontrol edilmelidir.

504 bütün sitede oluşuyorsa

Bütün backend istekleri zaman aşımına uğruyorsa:

- Backend'in genel durumu

- PM2

- CPU

- RAM

- Veritabanı

- Ağ

- Upstream yapılandırması

kontrol edilmelidir.

Statik CSS ve görseller açılırken dinamik sayfalar 504 veriyorsa sorun backend tarafına işaret edebilir.

Nginx upstream adresini kontrol edin

Örneğin:

proxy_pass http://127.0.0.1:3000;

kullanılıyorsa backend'in gerçekten bu adreste dinlediğini kontrol edin:

ss -lntp | grep ':3000'

Yanlış upstream adresi veya portu genellikle başka gateway problemleri oluşturabilir; yine de reverse proxy teşhisinde upstream yapılandırması mutlaka doğrulanmalıdır.

Docker kullanılıyorsa

Backend Docker container içerisinde çalışıyorsa:

- Container durumu

- Container kaynak limitleri

- Container logları

- Docker network

- Port mapping

kontrol edilmelidir.

Container'ın RAM veya CPU limiti host sunucudan daha düşük olabilir.

Host üzerinde yeterli kaynak bulunması container'ın da aynı kaynağa sahip olduğu anlamına gelmez.

Proxy zinciri varsa sorun başka katmanda olabilir

Bazı sistemlerde istek:

Kullanıcı → CDN → Nginx → Backend → Veritabanı

gibi birden fazla katmandan geçebilir.

Bu durumda görülen timeout cevabının hangi katmanda üretildiğini belirlemek önemlidir.

Her 504 cevabının doğrudan sizin Nginx sunucunuz tarafından oluşturulduğunu varsaymayın.

504 hatası için hızlı kontrol sırası

Şu sırayla ilerleyebilirsiniz:

1. 504 veren URL'yi belirleyin.

2. Nginx error logunu kontrol edin.

3. pm2 status ile backend durumuna bakın.

4. pm2 logs uygulama-adi ile hataları inceleyin.

5. Backend'i curl ile doğrudan test edin.

6. Yanıt süresini ölçün.

7. PostgreSQL sorgularını ve olası kilitleri kontrol edin.

8. Harici API bağımlılıklarını araştırın.

9. top ile CPU kullanımına bakın.

10. free -h ile RAM ve swap durumunu kontrol edin.

11. df -h ile disk durumuna bakın.

12. Nginx timeout yapılandırmasını inceleyin.

13. Değişiklik gerekiyorsa önce nginx -t, ardından reload yapın.

Sık yapılan hatalar

504 problemi çözülürken şu hatalardan kaçının:

- Timeout değerini doğrudan çok yükseltmek

- Nginx'i sürekli restart etmek

- Backend'i doğrudan test etmemek

- Yavaş veritabanı sorgularını araştırmamak

- Harici API beklemelerini unutmak

- CPU ve RAM kullanımını kontrol etmemek

- PM2 restart döngüsünü gözden kaçırmak

- Bütün 504 hatalarını Nginx kaynaklı sanmak

- nginx -t çalıştırmadan yapılandırmayı reload etmek

Özetle, Nginx 504 Gateway Timeout hatası çoğu zaman Nginx'in kendisinden ziyade zamanında cevap veremeyen backend veya onun bağımlılıklarıyla ilişkilidir.

Sorunu kalıcı olarak çözmek için Nginx logu → backend → veritabanı → harici servisler → CPU ve RAM → timeout yapılandırması sırasıyla ilerlemek en sağlıklı yaklaşımdır. Timeout süresini artırmak ise ancak işlemin gerçekten uzun sürmesi bekleniyorsa ve bunun nedeni biliniyorsa değerlendirilmelidir.