Nginx ile Reverse Proxy Yapılandırma

Modern uygulamaların çoğu artık kendi HTTP sunucusuyla birlikte gelir. Bir Node.js API'si 3000 portunu dinler, bir Python/Flask servisi 5000'de çalışır, Docker'da ayağa kaldırdığınız bir konteyner 8080'e bağlanır. Ancak internetten gelen ziyaretçi ne 3000 portunu, ne de konteyner IP'sini bilmek zorunda kalmalıdır. Kullanıcı yalnızca https://uygulamam.com yazar ve arka planda hangi framework'ün, hangi portta çalıştığını hiç umursamaz. İşte bu boşluğu kapatan katmana reverse proxy denir ve bu işi en yaygın, en güvenilir şekilde yapan araç Nginx'tir.

Reverse proxy, dış dünyadan gelen istekleri 80 ve 443 portlarında karşılayıp arka plandaki gerçek uygulamaya yönlendiren bir ara katmandır. Uygulamanızı doğrudan internete açmak yerine önüne Nginx koyarsınız; Nginx TLS sonlandırmayı, alan adı yönlendirmesini, başlık düzenlemeyi, hız sınırlamayı ve statik dosya sunumunu üstlenir, uygulamanız ise yalnızca kendi işine odaklanır. Bu yazıda bir reverse proxy'nin nasıl çalıştığını, proxy_pass ve proxy_set_header direktiflerinin ne yaptığını, WebSocket bağlantılarının neden özel başlıklar gerektirdiğini ve gerçek bir Node/Docker uygulamasını alan adınıza nasıl bağlayacağınızı adım adım göreceğiz. Nginx'in kurulu olduğunu varsayıyoruz; henüz kurmadıysanız önce Ubuntu'da Nginx kurulumu rehberini takip edebilirsiniz.

Reverse Proxy Nedir ve Ne İşe Yarar#

Adındaki "reverse" (ters) kelimesi, klasik forward proxy ile arasındaki farkı anlatır. Normal bir proxy, istemci tarafında durur ve kullanıcının isteklerini dış dünyaya taşır; kullanıcı kimliğini gizler. Reverse proxy ise sunucu tarafında durur ve arka plandaki uygulamaları dış dünyadan gizler. Ziyaretçi tek bir kapıyla (Nginx) konuşur; o kapının arkasında kaç uygulama, kaç konteyner, hangi portta çalışıyor hiç bilmez.

Bir reverse proxy kullanmanın somut faydaları şunlardır:

• Tek giriş noktası: Tüm alan adlarınızı ve alt alan adlarınızı 443 üzerinden karşılarsınız; her uygulama için ayrı port açmazsınız.
• TLS sonlandırma: SSL sertifikası yalnızca Nginx'te durur. Arka plandaki uygulamalar düz HTTP konuşur, sertifika yönetimiyle uğraşmaz.
• Güvenlik katmanı: Uygulama sunucusu doğrudan internete açık değildir. Saldırı yüzeyi Nginx'e iner; hız sınırlama, IP engelleme ve istek filtreleme burada yapılır.
• Yük dağıtımı: Aynı uygulamanın birden çok kopyasını upstream bloğuyla yük dengeleyebilirsiniz.
• Statik dosya hızı: Görseller, CSS ve JS dosyalarını doğrudan Nginx sunar; uygulama sunucusunu yormaz.

Bu mimari, özellikle uygulama önüne bir WAF veya DDoS koruması yerleştirdiğinizde daha da anlamlı hale gelir, çünkü zararlı trafik uygulamaya ulaşmadan önce ilk hattı Nginx'te durdurulur.

Temel Server Bloğu ve proxy_pass#

Reverse proxy'nin kalbi proxy_pass direktifidir. Bu tek satır, "gelen isteği şu adrese ilet" demektir. En sade örnekle başlayalım: 3000 portunda çalışan bir Node uygulamasını uygulamam.com alan adına bağlayalım.

Yapılandırma dosyasını genellikle /etc/nginx/sites-available/ altında oluşturursunuz:

sudo nano /etc/nginx/sites-available/uygulamam.com

İçeriği şöyle olabilir:

server {
    listen 80;
    listen [::]:80;
    server_name uygulamam.com www.uygulamam.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
    }
}

Burada dikkat edilecek noktalar var. proxy_pass hedefi olarak localhost yerine 127.0.0.1 yazmayı tercih edin; bu, IPv6 çözümleme gecikmelerini önler. proxy_http_version 1.1; satırı ise varsayılan HTTP/1.0 yerine kalıcı bağlantı (keep-alive) ve WebSocket desteği için gereklidir; ilerideki bölümlerde önemi netleşecek.

Bu dosyayı etkinleştirmek için sembolik bağ oluşturup Nginx'i test edip yeniden yükleyin:

sudo ln -s /etc/nginx/sites-available/uygulamam.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

nginx -t komutunu her değişiklikten sonra çalıştırmayı alışkanlık haline getirin; sözdizimi hatası varsa reload yerine bu adımda yakalarsınız ve canlı servisi kesintiye uğratmazsınız.

proxy_pass sonundaki eğik çizginin (/) davranışı değiştirdiğini bilin. Aşağıdaki tablo iki durumu karşılaştırır:

Yani proxy_pass adresinin sonuna / koyarsanız Nginx, location ile eşleşen ön eki keser. Alt yol taşıma yaparken bu ayrım hataların en sık kaynağıdır.

Doğru Başlıkları İletmek (proxy_set_header)#

Nginx varsayılan olarak isteği ilettiğinde, arka plandaki uygulama isteğin gerçek kaynağı hakkında çok az şey bilir. Uygulama, bağlantının Nginx'ten geldiğini görür; gerçek ziyaretçinin IP'sini, kullandığı alan adını ve HTTP/HTTPS bilgisini kaybeder. Bu bilgileri geri kazandırmak için proxy_set_header ile başlık eklersiniz.

Pratikte her reverse proxy yapılandırmasında bulunması gereken standart başlık seti şudur:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;

    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;
    proxy_set_header X-Forwarded-Host  $host;
    proxy_set_header X-Forwarded-Port  $server_port;
}

Bu başlıkların her biri farklı bir bilgiyi taşır:

• Host: Ziyaretçinin adres çubuğuna yazdığı alan adı. Uygulamanız çoklu alan adı (multi-tenant) mantığıyla çalışıyorsa veya doğru yönlendirme URL'leri üretiyorsa bu şarttır.
• X-Real-IP: Ziyaretçinin gerçek IP adresi. Loglama ve coğrafi kısıtlama için gerekir.
• X-Forwarded-For: Zincirdeki tüm proxy IP'lerini virgülle biriktirir. $proxy_add_x_forwarded_for değişkeni, varsa mevcut değere ekleme yapar; bu yüzden onu manuel yazmak yerine bu değişkeni kullanın.
• X-Forwarded-Proto: İsteğin http mi https mi olduğunu söyler. TLS sonlandırmayı Nginx yaptığından, arka plan uygulaması bağlantının aslında HTTPS olduğunu ancak bu başlıktan öğrenir. Bu başlık olmadan uygulamanız sonsuz HTTPS yönlendirme döngüsüne girebilir.

Bir uyarı: Uygulamanız X-Forwarded-For başlığına güvenip ziyaretçinin IP'sini oradan okuyacaksa, Nginx'i "güvenilir proxy" olarak tanımladığınızdan emin olun. Aksi halde ziyaretçinin gönderdiği sahte bir X-Forwarded-For başlığı uygulamayı yanıltabilir. Framework tarafında (Express'te app.set('trust proxy', 'loopback') gibi) bu ayarı yapmak önemlidir.

WebSocket Bağlantılarını Proxy'lemek#

WebSocket, gerçek zamanlı sohbet, canlı bildirim, işbirlikçi editör ve panolar gibi uygulamaların bel kemiğidir. Sorun şu ki WebSocket, sıradan bir HTTP isteği değildir; istemci önce bir HTTP isteği gönderir, ardından Upgrade: websocket başlığıyla bağlantının protokolünü yükseltmek ister. Nginx bu yükseltme başlıklarını varsayılan olarak arka plana iletmez; sonuç olarak WebSocket bağlantısı kurulamaz veya sürekli kopar.

Çözüm, Upgrade ve Connection başlıklarını elle taşımaktır. Önce http bloğu düzeyinde (/etc/nginx/nginx.conf içinde) bir map tanımlamak en temiz yöntemdir:

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

Bu map, Upgrade başlığı geldiğinde Connection: upgrade, gelmediğinde Connection: close üretir. Ardından location bloğunda şu iki satırı ekleyin:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;

    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;

    proxy_set_header Upgrade    $http_upgrade;
    proxy_set_header Connection $connection_upgrade;

    proxy_read_timeout 3600s;
}

proxy_http_version 1.1; burada mutlaka bulunmalı, çünkü WebSocket yükseltmesi HTTP/1.0'da mümkün değildir. proxy_read_timeout değerini yükselttiğimize dikkat edin; WebSocket bağlantıları uzun süre açık kalır ve varsayılan 60 saniyelik zaman aşımı, sessiz geçen dakikalarda bağlantıyı düşürerek "neden bağlantım kopuyor" şikayetlerine yol açar. Bir sonraki bölümde zaman aşımı ayarlarını daha ayrıntılı ele alacağız.

Zaman Aşımı ve Tampon Ayarları#

Varsayılan Nginx zaman aşımları çoğu web sitesi için yeterlidir ama arka planda ağır iş yapan API'ler, uzun süren rapor üretimi veya büyük dosya yüklemeleri söz konusuysa hızla "504 Gateway Timeout" hatalarıyla karşılaşırsınız. Bu hata, Nginx'in arka plandan yanıt beklerken sabrının tükendiğini gösterir; uygulamanın çökmesiyle karıştırmayın.

En sık ayarlanan zaman aşımı direktifleri şunlardır:

Uzun süren istekler ve dosya yükleyen uygulamalar için tipik bir yapılandırma:

server {
    listen 80;
    server_name uygulamam.com;

    client_max_body_size 50M;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;

        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;

        proxy_connect_timeout 30s;
        proxy_send_timeout    120s;
        proxy_read_timeout    120s;

        proxy_buffering on;
        proxy_buffers 16 16k;
        proxy_buffer_size 32k;
    }
}

client_max_body_size özellikle önemlidir; kullanıcılarınız dosya yüklüyor ve "413 Request Entity Too Large" hatası alıyorsa neredeyse her zaman sebep bu direktifin düşük kalmasıdır. Değeri uygulamanızın kabul ettiği en büyük dosyaya göre belirleyin.

proxy_buffering konusu ise uygulamaya göre değişir. Nginx varsayılan olarak arka plandan gelen yanıtı tamponlar; bu, yavaş istemcilerin arka plan iş parçacığını uzun süre meşgul etmesini önler. Ancak bir olay akışı (Server-Sent Events) veya canlı log yayını sunuyorsanız tamponlama, verinin istemciye anında ulaşmasını engeller. Bu tür location blokları için proxy_buffering off; yazmanız gerekir.

SSL Sonlandırma ve HTTPS#

Reverse proxy'nin en büyük pratik faydalarından biri, TLS sertifikasını tek bir yerde yönetmenizdir. Arka plandaki Node veya Docker uygulaması düz HTTP konuşurken, dış dünyaya karşı bağlantı HTTPS olur. Bu düzene "SSL sonlandırma" (SSL termination) denir: şifreli bağlantı Nginx'te sonlanır, oradan arka plana giden trafik yerel ve şifresizdir.

En pratik yol, Let's Encrypt ile ücretsiz ve otomatik yenilenen bir sertifika almaktır. Certbot bunu Nginx yapılandırmanıza kendisi ekleyebilir:

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d uygulamam.com -d www.uygulamam.com

Certbot başarıyla çalıştığında yapılandırmanız kabaca şu hale gelir; 80 portu HTTPS'e yönlendirir, asıl iş 443'te yapılır:

server {
    listen 80;
    server_name uygulamam.com www.uygulamam.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name uygulamam.com www.uygulamam.com;

    ssl_certificate     /etc/letsencrypt/live/uygulamam.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/uygulamam.com/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;

        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;
        proxy_set_header Upgrade           $http_upgrade;
        proxy_set_header Connection        $connection_upgrade;
    }
}

X-Forwarded-Proto $scheme başlığının burada kritik olduğunu tekrar vurgulayalım. Uygulamanız güvenli çerezleri (secure cookie) veya HTTPS zorlayan yönlendirmeleri bu başlığa göre yapar; başlık gelmezse tarayıcı ile uygulama arasında bitmeyen bir yönlendirme döngüsü oluşur. Ticari bir SSL sertifikası tercih ediyorsanız aynı ssl_certificate satırlarını kendi sertifika dosyalarınızla doldurmanız yeterlidir; mantık değişmez. Sertifikanın yenilenmesini otomatikleştirmeyi de unutmayın; Let's Encrypt sertifikaları 90 günde bir yenilenir ve Certbot bu işi bir sistem zamanlayıcısıyla kendisi yapar.

Node ve Docker Uygulamasını Domaine Bağlamak#

Şimdi tüm parçaları gerçek bir senaryoda birleştirelim. Diyelim ki bir Node.js uygulamanız var, süreç yöneticisi olarak PM2 kullanıyorsunuz ve uygulama 3000 portunu dinliyor. Amacınız api.uygulamam.com alan adını bu uygulamaya bağlamak.

Önce uygulamanın çalıştığını ve porta bağlandığını doğrulayın:

pm2 start server.js --name api
curl -I http://127.0.0.1:3000

curl bir HTTP yanıtı döndürüyorsa Nginx tarafına geçebilirsiniz. Yukarıdaki bölümlerde kurduğumuz şablonu api.uygulamam.com için uygulayıp certbot ile sertifikayı ekleyin. Bu kadar; alan adının DNS A kaydını sunucunuzun IP'sine yönlendirmeyi ihmal etmeyin, aksi halde Nginx isteği hiç almaz.

Docker senaryosu da benzerdir, tek fark portun konteynerden ana makineye nasıl yayınlandığıdır. Bir docker-compose.yml ile uygulamayı 8080 portuna bağlayalım:

services:
  web:
    image: benim-uygulamam:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      - NODE_ENV=production

ports satırında 127.0.0.1:8080:8080 yazdığımıza dikkat edin. Yalnızca 8080:8080 yazsaydınız, port tüm ağ arayüzlerine açılır ve konteyner doğrudan internetten erişilebilir hale gelirdi; bu, reverse proxy mimarisinin amacına aykırıdır. 127.0.0.1 ön ekiyle portu yalnızca yerel makineye açar, dış dünyaya kapıyı sadece Nginx'e bırakırsınız.

Ardından Nginx proxy_pass hedefini bu porta yönlendirirsiniz:

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;

    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;
}

Aynı sunucuda birden fazla konteyner çalıştırıyorsanız her birine farklı bir yerel port verir ve her alan adı için ayrı bir server bloğu tanımlarsınız. Bu yaklaşım, tek bir VDS sunucu üzerinde onlarca uygulamayı düzenli biçimde barındırmanın standart yöntemidir. Kendi kendine barındırdığınız hazır uygulamaları (n8n, Ghost, Nextcloud gibi) denemek istiyorsanız App Center katalogumuz bu servisleri tek tıkla kurmanızı sağlar; her birinin önüne yine aynı reverse proxy mantığı gelir.

Sık Karşılaşılan Hatalar ve Çözümleri#

Reverse proxy kurulumunda hatalar genellikle birkaç tipik başlık altında toplanır. Aşağıdaki tablo, karşılaşacağınız hataları ve gerçek nedenlerini özetler:

502 hatası en sık görülenidir ve neredeyse her zaman Nginx'in suçu değildir; arka plandaki uygulama durmuştur veya proxy_pass içinde yanlış port yazılmıştır. Sorunu izole etmek için önce sunucuda doğrudan curl ile uygulamaya ulaşmayı deneyin. Uygulama yanıt veriyor ama Nginx 502 döndürüyorsa, SELinux veya güvenlik duvarının yerel bağlantıyı engelleyip engellemediğine bakın.

Hata ayıklamanın en güçlü aracı Nginx günlükleridir. Erişim ve hata günlüklerini canlı izlemek çoğu sorunu saniyeler içinde açığa çıkarır:

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

Nginx ile Apache arasında hangisinin sizin senaryonuza uyduğunu merak ediyorsanız Apache ve Nginx karşılaştırması yazımız iki sunucunun reverse proxy performansını ve yapılandırma farklarını ayrıntılı ele alıyor. Sunucu yönetimini kendiniz üstlenmek istemiyorsanız, bu tür yapılandırmaları sizin adınıza kuran sunucu yönetimi hizmetimiz de mevcut.

Sıkça Sorulan Sorular#

Reverse proxy ile load balancer aynı şey mi?#

Aynı şey değildir ama iç içe geçebilirler. Reverse proxy, isteği arka plandaki bir uygulamaya yönlendiren genel katmandır; yük dengeleyici (load balancer) ise gelen istekleri aynı uygulamanın birden fazla kopyası arasında dağıtan özel bir reverse proxy davranışıdır. Nginx her ikisini de yapar. Tek bir arka plana yönlendiriyorsanız buna reverse proxy, upstream bloğuyla birden çok sunucuya dağıtıyorsanız buna yük dengeleme dersiniz.

proxy_pass adresinin sonuna eğik çizgi koymalı mıyım?#

Bu, taşımak istediğiniz yol yapısına bağlıdır. proxy_pass http://127.0.0.1:3000; şeklinde çizgisiz yazarsanız, location ile eşleşen yolun tamamı arka plana olduğu gibi iletilir. Sonuna / eklerseniz, location ön eki kesilir ve kalan kısım kök yola yeniden yazılır. Alt yol yönlendirmesi yaparken bu ayrım kritik olduğundan, kurduğunuz yapıyı curl ile test edip arka plana hangi yolun gittiğini doğrulamanızı öneririm.

Arka plandaki uygulama gerçek ziyaretçi IP'sini neden göremiyor?#

Çünkü uygulama, bağlantıyı Nginx'ten alır ve varsayılan olarak kaynağı Nginx sunucusunun IP'si olarak görür. Gerçek ziyaretçi IP'sini geri kazandırmak için Nginx'te proxy_set_header X-Real-IP $remote_addr; ve X-Forwarded-For başlıklarını iletmeniz, uygulamanızda ise bu başlıklara güvenmesi için proxy ayarını açmanız gerekir. Express kullanıyorsanız app.set('trust proxy', ...) satırı, bu başlıkların dikkate alınmasını sağlar.

WebSocket için mutlaka özel yapılandırma gerekli mi?#

Evet, gereklidir. Nginx varsayılan davranışında Upgrade ve Connection başlıklarını arka plana iletmez, bu da WebSocket el sıkışmasının başarısız olmasına yol açar. Bağlantının kurulabilmesi için proxy_http_version 1.1; satırını, Upgrade ve Connection başlıklarını eklemeniz ve proxy_read_timeout değerini yeterince yüksek tutmanız şarttır. Aksi halde bağlantı ya hiç kurulmaz ya da kısa süre sonra düşer.

SSL sertifikasını Nginx'te mi yoksa uygulamada mı tutmalıyım?#

Neredeyse tüm durumlarda sertifikayı Nginx'te tutmak en pratik yoldur. SSL sonlandırmayı reverse proxy'de yaparsanız sertifika yönetimi tek bir yerde toplanır, arka plandaki uygulamalar düz HTTP konuşur ve sertifika yenileme işini yalnızca Nginx için yaparsınız. Uçtan uca şifreleme gerektiren çok hassas senaryolar dışında, arka plana ayrıca sertifika koymanıza gerek yoktur.

502 Bad Gateway hatasını nasıl teşhis ederim?#

İlk adım, arka plandaki uygulamanın gerçekten çalıştığını doğrulamaktır. Sunucuda curl -I http://127.0.0.1:PORT komutunu çalıştırın; bir yanıt alıyorsanız uygulama ayaktadır ve sorun Nginx yapılandırmasındaki port veya adres hatasındadır. Yanıt alamıyorsanız uygulama durmuş demektir; süreç yöneticinizin (PM2, systemd, Docker) durumunu kontrol edin. Bu sırada /var/log/nginx/error.log dosyasını izlemek, Nginx'in tam olarak neye takıldığını satır satır gösterir.

Kapanış#

Reverse proxy, tek bir proxy_pass satırıyla başlayan ama başlık iletimi, WebSocket desteği, zaman aşımı ayarları ve SSL sonlandırmayla birlikte gerçek bir üretim mimarisine dönüşen güçlü bir kalıptır. Bu yazıda kurduğumuz şablonu bir kez kavradığınızda, ister Node ister Python ister Docker olsun herhangi bir uygulamayı dakikalar içinde alan adınıza güvenle bağlayabilirsiniz. Önemli olan başlıkları eksiksiz iletmek, HTTPS bilgisini arka plana taşımak ve zaman aşımlarını uygulamanızın gerçek davranışına göre ayarlamaktır.

Bu tür yapılandırmalar için tam kök erişimli, kaynakları size ayrılmış bir ortama ihtiyacınız var. Clou.TR'nin sanal sunucu ve VDS sunucu paketleri, Nginx reverse proxy kurmak ve birden fazla uygulamayı tek makinede barındırmak için gereken tam yönetim özgürlüğünü sunar. Sunucu yönetimini bize bırakmak isterseniz sunucu yönetimi hizmetimiz kurulumdan güvenliğe kadar süreci üstlenir; uygulamanızı hemen yayına almak istiyorsanız App Center katalogumuzdaki hazır servislerle işe başlayabilir, alan adınızı da domain sayfamızdan saniyeler içinde alabilirsiniz.