Nginx Proxy Manager Kurulumu

Nginx yapılandırma dosyalarını elle yazmak, proxy_pass satırlarını ezberlemek ve her alan adı için ayrı ayrı certbot çalıştırmak istemiyorsanız, Nginx Proxy Manager tam olarak bu boşluğu dolduran araçtır. Arkada gerçek bir Nginx çalışır, ama siz konfigürasyonu bir web arayüzünden yönetirsiniz: alan adını yazarsınız, hedef IP ve portu girersiniz, "SSL sertifikası iste" kutusunu işaretlersiniz ve iş biter. Ev laboratuvarında beş servis çalıştıran biri için de, tek VDS üzerinde on müşteri sitesini toplayan bir ajans için de bu iş akışı fazlasıyla pratiktir.

Bu rehberde Nginx Proxy Manager'ı (kısaca NPM) Docker üzerinde sıfırdan kuracağız, ilk yönetici hesabını güvene alacağız, bir proxy host tanımlayıp Let's Encrypt'ten ücretsiz SSL alacağız, erişim listeleriyle panelleri koruyacağız ve WebSocket, özel Nginx direktifleri, stream (TCP/UDP) yönlendirme gibi ileri konulara değineceğiz. Son bölümde de sahada en sık gördüğüm hataları — 502, sertifika alamama, veritabanı bozulması — nedenleriyle birlikte ele alacağım.

Nginx Proxy Manager Ne Yapar, Ne Yapmaz#

NPM üç şeyi bir araya getirir: bir Nginx örneği, bir yönetim arayüzü ve bir Let's Encrypt istemcisi. Arayüzde tanımladığınız her "Proxy Host" kaydı, arka planda gerçek bir Nginx server bloğuna dönüşür ve /data/nginx/proxy_host/ altına yazılır. Yani sihir yoktur; sadece dosya yazma işini sizin yerinize bir panel yapar. Bu, sorun çıktığında üretilen dosyaya bakıp neyin yanlış olduğunu görebileceğiniz anlamına gelir ki bu şeffaflık önemli bir avantajdır.

NPM'in yapmadıklarını da baştan bilmek gerekir. Konteyner keşfi yapmaz: yeni bir konteyner başlattığınızda otomatik olarak yayına girmez, arayüze girip elle tanımlarsınız. Karmaşık yük dengeleme senaryolarını (ağırlıklı dağıtım, sağlık kontrolü) desteklemez. Bir de yapılandırmayı kod olarak versiyonlamak isteyenler için uygun değildir; ayarlar bir SQLite veya MariaDB veritabanında durur. Bu üç ihtiyaçtan biri sizin için kritikse Traefik veya Caddy daha doğru tercih olur.

Kurulum: docker-compose ile Ayağa Kaldırma#

NPM tek konteyner olarak, dahili SQLite ile çalışabilir. Küçük ve orta kurulumlarda ayrı bir MariaDB açmanız gerekmez; bu hem RAM tasarrufu sağlar hem de yedekleme işini tek klasöre indirir. Önce bir dizin ve compose dosyası oluşturun:

mkdir -p /opt/npm/{data,letsencrypt}
cd /opt/npm

services:
  app:
    image: jc21/nginx-proxy-manager:latest
    container_name: npm
    restart: unless-stopped
    ports:
      - "80:80"      # HTTP trafiği
      - "443:443"    # HTTPS trafiği
      - "81:81"      # Yönetim arayüzü
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt
    environment:
      # SQLite kullanıldığında ek veritabanı ayarı gerekmez
      DISABLE_IPV6: 'true'

DISABLE_IPV6 satırı, sunucusunda IPv6 etkin olmayan makinelerde Nginx'in "Address family not supported" hatasıyla başlamamasını engeller; IPv6 kullanıyorsanız bu satırı silin. Şimdi başlatın:

docker compose up -d
docker compose logs -f app
# "Starting backend ..." ve ardından "Nginx is running" satırlarını bekleyin

Kurulumun ardından güvenlik duvarında yönetim portunu herkese açık bırakmayın. Panel yalnızca sizin çalıştığınız IP'den erişilebilir olmalı:

# 80 ve 443 herkese açık, 81 yalnızca ofis IP'nize
ufw allow 80,443/tcp
ufw allow from 185.12.34.56 to any port 81 proto tcp
ufw enable

Veri kaybını önlemek için data ve letsencrypt klasörlerini düzenli yedekleyin; bu iki klasör kurulumunuzun tamamıdır. Hacim mantığına yabancıysanız Docker volume ve veri yönetimi yazısı neyin kalıcı olduğunu netleştirir.

İlk Giriş ve Yönetici Hesabını Güvene Alma#

Tarayıcıdan http://sunucu-ip:81 adresine gidin. NPM ilk kurulumda sabit bir varsayılan hesapla gelir ve bu hesap internette herkesin bildiği bir bilgidir; bu yüzden ilk yapılacak iş onu değiştirmektir.

1. Varsayılan e-posta [email protected], varsayılan parola changeme ile giriş yapın.
2. Sistem sizi hemen profil düzenleme ekranına yönlendirir; adınızı ve gerçek e-posta adresinizi girin.
3. Ardından parola değiştirme ekranı gelir. Buraya uzun ve benzersiz bir parola girin — parola üretici aracımızla üretebilirsiniz.
4. Çıkış yapıp yeni bilgilerle tekrar giriş yaparak değişikliği doğrulayın.

Bu adımı ertelerseniz, panel portunu internete açık bıraktığınız her dakika sunucunuz taranan botlara açık demektir. NPM'i kurup varsayılan parolayla günlerce bırakılmış sunucuların ele geçirilmesi, sahada gördüğüm en sık ihmal senaryolarından biridir.

İlk Proxy Host'u Oluşturmak#

Elimizde 3000 portunda çalışan bir uygulama olduğunu varsayalım. Amacımız uygulama.firmaniz.com adresine gelen isteği bu uygulamaya taşımak. Önce DNS tarafında A kaydının sunucunuzun IP'sine baktığından emin olun; NPM sertifika alırken bunu doğrulayacak.

Panelde Hosts → Proxy Hosts → Add Proxy Host yolunu izleyin ve Details sekmesini doldurun:

Hedef adres konusunda en kritik ayrım şudur: NPM konteyneri ile uygulamanın aynı Docker ağında olması hâlinde hedef olarak doğrudan konteyner adını yazabilirsiniz (web-uygulamasi). Ağlar farklıysa konteyner adı çözülmez ve 502 alırsınız; bu durumda ya iki konteyneri ortak bir ağa alın ya da uygulamanın portunu host üzerine yayımlayıp 172.17.0.1:3000 gibi Docker köprü ağ geçidini hedefleyin.

# İki konteyneri ortak ağda buluşturmanın en temiz yolu
docker network create proxy
docker network connect proxy npm
docker network connect proxy web-uygulamasi

Bağlantının konteyner içinden çalışıp çalışmadığını doğrulamak, panelde uğraşmaktan çok daha hızlı sonuç verir:

docker exec -it npm curl -I http://web-uygulamasi:3000
# 200 veya 3xx dönüyorsa proxy tarafı sorunsuz demektir

Let's Encrypt ile Ücretsiz SSL Almak#

Aynı ekranın SSL sekmesine geçin. SSL Certificate açılır menüsünden Request a new SSL Certificate seçin ve şu üç kutuyu işaretleyin: Force SSL (HTTP'den HTTPS'e zorunlu yönlendirme), HTTP/2 Support ve HSTS Enabled. E-posta adresinizi girip Let's Encrypt şartlarını kabul edin ve kaydedin. Sertifika genellikle 10-40 saniye içinde gelir ve listede alan adının yanında yeşil bir SSL etiketi görürsünüz.

HSTS'i açarken bir noktaya dikkat edin: tarayıcı bu alan adı için HTTPS'i uzun süre zorunlu hafızasına alır. Alan adını ileride HTTP'ye döndürmeyi planlıyorsanız HSTS'i açmayın; test aşamasındaki kurulumlarda kapalı tutmak daha esnektir.

Wildcard sertifika (*.firmaniz.com) almak isterseniz HTTP doğrulaması yetmez, DNS doğrulaması gerekir. SSL sekmesinde Use a DNS Challenge seçeneğini işaretleyip DNS sağlayıcınızı listeden seçer ve API bilgilerinizi girersiniz. Bu yöntemin ek avantajı, sunucunuzun 80 portunun dışarıya kapalı olduğu durumlarda bile sertifika alabilmenizdir.

Sertifikaların yenilenmesi otomatiktir; NPM süresi dolmaya yaklaşan sertifikaları arka planda yeniler. Yine de ayda bir SSL Certificates sekmesine göz atıp "Expires" sütununda geçmiş tarih olup olmadığını kontrol etmek iyi bir alışkanlıktır. Sertifika bitiş tarihini dışarıdan da izleyebilirsiniz:

echo | openssl s_client -servername uygulama.firmaniz.com \
  -connect uygulama.firmaniz.com:443 2>/dev/null | openssl x509 -noout -dates
# notAfter satırındaki tarih bitiş tarihidir

Erişim Listeleri, Özel Yapılandırma ve Stream#

Access Lists sekmesi, herhangi bir proxy host'a parola veya IP kısıtlaması eklemenizi sağlar. Yeni bir liste oluşturup Authorization sekmesinde kullanıcı adı ve parola tanımlar, Access sekmesinde ise izin verilen IP bloklarını girersiniz. Ardından proxy host'un Details sekmesinden bu listeyi seçersiniz. Yönetim panelleri, staging siteleri ve iç araçlar için bu iki satırlık koruma çok işe yarar. IP bloklarını CIDR biçiminde yazmanız gerekir; hesaplamak için subnet hesaplayıcı aracımızı kullanabilirsiniz.

Arayüzde karşılığı olmayan Nginx direktiflerini Advanced sekmesinden serbestçe ekleyebilirsiniz. Bu alana yazdığınız her şey üretilen server bloğunun içine girer:

# Büyük dosya yüklemelerine izin ver
client_max_body_size 256m;

# Uzun süren isteklerde zaman aşımını uzat
proxy_read_timeout 300s;
proxy_send_timeout 300s;

# Gerçek ziyaretçi IP'sini arka uca ilet
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;

Streams sekmesi ise HTTP dışındaki trafiği yönlendirmek içindir: bir oyun sunucusunun UDP portu, bir veritabanı bağlantısı ya da özel bir TCP servisi. Burada alan adı değil, doğrudan port eşleştirmesi yaparsınız — çünkü TCP seviyesinde Host başlığı yoktur. Bu portların NPM konteynerinde de yayımlanmış olması gerekir, yani compose dosyasındaki ports: bölümüne eklemeniz şarttır; unutulan bu adım Streams kayıtlarının neden çalışmadığının en yaygın cevabıdır.

Sık Yapılan Hatalar#

502 Bad Gateway — NPM isteği aldı ama arka uca ulaşamadı. Sırasıyla kontrol edin: hedef port uygulamanın iç portu mu, iki konteyner aynı ağda mı, uygulama 0.0.0.0 üzerinde mi dinliyor (yalnızca 127.0.0.1 dinleyen bir servise dışarıdan erişilemez). Doğrulamayı yukarıdaki docker exec ... curl komutuyla yapın.

Sertifika alınamıyor, "Internal Error" — Neredeyse her zaman doğrulama trafiği sunucuya ulaşamıyordur. 80 portunun dışarıya açık olduğunu, alan adının A kaydının doğru IP'yi gösterdiğini ve önünde sertifikayı kendi sonlandıran bir CDN katmanı olmadığını doğrulayın. Cloudflare arkasındaysanız doğrulama sırasında ilgili kaydı geçici olarak "DNS only" moduna almak sorunu çözer.

Panel açılmıyor ama siteler çalışıyor — Genellikle veritabanı dosyası bozulmuştur; bu, sunucunun aniden kapanması ya da diskin dolması sonrası olur. data/database.sqlite dosyasının yedeğinden dönmek en hızlı çözümdür. Disk doluluğu Docker'da sinsi bir sorundur; Docker diski doldurdu, nasıl temizlenir yazısı bu konuyu ayrıntılı ele alıyor.

WebSocket bağlantısı düşüyor — Canlı sohbet, bildirim ya da terminal arayüzü olan uygulamalarda Websockets Support anahtarını açmayı unutmayın. Kapalıyken sayfa açılır ama gerçek zamanlı özellikler sessizce çalışmaz; tarayıcı konsolunda 400 veya 426 hatası görürsünüz.

Yönlendirme döngüsü — Arka uç uygulama kendi içinde HTTPS'e yönlendirme yapıyor ve NPM ona HTTP ile bağlanıyorsa sonsuz döngü oluşur. Çözüm, arka uca X-Forwarded-Proto $scheme başlığını iletmek ve uygulamanın proxy arkasında çalıştığını bilmesini sağlamaktır.

Sıkça Sorulan Sorular#

Nginx Proxy Manager ücretsiz mi#

Evet, tamamen açık kaynaklıdır ve ticari kullanım dahil ücretsizdir. Let's Encrypt sertifikaları da ücretsiz olduğu için toplam maliyetiniz yalnızca sunucudur. Ücretli bir sürümü, lisans anahtarı ya da özellik kısıtlaması yoktur; kaynak kodu ve imajı herkese açıktır.

Nginx Proxy Manager mı Traefik mi daha iyi#

Bu bir kalite karşılaştırmasından çok iş akışı tercihidir. Görsel bir panelden birkaç siteyi yönetiyorsanız ve yapılandırmayı kodda tutmak gibi bir gereksiniminiz yoksa NPM daha hızlı sonuç verir. Konteynerlerin sürekli gelip gittiği, dağıtımın otomatik olduğu bir ortamda ise Traefik'in etiket tabanlı otomatik keşfi elle kayıt girmekten çok daha verimlidir. İkisini aynı sunucuda çalıştırmayın; ikisi de 80 ve 443'ü ister.

Kurulum ne kadar sürer#

Docker kurulu bir sunucuda compose dosyasını yazıp konteyneri başlatmak birkaç dakika, ilk giriş ve parola değişimi bir dakika sürer. İlk proxy host'u tanımlayıp SSL almak da genellikle bir dakikanın altındadır. Toplamda on dakika içinde SSL'li, çalışan bir kurulumunuz olur; asıl zaman DNS kayıtlarının yayılmasını beklemekte geçer.

Panelin portunu nasıl değiştiririm#

Compose dosyasındaki 81:81 eşlemesinin sol tarafını değiştirmeniz yeterlidir; örneğin 18081:81 yazarsanız panele sunucu-ip:18081 üzerinden erişirsiniz. Konteyner içindeki port sabittir, sağ tarafa dokunmayın. Port değiştirmek gerçek bir güvenlik önlemi değildir; asıl koruma güvenlik duvarında portu yalnızca kendi IP'nize açmak veya paneli bir VPN arkasına almaktır.

Aynı sunucuda birden çok siteyi yönetebilir miyim#

Evet, NPM'in asıl kullanım amacı budur. Her alan adı için ayrı bir Proxy Host kaydı oluşturur, her birine kendi SSL sertifikasını alır ve hepsi tek Nginx üzerinden 443 portunu paylaşır. Sınır pratikte sunucunuzun kaynaklarıdır; yüzlerce kayıt yönetildiği kurulumlar mevcuttur.

Yedeğimi nasıl alırım#

Kurulumun tamamı iki klasördedir: data ve letsencrypt. Konteyneri durdurup bu iki klasörü arşivlemek eksiksiz bir yedek üretir. Geri dönerken aynı klasörleri yeni sunucuya kopyalayıp compose dosyasını başlatmanız yeterlidir; tüm proxy kayıtları ve sertifikalar olduğu gibi gelir. Yedeği düzenli almak ve başka bir makinede saklamak, tek diskli sunucularda kritik önemdedir.

Kapanış#

Nginx Proxy Manager'ı verimli kullanmanın püf noktaları aslında birkaç alışkanlıkta toplanıyor: kurulumdan sonraki ilk iş varsayılan parolayı değiştirmek, 81 portunu güvenlik duvarında yalnızca kendinize açmak, proxy hedefi olarak uygulamanın iç portunu ve doğru ağdaki adını vermek, WebSocket gerektiren uygulamalarda ilgili anahtarı açmak ve data ile letsencrypt klasörlerini düzenli yedeklemek. Bir sorun çıktığında da panelde dolaşmadan önce konteyner içinden curl ile arka uca ulaşıp ulaşamadığınızı test etmek, sorunun proxy'de mi uygulamada mı olduğunu saniyeler içinde söyler.

Bu kurulumun tamamı tek bir sunucuda rahatlıkla döner; kendi ters proxy'nizi barındırmak için tam root erişimi sunan VDS veya sanal sunucu paketlerimiz uygun bir başlangıç noktasıdır. Sertifika, güvenlik duvarı ve güncellemelerle uğraşmak istemiyorsanız sunucu yönetimi hizmetimiz bu bakımı üstlenir; kurumsal doğrulamalı sertifika ihtiyacınız varsa SSL sayfamızdaki seçenekleri inceleyebilirsiniz.