Nginx Reverse Proxy Yapılandırması Nasıl Yapılır?
Nginx reverse proxy kurulumunda proxy_pass, websocket desteği ve gerekli header ayarlarını adım adım yapılandırın. Ubuntu 24.04 üzerinde hatasız bir kurulum için rehber.
Nginx reverse proxy yapılandırması ne işe yarar
Bir Nginx reverse proxy, 80 ve 443 numaralı portlara gelen istekleri karşılar, bunları yerel bir portta dinleme yapan ilgili uygulamaya iletir ve uygulamanın yanıtını tarayıcıya geri döndürür. Yapılandırma tek bir server bloğundan oluşur ve bu blok oldukça kısadır. Zorlukların neredeyse tamamı, uygulamaya gerçek istemcinin kim olduğunu ve hangi protokolü kullandığını bildiren beş veya altı satırda toplanır.
Aşağıdaki tüm işlemler, Ubuntu 24.04 üzerinde, dağıtımın kendi Nginx paketi kullanılarak sıfırdan oluşturulmuştur. Başlangıç noktası, halihazırda 127.0.0.1:3000 üzerinde yanıt veren bir uygulamadır. Henüz bir proxy seçimi yapmadıysanız, öncelikle Nginx'in Caddy ve Traefik ile karşılaştırması başlıklı yazıyı okumalısınız. Aşağıda, Nginx yanıtının satır satır nasıl göründüğü açıklanmıştır.
Bu yapılandırmaları kendi sunucunuzda çalıştırın. Her değişiklikten sonra yeniden yükleme yapmadan önce sudo nginx -t ile test edin ve çıktısını inceleyin.
Ubuntu üzerinde Nginx yapılandırma dosyalarının konumu
sudo apt update
sudo apt install -y nginx
ls -l /etc/nginx/sites-enabled/Ana yapılandırma dosyası /etc/nginx/nginx.conf konumundadır. Bu dosya, genel ayarları bir http { } bloğu içerisinde tanımlar ve ardından /etc/nginx/conf.d/*.conf ile /etc/nginx/sites-enabled/* dizinlerini içeri aktarır. Ubuntu ve Debian sistemlerinde her site için /etc/nginx/sites-available/ dizininde ayrı bir dosya oluşturulur ve /etc/nginx/sites-enabled/ dizinine sembolik bir bağ (symlink) eklenerek site aktif hale getirilir. Sembolik bağın silinmesi siteyi devre dışı bırakır ancak yapılandırma dosyasını korur.
Daha sonra kullanılacak iki direktif yalnızca http bağlamında çalışır, server bloğu içerisinde kullanılamazlar: map ve upstream. Bu direktifleri /etc/nginx/conf.d/ altında kendi dosyalarına yerleştirin; çünkü bu dizin http seviyesinde içeri aktarılmaktadır.
Paket, default adında varsayılan olarak etkin bir site ile gelir. Bu site default_server olarak işaretlenmiştir; bu, Host başlığı yapılandırmanızdaki hiçbir server_name ile eşleşmeyen tüm isteklere bu sitenin yanıt vereceği anlamına gelir. Bu site etkin kaldığı sürece, tanımladığınız alan adlarıyla eşleşmeyen istekler uygulamanız yerine bu siteye yönlendirilir. Kendi siteniz çalışır duruma geldiğinde bu sembolik bağı kaldırın.
sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginxTek bir uygulamayı proxy eden en küçük sunucu bloğu
server {
listen 80;
listen [::]:80;
server_name app.example.com;
location / {
proxy_pass http://127.0.0.1:3000;
}
}Bunu /etc/nginx/sites-available/app.example.com olarak kaydedin, ardından etkinleştirin ve yükleyin.
sudo ln -s /etc/nginx/sites-available/app.example.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
curl -sI -H 'Host: app.example.com' http://127.0.0.1/listen 80; IPv4 adresini, listen [::]:80; ise IPv6 adresini dinler. İkinci satırı çıkarırsanız sunucunuza gelen tüm IPv6 bağlantıları reddedilir. DNS (alan adı sistemi) sorgusu AAAA kaydı döndüren çift yığınlı (dual-stack) bir tarayıcı genellikle IPv4'e geri döner ve sorunu gizler; ancak yalnızca IPv6 kullanan bir ziyaretçi veya yalnızca aldığı ilk adresi deneyen bir istemci, bağlantının reddedildiğini görürken IPv4 üzerindeki herkes çalışan bir site görür. Aldığınız hata raporu "bende çalışıyor" şeklinde olacaktır.
server_name, tarayıcının gönderdiği Host başlığı ile eşleştirilir. Boşluklarla ayrılarak birden fazla isim listelenebilir. Hiçbir blok eşleşmezse, nginx default_server olan bloğu kullanır; paketlenmiş sitenin kaldırılmasının nedeni budur.
location /, istek yolu üzerinde bir önek eşleşmesidir ve / her yolu eşleştirir. proxy_pass, nginx'in bağlantı açtığı adrestir. Uygulamayı 127.0.0.1 adresine bağlı tutun, böylece içeriye giden tek yol nginx üzerinden olur. Uygulama bir container içinde çalışıyorsa, onu 3000:3000 olarak değil 127.0.0.1:3000:3000 olarak yayınlayın; çünkü Docker kendi kurallarını yazar ve portları ufw'yi atlayarak doğrudan yayınlar, bu nedenle çıplak bir yayın portu ufw ne derse desin internetten erişilebilir durumdadır. Docker, bu trafiği filtrelemek için DOCKER-USER zincirini dokümante eder ancak 127.0.0.1 adresine bağlamak daha basit bir çözümdür.
curl satırı, sunucunun kendisinden doğru Host başlığını gönderir, böylece DNS herhangi bir yeri işaret etmeden önce bloğu test edebilirsiniz.
Başka bir ayar yapılmadığında Nginx'in upstream'e gönderdikleri
proxy_pass tek başına kullanıldığında uygulamanızdan dört şeyi gizler.
Ubuntu 24.04 ile gelen nginx 1.24.0 paketi, varsayılan olarak arka uçla HTTP/1.0 üzerinden konuşur ve Connection: close gönderir; bu nedenle her istek yeni bir upstream bağlantısı açar ve protokol yükseltmesi mümkün olmaz. Mart 2026'da yayınlanan nginx 1.29.7, bu varsayılanları değiştirdi: bu sürümden itibaren nginx, upstream ile HTTP/1.1 üzerinden konuşur, Connection başlığı göndermez ve her istek için yeni bir bağlantı açmak yerine havuzdaki bağlantıları yeniden kullanır. Bu sürümde dahi, bir WebSocket yükseltmesi aşağıda gösterilen başlıkları gerektirir.
Host başlığı, 127.0.0.1:3000 olan proxy_pass değerine yeniden yazılır. Host üzerinden mutlak bağlantılar oluşturan bir uygulama, artık sunucu dışındaki hiç kimsenin açamayacağı bağlantılar üretir.
Uygulamaya ulaşan bağlantı nginx üzerinden geldiği için uygulama, istemci adresini 127.0.0.1 olarak görür. Bu durumda uygulamadaki her günlük satırı ve her hız sınırlaması, ziyaretçi yerine proxy'yi kaydeder.
Uygulama, tarayıcının HTTPS kullanıp kullanmadığını anlayamaz; çünkü aldığı bağlantı, loopback adresi üzerinde düz bir HTTP bağlantısıdır.
Dört satır tüm bu sorunları çözer.
FAQ
Ayarlanması gereken dört başlık ve her birinin arka uçta sağladığı görünürlük
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}Host, ziyaretçinin yazdığı alan adını taşır. $host, isteğin içindeki, port bilgisi çıkarılmış ve küçük harfe dönüştürülmüş isimdir. Bunu ayarladığınızda uygulamanız doğru mutlak URL'ler oluşturur: giriş sonrası yönlendirme veya şifre sıfırlama e-postasındaki bağlantı gibi. Bu başlığı atladığınızda uygulama, kendi ismi olarak 127.0.0.1:3000 değerini alır. nginx'in varsayılan proxy_redirect değeri, proxy_pass adresini işaret eden bir Location veya Refresh başlığını yeniden yazar; bu sayede giriş sonrası basit yönlendirmeler genellikle doğru yere ulaşır. Ancak uygulamanın sayfalarına ve e-postalarına yazdığı şifre sıfırlama bağlantısı gibi mutlak URL'ler, ziyaretçinin tarayıcısının açamayacağı 127.0.0.1:3000 adresini işaret eder. Eğer uygulamanız 8080 portunda çalıştığı için port bilgisine de ihtiyaç duyuyorsa, istemcinin gönderdiği başlığın aynısı olan $http_host değerini kullanın.
X-Real-IP tek bir değer taşır: nginx'in bağlantıyı kabul ettiği adres olan $remote_addr. Uygulamalar bunu kendi erişim günlükleri ve hız sınırlama işlemleri için okur.
X-Forwarded-For bir liste taşır. $proxy_add_x_forwarded_for, istemcinin halihazırda başlığa eklediği değerlerin sonuna $remote_addr değerini ekler; böylece değer virgülle ayrılmış bir liste haline gelir ve nginx'in eklediği girdi en sonda yer alır. Bu detay, başlığın güvenilir olup olmadığını belirler: bir istemci istediği herhangi bir X-Forwarded-For değerini gönderebilir, bu yüzden ilk girdiyi okuyan bir uygulama herhangi bir adrese yönlendirilebilir. nginx uç sunucu (edge server) konumundaysa, istemcinin sürümünü göz ardı edip $remote_addr yazın. Ön tarafta bir CDN veya başka bir proxy varsa, realip modülünden set_real_ip_from ve real_ip_header kullanın; böylece $remote_addr değerinin kendisi gerçek istemci adresi olur.
X-Forwarded-Proto, http veya https değerini taşır. Çerçeveler (frameworks), çerezleri Secure olarak işaretleyip işaretlemeyeceğine ve HTTPS'e zorunlu yönlendirme yapıp yapmayacağına karar vermek için bunu okur. TLS destekli bir sitede bu başlığı atlarsanız, HTTPS'e zorlamak üzere yapılandırılmış bir uygulama http değerini görür, HTTPS adresine yönlendirme ile yanıt verir, bir sonraki isteği nginx üzerinden alır, yine http değerini görür ve tekrar yönlendirir. Tarayıcı bu döngüde pes eder ve ERR_TOO_MANY_REDIRECTS hatasını gösterir.
Bu dört satırı her location bloğunda tekrarlamak, zamanla farklılaşmalarına neden olur. Bunları tek bir dosyaya koyun ve include komutuyla dahil edin.
# /etc/nginx/snippets/proxy-headers.conf
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;location / {
include snippets/proxy-headers.conf;
proxy_pass http://127.0.0.1:3000;
}Buradaki kalıtım bir tuzak içerir. Bir location bloğu, kendi içinde hiçbir proxy_set_header yönergesi tanımlamadığı sürece, server bloğundaki yönergeleri devralır. Location içine tek bir proxy_set_header eklerseniz, server seviyesinde tanımlanan tüm başlıklar o location için devre dışı kalır. Bu nedenle hepsini tek bir seviyede tutun veya proxy işlemi yapan her location bloğunda ilgili kod parçacığını include ile dahil edin.
WebSocket uygulamam neden bağlanıyor ve ardından bağlantıyı kesiyor?
Varsayılan ayarlar yükseltme (upgrade) işlemine izin vermediği ve varsayılan okuma zaman aşımı boşta kalan bir tüneli 60 saniye sonra kapattığı için bu durum yaşanır. Bir WebSocket, Upgrade: websocket ve Connection: Upgrade başlıklarını taşıyan bir HTTP isteği olarak başlar. Bunlar "hop-by-hop" başlıklardır; yani bir proxy'nin bunları iletmek yerine tüketmesi beklenir. Ubuntu 24.04 üzerindeki nginx 1.24.0 sürümünde yukarı akış (upstream) protokolü varsayılan olarak HTTP/1.0'dır ve bu protokol herhangi bir yükseltme mekanizmasına sahip değildir. Her ikisinin de manuel olarak geri eklenmesi gerekir.
Map bloğu, kendi dosyası içinde http bağlamına yerleştirilmelidir.
# /etc/nginx/conf.d/websocket.conf
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}Ardından location bloğu gelir.
location / {
include snippets/proxy-headers.conf;
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
}Map bloğu, tek bir location bloğunun her iki trafik türüne de hizmet verebilmesi için kullanılır. Normal bir istekte $http_upgrade boştur, bu nedenle $connection_upgrade değeri close olur. Bir yükseltme isteğinde ise websocket değerini tutar, dolayısıyla yukarı akışa gönderilen başlık Connection: upgrade olur. proxy_set_header Connection "upgrade"; değerini doğrudan kodlamak, bu başlığı her düz sayfa isteğinde de gönderir ve bazı arka uçlar (backend) böyle bir isteğe 400 hatası ile yanıt verir.
proxy_http_version 1.1;, nginx 1.29.7 ve sonraki sürümlerde varsayılan değerdir; bu nedenle ilgili sürümlerde bu satır hiçbir şeyi değiştirmez ve bir zararı olmaz. 1.24.0 paketinde ise bu satır gereklidir. Upgrade ve Connection satırları her sürümde gereklidir, çünkü nginx bu iki başlığı kendiliğinden iletmez.
proxy_read_timeout, "yükleniyor ancak güncellemeyi durduruyor" şeklindeki raporlara neden olan ayardır. Varsayılan değeri 60 saniyedir ve bağlantının toplam ömrünü değil, arka uçtan gelen iki okuma arasındaki süreyi ölçer. 60 saniye boyunca sessiz kalan bir WebSocket, nginx tarafından kapatılır ve tarayıcı konsolu soketin 1006 koduyla kapandığını gösterir. Dakikada bir kereden daha sık kendi "heartbeat" sinyalini gönderen uygulamalar bu durumu fark etmez. Göndermeyen uygulamalar ise dakika dolduğunda bağlantıyı kaybeder. Canlı editörler ve paneller bu durumun ilk görüldüğü yerlerdir; HTTPS arkasındaki self-hosted bir n8n örneği bunun yaygın bir örneğidir.
proxy_pass içindeki bir eğik çizgi (trailing slash) URL'lerimi neden değiştiriyor?
Kural tek bir cümleden ibarettir. Eğer proxy_pass bir URI (uniform resource identifier) ile bitiyorsa, basit bir / olsa dahi, nginx istek yolunun location önekiyle eşleşen kısmını kaldırır ve yerine bu URI'yi yerleştirir. Eğer proxy_pass ana makine (host) ve port kısmında bitiyorsa, istek yolu hiçbir değişikliğe uğramadan iletilir.
location /app/ {
proxy_pass http://127.0.0.1:3000/;
}/app/status için yapılan bir istek, arka uç (backend) sistemine /status olarak ulaşır.
location /app/ {
proxy_pass http://127.0.0.1:3000;
}/app/status için yapılan bir istek, arka uç (backend) sistemine /app/status olarak ulaşır.
Hangi biçimi kullanacağınız uygulamaya bağlıdır. Temel yol (base-path) veya alt klasör ayarı olan bir uygulama, /app hakkında bilgilendirilmiş şekilde ikinci biçimi ister. Önekler hakkında hiçbir bilgisi olmayan bir uygulama ise ilk biçime ihtiyaç duyar. İlk biçimin hemen fark edilen bir maliyeti vardır: uygulamanın döndürdüğü HTML içeriği hala /static/main.css gibi mutlak yollar içerir; tarayıcı bunları site kök dizininden ister, hiçbir location eşleşmez ve sayfa stiller yüklenmeden görüntülenir. Tarayıcının ağ (network) sekmesi, bu varlık (asset) isteklerinin 404 hatasıyla döndüğünü gösterir. Çözüm, uygulamanın kendi temel yol ayarı veya aynı arka ucu işaret eden ikinci bir location /static/ bloğudur.
Regex tabanlı bir location, proxy_pass içinde bir URI taşıyamaz. sudo nginx -t yapılandırmayı reddeder ve nedenini şu şekilde belirtir: "proxy_pass" cannot have URI part in location given by regular expression, or inside named location, or inside "if" statement, or inside "limit_except" block.
Bu tür sorunların tamamı, her uygulama kendi app.example.com adına sahip olduğunda ve location / üzerinden proxy edildiğinde ortadan kalkar. Alt yollar (sub-paths), yalnızca DNS kayıtları ekleyemediğiniz durumlarda uğraşmaya değerdir.
Birden fazla backend servisini tek bir isim altında nasıl toplarım?
Bunu bir upstream bloğu ile yapabilirsiniz. Bu blok http bağlamına ait olduğundan, aynı dosya içerisinde server bloğunun üzerine veya /etc/nginx/conf.d/ içerisine yazılmalıdır.
upstream app_backend {
least_conn;
server 127.0.0.1:3000 max_fails=3 fail_timeout=30s;
server 127.0.0.1:3001 max_fails=3 fail_timeout=30s;
keepalive 32;
}Ardından location bloğu içerisinde bu ismi belirtin: proxy_pass http://app_backend;.
Varsayılan yöntem round robin'dir. least_conn, her isteği en az aktif bağlantıya sahip olan backend sunucusuna gönderir; bu yöntem, süresi değişken olan istekler için uygundur. ip_hash ise bir istemci adresini tek bir backend sunucusuna sabitler. Uygulamanız oturum bilgilerini kendi belleğinde tutuyorsa ip_hash kullanmanız gerekir; aksi takdirde round robin yöntemi, istekleri oturum bilgisini içermeyen bir örneğe yönlendirebileceği için kullanıcıların rastgele oturumlarının kapanmasına neden olur. Oturumları paylaşımlı bir depolama alanına taşımak daha doğru bir çözümdür.
max_fails=3 fail_timeout=30s, 30 saniye içinde 3 başarısız deneme gerçekleştiğinde ilgili sunucunun 30 saniye boyunca devre dışı bırakılacağı anlamına gelir. Bloktaki tüm sunucular bu duruma düştüğünde, istemciler 502 hatası alır ve hata günlüğünde no live upstreams while connecting to upstream ifadesi yer alır.
keepalive 32, worker süreci başına backend sunucularına giden 32 adede kadar boşta bağlantıyı açık tutar; bu da çoğu istekte TCP el sıkışma sürecini ortadan kaldırır. Ubuntu 24.04 üzerindeki 1.24.0 sürümünde önbelleği etkinleştiren satır budur. nginx 1.29.7 sürümünden itibaren önbellek varsayılan olarak açıktır ancak belgelenen varsayılan değer keepalive 32 local; şeklindedir ve local parametresi, önbelleğe alınmış bağlantıların farklı location blokları arasında paylaşılmasını engeller. Dolayısıyla 1.29.7 ve sonraki sürümlerde, yalın bir keepalive 32; kullanımı sadece varsayılanı belirtmekle kalmaz; local ifadesini dışarıda bırakarak, aynı upstream sunucusuna proxy yapan herhangi bir location bloğunun havuzdaki bir bağlantıyı yeniden kullanmasına izin verir ki bu, varsayılan davranıştan bir sapmadır. Bu sürümlerde ilgili satırı tamamen kaldırın veya varsayılanı korumak için keepalive 32 local; yazın; sadece paylaşımı etkinleştirmek istiyorsanız yalın halini kullanın. local parametresi 1.29.7 ile gelmiştir, bu nedenle 1.24.0 paketi bunu desteklemez. HTTP backend sunucuları için nginx'in havuz yapılandırması olarak önerdiği yöntem, proxy_http_version değerini 1.1 (veya nginx 1.29.4 ve sonrası için 2) olarak ayarlamak ve Connection başlığını upstream tarafına temizlenmiş şekilde göndermektir. nginx ayrıca, destekleyen bir backend sunucusuna Connection: Keep-Alive gönderilerek sağlanan HTTP/1.0 kalıcı bağlantılarını da belgeler ancak bu yöntemin önerilmediğini belirtir. 1.29.7 sürümünden itibaren önerilen yapılandırmanın her iki parçası da varsayılan olarak gelir. 1.24.0 sürümünde, location bloğuna kendiniz proxy_http_version 1.1; ve proxy_set_header Connection ""; eklemelisiniz; aksi takdirde nginx Connection: close ile HTTP/1.0 göndermeye devam eder ve havuz asla yeniden kullanılmaz. Eğer aynı location bloğu WebSocket haritasını da kullanıyorsa, boş durumu close yerine boş bir dizge olarak değiştirin; böylece normal istekler Connection başlığını taşımaz ve havuzdaki bağlantı yeniden kullanılabilir.
map $http_upgrade $connection_upgrade {
default upgrade;
'' '';
}upstream bloğu içindeki isimler, nginx başlatıldığında çözümlenir. Eğer backend sunucunuz yeniden başlatıldığında yeni bir adres alan bir container ise, nginx siz yeniden yükleme yapana kadar eski adresi kullanmaya devam eder. nginx 1.27.3 ve sonraki sürümler, bir resolver, upstream bloğu içindeki bir zone ve her server satırındaki resolve parametresi sayesinde bu değişiklikleri yeniden yükleme yapmadan takip edebilir; ancak 1.24.0 paketi bu özellikten daha eskidir. Bir Docker ağı içerisinde, gömülü çözümleyici (resolver) ile sorguyu istek zamanına taşıyabilirsiniz.
resolver 127.0.0.11 valid=10s;
set $backend http://app:3000;
proxy_pass $backend;Container'lar, nginx yapılandırmasını sürekli düzenlemenizi gerektirecek kadar sık görünüp kaybolmaya başladığında, container etiketlerini okuyabilen bir proxy daha iyi bir araçtır. Birden fazla Docker Compose uygulaması önünde Traefik kullanımı, rotalarını doğrudan container'ların kendisinden oluşturur.
Yüklemeler neden 413 Request Entity Too Large hatası veriyor?
client_max_body_size varsayılan olarak 1 megabayt değerindedir. Bu değerden daha büyük bir istek gövdesi nginx tarafından 413 hatası ile reddedilir ve hata günlüğüne client intended to send too large body kaydedilir. Bu sınırı server bloğunda veya yüklemelerin gerçekleştiği location bloğunda yükseltin.
client_max_body_size 512m;0 değeri, kontrolü tamamen devre dışı bırakır. 512m kullanıldığında, nginx bu sınırın üzerindeki istek gövdelerini yine de reddeder; dolayısıyla bu değişiklikten sonra devam eden bir 413 hatası, kaynağın backend olduğunu göstermez. Uygulamanın kendi yükleme sınırını kontrol etmeden önce, yüklemeyi işleyen location bloğundaki geçerli client_max_body_size değerini ve nginx hata günlüğünü inceleyin.
Nginx, varsayılan olarak upstream bağlantısını açmadan önce tüm istek gövdesini okur ve büyük verileri önce diskteki geçici bir dosyaya yazar. Bu işlem, uygulamayı yavaş istemcilerden korur; çünkü backend, yüklemeyi tam yerel hızda alır. Çok büyük yüklemeler için bunun yerine akış (streaming) yöntemini kullanabilirsiniz.
proxy_request_buffering off;1.24.0 paketinde HTTP/1.1 parçalı (chunked) yüklemeler için ilgili location bloğunda proxy_http_version 1.1; ayarını da yapın; aksi takdirde nginx gövdeyi tamponlamaya (buffer) devam eder. Bu durumda backend, gövdeyi ulaştığı anda alır ve bunu işleyebilecek kapasitede olmalıdır. Nginx gövdeyi upstream'e göndermeye başladığında, isteği başka bir upstream üzerinde yeniden deneyemez.
Varsayılan olarak 60 saniye olan client_body_timeout, tüm yükleme süresine değil, gövdenin iki ardışık okuma işlemi arasındaki süreye uygulanır. Yavaş ancak istikrarlı bir yükleme bu sürede kesintiye uğramaz. Duraksayan bir yükleme ise sonlandırılır.
Yanıt tamponlama ve canlı çıktıyı bozan ayar
proxy_buffering varsayılan olarak etkindir ve genellikle istenen davranış budur. nginx, uygulamanızdan gelen yanıtı uygulamanın yazabildiği hızda okur, tutar ve yavaş bir istemciye o istemcinin kendi hızında sunar. Uygulama çalışanı (worker), yavaş bir indirme işleminin tamamını beklemek yerine erkenden serbest kalır.
Bu durum, akış (streaming) yanıtlarını bozar. Server-sent events ve canlı günlük çıktıları, bir tampon dolana kadar okuyucuya hiçbir şey göstermez. Tamponlamayı yalnızca ilgili konumda kapatın.
proxy_buffering off;Eğer uygulama üzerinde kontrolünüz varsa, daha iyi bir yöntem yalnızca akış yanıtlarında X-Accel-Buffering: no başlığını göndermektir. nginx bu başlığı yanıt bazında okur ve tamponlamayı yalnızca o yanıt için devre dışı bırakır; böylece normal sayfalar avantajını korumaya devam eder.
Hata günlüğünde upstream sent too big header while reading response header from upstream ifadesi yer aldığında, yanıt başlıkları tek bir tampona sığmamış demektir. proxy_buffer_size varsayılan olarak tek bir bellek sayfası boyutundadır (platforma bağlı olarak 4 veya 8 kilobayt); uzun çerezler veya büyük kimlik doğrulama başlıkları bu alanı aşar. Her iki değeri de artırın.
proxy_buffer_size 16k;
proxy_buffers 8 16k;TLS bu yapılandırmanın neresinde yer alır?
Nginx katmanında, yukarıdaki her şeyin önünde yer alır. TLS (transport layer security), proxy üzerinde sonlandırılır ve Nginx'ten uygulamaya giden bağlantı, ağdaki başka hiçbir cihazın okuyamayacağı loopback adresi üzerinden düz HTTP olarak devam eder. Uygulama, ziyaretçinin HTTPS kullandığını dört başlıktan dördüncüsü olan X-Forwarded-Proto üzerinden öğrenir.
Sertifika yollarını elle yazmayın. DNS kaydını sunucuya yönlendirin, güvenlik duvarını açın ve Certbot'un bu sunucu bloğunu düzenlemesine izin verin: Certbot, ssl_certificate yollarıyla birlikte listen 443 ssl satırını ve 80 numaralı porttan yönlendirmeyi otomatik ekler. Nginx için Certbot ile Let's Encrypt sertifikası oluşturma rehberi, sertifika oluşturma ve yenileme zamanlayıcısı konularını kapsamaktadır.
sudo ufw allow 'Nginx Full'
sudo ufw statusNginx Full, Nginx paketinin yüklediği bir uygulama profilidir ve 80 ile 443 numaralı portları birlikte açar. Tüm ziyaretçiler HTTPS'e yönlendirilmiş olsa dahi, HTTP-01 yenileme doğrulaması için 80 numaralı portun açık kalması zorunludur.
Yapılandırmayı test edin ve ardından yeniden yükleyin
sudo nginx -t
sudo systemctl reload nginxnginx -t, dahil edilen her dosyayı ayrıştırır ve testi başarılı olarak raporlar ya da işlemin durduğu dosya ve satır numarasını yazdırır. Yeniden yükleme yapmadan önce bu çıktıyı okuyun. Hatalı bir yapılandırma ile yapılan yeniden yükleme uygulanmaz: nginx önceki yapılandırmayı sunmaya devam eder, bu nedenle siz değişiklik yaparken site çalışır durumda kalır ancak değişiklikleriniz sessizce etkisiz kalır. systemctl restart farklı ve daha kötü bir şekilde davranır; çünkü yeniden başlatma işlemi önce çalışan sunucuyu durdurur, bu nedenle bir yapılandırma hatası nginx'in tamamen çalışmamasına neden olur. Varsayılan olarak yeniden yükleme yapın ve yeniden başlatma işlemini yalnızca gerektiren nadir değişiklikler için saklayın.
sudo tail -f /var/log/nginx/error.log
sudo ss -lntp | grep -E ':(80|443|3000)'ss satırı, her portu hangi sürecin tuttuğunu gösterir; böylece uygulamanın gerçekten proxy_pass tarafından işaret edilen yerde dinleme yaptığını doğrulayabilirsiniz.
Karşılaşacağınız gerçek hatalar
connect() failed (111: Connection refused) while connecting to upstream hatası içeren 502 Bad Gateway. proxy_pass adresinde dinleme yapan bir servis bulunmuyor. Uygulama durdurulmuş, başka bir porta bağlanmış veya ana makinenin erişemeyeceği bir container içi adrese bağlanmış olabilir.
no live upstreams while connecting to upstream hatası içeren 502. upstream bloğundaki tüm sunucular, max_fails tarafından şu anda başarısız olarak işaretlenmiş durumda. Backend servislerini onarın. fail_timeout süresi dolduğunda nginx tekrar deneme yapacaktır.
upstream timed out (110: Connection timed out) while reading response header from upstream hatası içeren 504 Gateway Time-out. Backend bağlantıyı kabul etti ancak proxy_read_timeout saniye boyunca hiçbir veri göndermedi. Zaman aşımı süresini artırmak, gerçekten yavaş çalışan bir rapor için doğru, ancak kilitlenmiş bir uygulama için yanlış bir yöntemdir.
Tüm yollar uygulamadan 404 dönüyor. Sondaki eğik çizgi (trailing slash) kuralı yolu yeniden yazmış olabilir. Uygulamanın günlük kayıtlarındaki yol ile talep ettiğiniz yolu karşılaştırın.
Farklı bir site yanıt veriyor. server_name, Host başlığı ile eşleşmiyor; bu nedenle istek default_server bloğuna düştü.
Sayfa yükleniyor ancak arayüz yaklaşık bir dakika sonra donuyor. Bu durum WebSocket ile ilgilidir: Upgrade yapılandırması eksik veya proxy_read_timeout değeri hala 60 saniye olarak ayarlanmış olabilir.
FAQ
Nginx, proxy_pass ekledikten sonra neden 502 Bad Gateway hatası veriyor?
Nginx, proxy_pass adresindeki bağlantıyı açamıyor. /var/log/nginx/error.log konumundaki hata günlüğü sorunun kaynağını belirtir: connect() failed (111: Connection refused) while connecting to upstream ifadesi ilgili adreste dinleme yapan bir servis olmadığını, no live upstreams ise bir upstream bloğundaki tüm sunucuların başarısız olarak işaretlendiğini gösterir. Hangi sürecin portu kullandığını ve hangi adrese bağlı olduğunu görmek için sudo ss -lntp | grep 3000 komutunu çalıştırın. Konteyner içi bir adrese veya yazdığınızdan farklı bir porta bağlı olan uygulamalar her zaman bu hatayı verir.
Uygulamam Nginx arkasında neden yaklaşık bir dakika sonra bağlantıyı kesiyor?
Bağlantı bir WebSocket'tir ve proxy_read_timeout değeri, arka uçtan gelen iki okuma arasındaki süreyi ölçen varsayılan 60 saniye değerinde kalmıştır. Sessiz kalan bir soket Nginx tarafından kapatılır ve tarayıcı konsolu 1006 hata kodunu bildirir. proxy_http_version 1.1 değerini ayarlayın (Nginx 1.29.7 sürümünden beri varsayılan olsa da, Ubuntu 24.04 paketindeki 1.24.0 sürümünde bulunmaz), Upgrade ve Connection değerlerini $http_upgrade üzerinde bir map ile iletin ve proxy_read_timeout değerini 3600s gibi bir süreye yükseltin. Upgrade başlığı olmadan yükseltme (upgrade) işlemi gerçekleşmez, bu nedenle uygulama yoklama (polling) yöntemine geri döner veya canlı güncellemeleri göstermez.
proxy_pass içindeki sondaki eğik çizgi (trailing slash) önemli mi?
Evet, bu arka ucun aldığı yolu değiştirir. location /app/ ve proxy_pass http://127.0.0.1:3000/ yapılandırmasında, /app/status için gelen bir istek arka uca /status olarak ulaşır; çünkü ana bilgisayar ve porttan sonraki her URI, eşleşen konum önekini değiştirir. Sondaki eğik çizgiyi kaldırdığınızda aynı istek /app/status olarak ulaşır. Öneki kaldırmak genellikle uygulamanın kendi varlık (asset) bağlantılarını bozar; bu bağlantılar mutlak kaldığı için site kök dizininde 404 hatası verir. Bu nedenle, temel yol (base-path) ayarı olan bir uygulama, yolu olduğu gibi ileten biçimle daha iyi çalışır.
Uygulamam neden tüm ziyaretçilerin IP adresini 127.0.0.1 olarak kaydediyor?
Çünkü uygulamanın aldığı bağlantı gerçekten Nginx üzerinden, loopback adresi kullanılarak gelmektedir. Ziyaretçinin adresi uygulamaya yalnızca sizin ayarladığınız bir başlık ile ulaşır: tek bir değer için proxy_set_header X-Real-IP $remote_addr;, eklenen zincir için proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;. Uygulamanın bu başlıkları güvenilir kabul edecek şekilde yapılandırılması gerekir. Bir istemcinin kendi X-Forwarded-For başlığını gönderebileceğini unutmayın; bu nedenle Nginx uç sunucu (edge server) olarak kullanıldığında, bu başlığı eklemek yerine $remote_addr ile üzerine yazın.
Nginx ile uygulamam arasındaki bağlantıda TLS gerekli mi?
Uygulama aynı sunucuda çalışıyorsa ve 127.0.0.1 adresine bağlıysa gerekli değildir; çünkü bu trafik makine dışına çıkmaz. TLS sonlandırmasını Nginx üzerinde yapın, proxy_pass bağlantısını loopback üzerinden düz HTTP olarak tutun ve uygulamanın ziyaretçinin HTTPS kullandığını anlaması için X-Forwarded-Proto $scheme başlığını gönderin. Arka uç, kontrolünüz dışındaki bir ağda farklı bir sunucuda bulunuyorsa, bu bağlantının kendi korumasına ihtiyacı vardır; ya arka uca HTTPS kullanın ya da iki makine arasında özel bir tünel kurun.