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

Reverse proxy, birden fazla uygulamayı tek bir domain/port arkasından yönetmenizi sağlar. Doğru kurulduğunda gerçek istemci IP’si korunur, SSL tek noktada sonlandırılır ve uygulamalar doğrudan internete açılmadan güvenli hale gelir. Bu rehberde Nginx reverse proxy kurulumunu Linux üzerinde adım adım ilerleteceksiniz: upstream tanımı, gerekli header’lar, SSL, yönlendirme, cache ve yaygın hataların net çözümü.

Aşağıdaki anlatım, tipik olarak Ubuntu/Debian üzerinde çalışan Nginx için hazırlanmıştır. Dağıtımınız farklıysa paket isimleri dışında mantık aynıdır.

1) Reverse proxy mimarisi ve hedefi netleştirme

Reverse proxy kurmaya başlamadan önce iki kararı net vermek gerekir:

• SSL’yi Nginx’te sonlandırma: Kullanıcı ile Nginx arasındaki TLS (HTTPS) burada biter. Arka uç uygulamalar HTTP veya HTTPS konuşabilir.
• Uygulama erişimi: Uygulama sunucusu (ör. 127.0.0.1:3000) sadece proxy’den erişilebilir olmalı. İnternete açık porta ihtiyacınız azalır.

Tipik senaryo: - example.com → Nginx → http://127.0.0.1:3000 (Node/Next gibi) - example.com/api → Nginx → http://127.0.0.1:8080 (Java/Go gibi)

Hangi durumlarda reverse proxy şart?

• Birden fazla servis tek domain altında barınacaksa
• Gerçek kullanıcı IP’sini uygulamaya taşımak istiyorsanız (log/ratelimit/WAF için)
• Tek noktadan HTTP→HTTPS yönlendirmesi ve tek SSL yönetimi istiyorsanız
• Cache (özellikle statik içerik veya hafif dinamik) planlıyorsanız

2) Önkoşullar: ağ, güvenlik ve uygulama erişimi

Kurulum adımlarına geçmeden önce doğrulama yapın.

Sunucuda uygulama portu erişilebilir mi?

Uygulamanız Nginx’ten erişilebilir bir portta çalışmalı. Örnek kontrol: - Uygulama localhost:3000 dinliyorsa: - curl http://127.0.0.1:3000/ komutu sorunsuz yanıt vermeli.

Bu test başarısızsa Nginx yapılandırması başlamadan boşa gider.

Güvenlik kuralı: arka uç portlarını sınırlayın

En net yaklaşım: - Uygulama sunucusu sadece 127.0.0.1 dinlesin. - Uygulama VDS/VPS üzerinde farklı bir makinedeyse güvenlik grubunda sadece Nginx sunucusunun IP’sinden erişime izin verin.

3) Nginx kurulumu ve temel yapılandırma

Nginx paketini yükleyin

Debian/Ubuntu için: - sudo apt update - sudo apt install -y nginx

Ardından servis durumu: - sudo systemctl status nginx

Test sayfasını kaldırmadan önce doğrulayın

Nginx default siteyi açıp HTTP çalışıyor mu kontrol edin: - Tarayıcıdan server IP veya domain ile erişim

Erişim yoksa firewall/port açma/hosting firewall tarafını düzeltin.

Config yapısı: site dosyaları

Standart yaklaşım: - /etc/nginx/sites-available/ içinde siteyi tanımlayın - /etc/nginx/sites-enabled/ üzerinden etkinleştirin

4) Upstream ve server bloğu: adım adım konfigürasyon

Aşağıdaki örnek tek domain için temel reverse proxy kurulumunu gösterir.

Adım 4.1: upstream tanımı ekleyin

Öneri: upstream’i blok halinde kurun. Load balancing yapmasanız bile bakım kolaylığı sağlar.

/etc/nginx/sites-available/reverse-proxy.conf dosyasına şu mantıkla başlayın:

• upstream app_backend { server 127.0.0.1:3000; }

Adım 4.2: server bloğunu yazın

Aynı dosyada server { ... } içinde proxy ayarları yapılır.

Aşağıdaki ayarların tamamı “neden var?” sorusuna yanıt veren pratik bileşenlerdir: - Gerçek istemci IP’si: X-Real-IP ve X-Forwarded-For - Protokol bilgisi: X-Forwarded-Proto - Host koruma: uygulama çoklu domain kullanıyorsa Host doğru gelmeli - WebSocket (gerekirse): Upgrade ve Connection

Örnek konfigürasyon (domain ve portları kendi değerlerinizle değiştirin):

server {
    listen 80;
    server_name example.com www.example.com;

    # Reverse proxy
    location / {
        proxy_pass http://app_backend;
        proxy_http_version 1.1;

        # Gerçek istemci IP
        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;

        # WebSocket
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Zaman aşımı (uzun yanıtlar için)
        proxy_connect_timeout 5s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;

        # Proxy header temizliği yok, uygulamaya iletilenler bilinsin
    }
}

Not: WebSocket ihtiyacınız yoksa Upgrade/Connection satırlarını bırakabilirsiniz; ancak çoğu modern uygulama için güvenli bir standarttır.

Adım 4.3: config’i aktif edin

• Dosyayı sites-enabled’a bağlayın:
• sudo ln -s /etc/nginx/sites-available/reverse-proxy.conf /etc/nginx/sites-enabled/

Ardından Nginx config doğrulama: - sudo nginx -t

Sorunsuzsa reload: - sudo systemctl reload nginx

Adım 4.4: doğrulama testi

• curl -I http://example.com/
• Uygulama loglarında X-Forwarded-For değerleri görünmeli.

5) HTTPS (SSL) ve HTTP→HTTPS yönlendirmesi

SSL kurulumu reverse proxy’de en kritik bölümdür; yanlış yapılırsa hem güvenlik hem de SEO etkilenir.

Adım 5.1: sertifikayı alın

En yaygın yöntem Let’s Encrypt’tir (Certbot). Net bir çalışma için: - sudo apt install -y certbot python3-certbot-nginx - Ardından etki alanı bazlı kurulum

Örnek (domain’i kendi değerlerinizle değiştirin): - sudo certbot --nginx -d example.com -d www.example.com

Adım 5.2: HTTPS server bloğu oluşturun

Certbot otomatik ekleyebilir; yine de reverse proxy ayarlarının listen 443 ssl; bloğunda da geçerli olduğundan emin olun.

Basit bir şablon yaklaşımı: - 80 → 443 yönlendirmesi - 443 → reverse proxy (proxy_pass aynı)

Örnek yönlendirme:

server {
    listen 80;
    server_name example.com www.example.com;

    return 301 https://$host$request_uri;
}

6) Cache, hata sayfaları ve performans ayarları (net kurallar)

Reverse proxy yalnızca yönlendirme değildir; doğru cache ve hata sayfalarıyla gecikme düşer.

6.1 Cache’i sadece uygun içerikte kullanın

Tüm yanıtları cache’lemek yanlış olabilir. Net kriter: - Statik içerik: cache uzun olabilir - Dinamik: uygulamanın “cache edilebilir” başlıklarını temel alın

Örnek hafif cache yaklaşımı (dinamik içerikte temkinli olun):

location / {
    proxy_pass http://app_backend;

    proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=app_cache:10m inactive=60m use_temp_path=off;

    proxy_cache app_cache;
    proxy_cache_valid 200 30m;
    proxy_cache_valid 404 1m;

    proxy_no_cache $http_cache_control;
    proxy_cache_bypass $http_cache_control;
}

Bu örnek tek başına kopyala-yapıştır değildir. Nginx sürümünüz ve global cache tanımlarınıza göre düzenlemek gerekir. İlk hedefiniz: önce cache davranışını doğrulamak.

6.2 Hata sayfaları: uygulama arızası ile Nginx arızasını ayırın

Uygulama 502-504 döndüğünde bunun nereden kaynaklandığını loglardan görebilmek gerekir. Nginx’te hata yanıtlarını standartlaştırın.

Önerilen yaklaşım: - 502 Bad Gateway için basit bir JSON/HTML yanıt (uygulama değil Nginx sorunu için) - 504 Gateway Timeout için zamanı kontrol edin

Örnek mantık: - proxy_read_timeout çok düşükse 504 sıklaşır - upstream tarafında saturasyon varsa 502 artar

6.3 Zaman aşımı ve body boyutu

Net standart değerler yerine trafik modelinize göre ayarlayın: - dosya yükleme varsa client_max_body_size - uzun istekler varsa proxy_read_timeout

Örnek: - client_max_body_size 50m;

7) Multi-path (örn: /api) ve path bazlı yönlendirme

Birden çok servis aynı domain altında olacaksa, location kuralları kritik olur.

Örnek: - /api → app_api_backend - / → app_web_backend

Örnek konfigürasyon mantığı:

location /api {
    proxy_pass http://app_api_backend;

    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 / {
    proxy_pass http://app_web_backend;
}

Net uyarı: - Path eşleşmelerinde /api/ ile /api farkı uygulama tarafını etkileyebilir. - 301/302 yönlendirmelerini uygulama URL’leriyle uyumlu tutun.

8) Ortak hatalar ve net giderme listesi

Aşağıdaki kontrol listesi, reverse proxy kurulumu sonrası en sık yaşanan problemleri hızlı ayırır.

8.1 502 Bad Gateway

Belirti: Nginx 502 veriyor. En net sebepler: - upstream portu kapalı veya uygulama çalışmıyor - Nginx yanlış IP/port’a bağlanıyor - Firewall proxy→app engelliyor

Kontrol: - Uygulama portunu yerelden test edin: curl http://127.0.0.1:3000/ - Nginx hata logu: /var/log/nginx/error.log

8.2 504 Gateway Timeout

Belirti: Uygulama yanıt vermiyor veya çok geç dönüyor.

Kontrol: - proxy_read_timeout değerini artırın - Uygulama tarafında performans darboğazı var mı bakın (CPU/RAM, DB gecikmesi)

8.3 Uygulama gerçek IP göremiyor

Belirti: loglarda her istek proxy IP’si gibi görünür.

Çözüm: - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - Uygulama ayarlarınız X-Forwarded-For’u doğru yorumluyor mu kontrol edin

8.4 WebSocket çalışmıyor

Çözüm: - proxy_http_version 1.1 - Upgrade ve Connection header’ları doğru

9) Kurulumu sürdürülebilir yapmak: loglar ve izleme

Reverse proxy “kurulur biter” değildir; düzenli izleme karar verir.

9.1 Nginx log rotasyonu

Loglar büyürse disk dolması yaşanır. Bu nedenle log rotasyonu açık olmalı: - logrotate ile kontrol

9.2 Başarı metriği: statü dağılımı ve gecikme

Net yaklaşım: - 2xx/4xx/5xx oranını düzenli izleyin - 502/504 artıyorsa upstream ve zaman aşımı ayarlarını gözden geçirin

9.3 Config sürümü ve geri dönüş planı

• Değişiklik öncesi config yedeği alın: cp -a /etc/nginx /etc/nginx.bak-$(date +%F)
• nginx -t olmadan reload yapmayın

Karşılaştırma tablosu: Reverse proxy ayarlarını nasıl seçmelisiniz?

Aşağıdaki tablo karar vermeyi hızlandırır.

Sonuç: Bugün kurabileceğiniz net aksiyon planı

Nginx reverse proxy kurulumunda başarı, sadece proxy_pass yazmakla gelmez; doğru header’lar, SSL geçişi, zaman aşımı değerleri ve hata senaryolarının net yönetimi belirleyicidir. Önce uygulamanızın upstream portunu yerelden test edin, ardından tek bir server bloğunda location / ile çalıştırın. Çalıştığını doğruladıktan sonra 80→443 yönlendirmesini ekleyin, sonra gerekliyse /api gibi path bazlı yönlendirmeye geçin ve en son cache/hata sayfalarını optimize edin.

İsterseniz mevcut mimarinizi (tek uygulama mı, /api ayrımı var mı, WebSocket kullanılıyor mu, arka uç portları neler?) yazın; buna göre Nginx config şablonunuzu netleştirecek şekilde uyarlayabilirim.