Nginx Reverse Proxy Kurulumu: Adım Adım Rehber

Nginx reverse proxy, dış istekleri 80 veya 443 numaralı portta karşılayıp localhost'ta çalışan uygulamaya aktarır. Ubuntu'da Nginx'i yükleyin, ayrı bir server bloğu oluşturun, proxy_pass ve istemci başlıklarını tanımlayın, nginx -t ile doğrulayın ve yalnızca başarılı testten sonra reload uygulayın.

Nginx reverse proxy ne işe yarar?

Reverse proxy, istemci ile uygulama sunucusu arasında duran ve HTTP isteklerini arka uç servisine ileten katmandır. Nginx bu görevle 80 ve 443 numaralı portlarda bağlantıları karşılayabilir; uygulama ise yalnızca 127.0.0.1:3000, 127.0.0.1:8000 veya özel bir Unix socket üzerinden çalışır. Böylece TLS sonlandırma, alan adı yönlendirmesi, erişim günlükleri ve temel güvenlik kuralları tek bir noktada yönetilir.

Kurulum birkaç dosya düzenlemekten ibaret görünür. Asıl dikkat edilmesi gerekenler istemci IP bilgisinin arka uca doğru aktarılması, WebSocket bağlantılarının kopmaması, DNS kaydının doğru sunucuyu göstermesi ve yapılandırmanın yeniden yüklemeden önce doğrulanmasıdır.

HTTP isteklerinin hangi alan adından geldiğini anlamak için Domain ve URL Farkı Nedir? başlığındaki ayrım işe yarar: Nginx sunucu adına göre doğru server bloğunu seçer, URL’nin yol kısmı ise çoğunlukla location kurallarıyla işlenir.

Dinleme adresini belirleyin – Uygulamayı mümkünse dış ağa açmadan yalnızca localhost üzerinde çalıştırın.

Kurulumdan önce hangi bilgiler hazırlanmalı?

Örnek yapılandırmada Ubuntu 22.04 veya 24.04, Nginx ve 3000 numaralı portta çalışan bir uygulama kullanılacaktır. Dağıtım farklı olsa da dosya yolları Debian tabanlı sistemlerde genellikle aynıdır. Ubuntu’da Nginx Kurulumu ve İlk Yapılandırma başlığında paket kurulumunun temel adımları ayrıca ele alınır; burada reverse proxy katmanına odaklanılır.

Önce alan adının A veya AAAA kaydının VPS adresini gösterdiğini doğrulayın. Yetkili DNS cevabını görmek için aşağıdaki komutlar yeterlidir:

dig +short example.com A
dig +short example.com AAAA

Beklenen çıktı VPS’nin IPv4 veya IPv6 adresidir. Eski bir adres dönüyorsa Nginx yapılandırmasını değiştirmek sorunu çözmez; istekler hâlâ başka bir sunucuya gidebilir. DNS değişikliklerinin yayılma süresi ve önbellek davranışı için DNS Yayılması Nedir? Ne Kadar Sürer? başlığına bakılabilir.

Arka uç uygulamasını Nginx’i devreye almadan test edin:

ss -ltnp | grep ':3000'
curl --fail --silent --show-error http://127.0.0.1:3000/

ss çıktısında uygulama sürecinin 3000 numaralı portu dinlediği görülmelidir. curl komutu 2xx veya uygulamanın beklenen başka bir HTTP durum kodunu döndürmelidir. Hiçbir süreç dinlemiyorsa Nginx’e geçmeden önce uygulama servisini düzeltin.

Arka ucu doğrulayın – Nginx yapılandırmasına geçmeden önce localhost isteğinin başarılı olduğunu kanıtlayın.

Ubuntu’da Nginx reverse proxy kurulumu nasıl yapılır?

Paketi yükleyin ve servisi etkinleştirin

Ubuntu depolarındaki paketi kurup servisin durumunu kontrol edin:

sudo apt update
sudo apt install nginx
sudo systemctl enable --now nginx
sudo systemctl status nginx --no-pager

Varsayılan kurulum 80 numaralı portta dinler. Güvenlik duvarı kullanılıyorsa HTTP ve HTTPS profillerinin açık olduğundan emin olun. UFW etkinse şu komutlar kullanılabilir:

sudo ufw allow 'Nginx Full'
sudo ufw status verbose

Bu kural TCP 80 ve TCP 443 portlarını kapsar. Uygulamanın 3000 numaralı portunu internete açmak gereksizdir; arka uç yalnızca localhost’a bağlıysa dışarıdan erişilemez.

Site dosyasını oluşturun

Debian tabanlı Nginx paketleri etkin siteleri /etc/nginx/sites-enabled/ altındaki sembolik bağlantılarla yükler. Önce yapılandırma dosyasını oluşturun:

sudo vim /etc/nginx/sites-available/example.com

Aşağıdaki temel yapılandırma, example.com alan adından gelen istekleri 3000 numaralı porttaki servise iletir:

server {
    listen 80;
    listen [::]:80;

    server_name example.com www.example.com;

    access_log /var/log/nginx/example.com.access.log;
    error_log  /var/log/nginx/example.com.error.log warn;

    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_read_timeout 60s;
        proxy_connect_timeout 5s;
    }
}

proxy_pass hedef servisi belirler. Host başlığı uygulamanın hangi alan adıyla çağrıldığını korur; X-Real-IP ve X-Forwarded-For istemci adresini arka uca taşır. Bu başlıklar uygulamanın gördüğü istemci bilgisini etkiler; uygulama yalnızca güvenilen proxy katmanlarından gelen değerlere güvenecek şekilde ayarlanmalıdır.

proxy_read_timeout, Nginx’in arka uçtan yanıt bekleme süresidir. Bu değer uygulamanın uzun süren işleriyle birlikte değerlendirilmelidir. Rastgele birkaç dakikaya yükseltmek, kopmuş bağlantıların daha uzun süre kaynak tüketmesine yol açabilir.

Sembolik bağlantıyı oluşturup varsayılan siteyi kaldırın:

sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/example.com
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx

nginx -t başarılı olmadan reload çalıştırmayın. Başarılı çıktı genellikle syntax is ok ve test is successful satırlarını içerir. Yeniden yükleme mevcut bağlantıları genellikle kesmeden yeni yapılandırmayı devreye alır; restart ise servis sürecini durdurup yeniden başlatır.

Yapılandırmayı sınayın – Her değişiklikten önce sudo nginx -t çalıştırın ve yalnızca başarılı kontrolden sonra reload uygulayın.

İstemci IP’si ve proxy başlıkları nasıl ayarlanır?

Reverse proxy arkasındaki uygulama, TCP bağlantısının doğrudan Nginx’ten geldiğini görür. Uygulama loglarında gerçek istemci adresinin görünmesi için başlıkların aktarılması gerekir. $proxy_add_x_forwarded_for, mevcut X-Forwarded-For zincirine Nginx’in gördüğü adresi ekler; yalnızca $remote_addr kullanmak önceki güvenilir proxy bilgisini kaybettirebilir.

Uygulama HTTPS bağlantısını Nginx sonlandırdıktan sonra HTTP olarak alıyorsa X-Forwarded-Proto: https başlığı önem kazanır. Uygulama bu başlığı tanımıyorsa güvenli URL üretirken http:// kullanabilir, oturum çerezlerine Secure niteliği eklemeyebilir veya sonsuz HTTPS yönlendirmesi oluşturabilir.

Arka uç aynı makinede çalışıyorsa başlıkların dışarıdan doğrudan manipüle edilmesi zorlaşır. Nginx başka bir CDN veya yük dengeleyicinin arkasındaysa güvenilen proxy adresleri ayrıca tanımlanmalı, uygulamanın gelen her X-Forwarded-For değerini sorgusuz kabul etmesine izin verilmemelidir.

RFC 7239, standartlaştırılmış Forwarded başlığının söz dizimini tanımlar. Pratikte birçok uygulama ve web sunucusu hâlâ X-Forwarded-For, X-Forwarded-Proto ve X-Real-IP başlıklarını bekler. Kullanılacak biçimi uygulamanın dokümantasyonuyla eşleştirin.

Güven sınırını tanımlayın – Uygulamanın yalnızca kendi reverse proxy katmanından gelen istemci IP’sine güvenmesini sağlayın.

HTTPS ve alan adı yönlendirmesi nasıl eklenir?

HTTP testi tamamlandıktan sonra TLS sertifikası eklenebilir. Sertifika alınmadan önce DNS kaydı doğru sunucuyu göstermeli ve TCP 80 portu ACME HTTP-01 doğrulaması için erişilebilir olmalıdır. Certbot gibi araçlarla sertifika üretilecekse otomatik değişiklikten önce mevcut Nginx dosyalarının yedeğini alın.

HTTPS kullanan yapılandırmanın temel biçimi şöyledir:

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name example.com www.example.com;

    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

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

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

HTTP bloğundaki 301 yönlendirmesi yolu ve sorgu dizesini koruyarak istemciyi HTTPS’e taşır. Sertifika dosyaları henüz yoksa nginx -t başarısız olur; TLS bloğunu sertifika üretiminden önce etkinleştirmeyin.

Birden fazla alan adı kullanılacaksa her alan adının sertifikada yer aldığını kontrol edin. Sertifika yenileme işinden sonra yapılandırma testi ve Nginx reload adımları otomatik görevin parçası olmalıdır. Sertifika dosyalarının yenilenmesi, çalışan Nginx sürecinin yeni dosyayı kendiliğinden okuduğu anlamına gelmez.

HTTPS’i doğrulayın – Sertifika, alan adı, HTTP yönlendirmesi ve otomatik yenileme akışını birlikte test edin.

WebSocket ve uzun bağlantılar için ne değişir?

Standart HTTP isteklerinde temel proxy yapılandırması yeterlidir. WebSocket ise HTTP yükseltmesiyle farklı bir bağlantı akışı kullanır. Nginx’in Upgrade ve Connection başlıklarını arka uca iletmesi gerekir.

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

server {
    listen 443 ssl;
    server_name app.example.com;

    location /socket.io/ {
        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_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }
}

map bloğu http bağlamında, genellikle /etc/nginx/nginx.conf içindeki http {} bölümünde bulunmalıdır. Site dosyasının içine eklenirse Nginx bağlam hatası verebilir. WebSocket yolu uygulamaya göre /socket.io/, /ws/ veya farklı bir değer olabilir.

Uzun timeout değeri bağlantının sağlıklı olduğunu kanıtlamaz. Uygulama heartbeat göndermeli, monitoring sistemi açık bağlantıların sayısını ve hata oranını izlemelidir. VPS’te Prometheus ve Grafana ile İzleme başlığı, bu metrikleri görünür kılacak temel yaklaşımı açıklar.

Yükseltmeyi sınırlayın – Upgrade başlıklarını yalnızca gerçekten WebSocket kullanan location bloklarında etkinleştirin.

Statik dosyalar, alt yollar ve birden fazla uygulama

Bir VPS üzerinde birden fazla uygulama çalıştırılabilir. Nginx her alan adı için ayrı server bloğu seçebilir; aynı alan adının farklı yolları da ayrı upstream hedeflerine gönderilebilir.

upstream api_backend {
    server 127.0.0.1:8000;
    keepalive 16;
}

server {
    listen 443 ssl;
    server_name example.com;

    root /var/www/example.com/public;

    location /assets/ {
        try_files $uri =404;
        access_log off;
        expires 7d;
    }

    location /api/ {
        proxy_pass http://api_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

proxy_pass satırının URI ile veya URI olmadan kullanılması, yolun arka uca aktarılma biçimini etkiler. Örneğin location /api/ içinde proxy_pass http://127.0.0.1:8000; kullanıldığında istek yolu korunur; proxy_pass http://127.0.0.1:8000/; kullanıldığında eşleşen bölümün değiştirilmesi söz konusu olabilir. API’nin /api/users yerine /users bekleyip beklemediğini küçük bir curl testiyle doğrulayın.

Statik dosyalarda try_files $uri =404; kullanılması, bulunmayan dosyaların uygulamaya gereksiz yere gönderilmesini önler. Önbellek süresini dosya adlandırma stratejisiyle birlikte belirleyin; içerik değiştiğinde aynı URL kullanılacaksa uzun expires değerleri eski dosyaların tarayıcıda kalmasına yol açabilir.

Yol eşleşmesini test edin – Her location için beklenen istemci yolunu ve arka ucun aldığı gerçek yolu ayrı ayrı doğrulayın.

Hatalar nasıl incelenir ve performans nasıl izlenir?

Bir proxy hatasında servisi hemen yeniden başlatmak yerine üç katmanı ayırın: istemci ile Nginx, Nginx ile arka uç ve uygulamanın kendi logları. İlk testleri alan adı yerine doğrudan yerel hedefe, ardından Nginx’e ve en son HTTPS alan adına yöneltin.

curl -I http://127.0.0.1:3000/
curl -I -H 'Host: example.com' http://127.0.0.1/
curl -vk https://example.com/
sudo tail -f /var/log/nginx/example.com.error.log
sudo journalctl -u nginx -n 100 --no-pager

İlk komut uygulamanın durumunu, ikinci komut doğru server_name seçimini, üçüncü komut ise TLS el sıkışmasını ve yönlendirmeleri gösterir. 502 Bad Gateway çoğunlukla Nginx’in arka uca bağlanamadığını, uygulamanın kapalı olduğunu, yanlış port veya socket kullanıldığını gösterir. 504 Gateway Timeout ise bağlantının kurulup arka uç yanıtının zamanında gelmemesiyle ilişkilidir; uygulama logları incelenmeden timeout değerini artırmak doğru teşhis değildir.

Access loglarda istek süresi ve upstream süresi görülebilir. Daha ayrıntılı ölçüm için log formatına $request_time, $upstream_connect_time ve $upstream_response_time değişkenleri eklenebilir:

log_format proxy_timing '$remote_addr - $host [$time_iso8601] '
                        '"$request" $status $body_bytes_sent '
                        'rt=$request_time '
                        'uct=$upstream_connect_time '
                        'urt=$upstream_response_time';

Bu formatı http bağlamında tanımlayıp ilgili server bloğunda access_log satırına uygulayın. Ham logları uzun süre saklamak disk tüketimini artırır; logrotate ayarlarının ve disk alarmının birlikte çalıştığını kontrol edin.

Nginx’i CDN ile birlikte kullanıyorsanız istemci IP’si, önbellek başlıkları ve HTTPS yönlendirmeleri iki proxy katmanında farklılaşabilir. CDN Nedir? Web Sitesini Nasıl Hızlandırır? başlığındaki önbellek katmanı ile origin sunucu ayrımı, bu mimarinin sınırlarını anlamaya yardımcı olur.

Katmanlı teşhis yapın – Önce arka ucu, sonra Nginx’i, ardından TLS ve varsa CDN katmanını ayrı ayrı ölçün.

Yayına almadan önce güvenlik kontrolü

Reverse proxy uygulama portunu gizler, fakat tek başına güvenlik duvarı değildir. Yönetim paneli, veritabanı ve debug endpoint’leri internete açık bırakılmamalıdır. Uygulamanın 127.0.0.1 üzerinde dinlemesi iyi bir başlangıçtır; ayrı sunucudaki arka uç için yalnızca Nginx sunucusunun özel IP’sine izin veren güvenlik duvarı kuralı gerekir.

HTTP başlıklarını sabit bir reçete gibi eklemek yerine uygulamanın beklentisini doğrulayın. Host değerini kullanıcı girdisi gibi kullanan uygulamalarda izin verilen alan adlarını açıkça tanımlayın. Dosya yükleme yapan servislerde Nginx’in client_max_body_size değeri uygulama limitinden düşükse istemci 413 Request Entity Too Large alabilir; PHP veya uygulama limitini yükseltmek Nginx sınırını otomatik olarak değiştirmez.

Yapılandırma dosyalarının izinlerini gereksiz yere genişletmeyin. Sertifika özel anahtarı yalnızca root ve Nginx worker sürecinin ihtiyaç duyduğu kullanıcı tarafından okunabilmelidir. SSH portunu değiştirmek veya chmod 777 çalıştırmak proxy güvenliğinin yerine geçmez.

Dağıtımdan önce yapılandırmayı yedekleyin:

sudo cp -a /etc/nginx /etc/nginx.backup.$(date +%F-%H%M)
sudo nginx -t
sudo systemctl reload nginx
curl --fail --silent --show-error -o /dev/null -w '%{http_code}\n' https://example.com/

Son curl komutu yalnızca HTTP durum kodunu yazdırır. Uygulama gövdesinin doğru olduğunu kanıtlamaz; kritik bir yayında giriş, statik dosya, API ve WebSocket akışlarını ayrıca deneyin.

Geri dönüş planını hazırlayın – Eski dosyayı saklayın, değişikliği reload ile uygulayın ve başarısızlıkta önceki yapılandırmaya dönün.

Yayına Almadan Önce Şunları Kontrol Edin

• DNS A ve AAAA kayıtlarını VPS adresiyle eşleştirin.
• Arka uç servisini localhost üzerinde çalıştırın.
• Nginx server bloğunda alan adını doğru yazın.
• proxy_set_header satırlarını uygulamanızın beklentisiyle karşılaştırın.
• sudo nginx -t komutunu başarılı çıktı alana kadar düzeltin.
• HTTP, HTTPS, API ve WebSocket akışlarını ayrı ayrı test edin.
• Eski yapılandırmayı saklayıp geri dönüş komutunu hazır tutun.

Sık Sorulan Sorular

Kaynaklar

• NGINX – ngx_http_proxy_module — nginx.org
• RFC 7239 – Forwarded HTTP Extension — rfc-editor.org
• MDN – X-Forwarded-For — developer.mozilla.org
• NGINX – ngx_http_upstream_module — nginx.org