Node.js Uygulaması Yayınlama: PM2 ve Nginx Reverse Proxy

Geliştirme sırasında node app.js ile çalıştırdığınız bir uygulamayı sunucuda kesintisiz, güvenli ve alan adınız üzerinden erişilebilir hâle getirme sürecine Node.js uygulaması yayınlama denir. Express, Fastify, NestJS ya da Next.js ile yazılmış bir projeyi kendi VPS sunucunuzda yayına alırken üç sorunu çözmeniz gerekir: çökme ya da yeniden başlatma sonrasında uygulamanın kendiliğinden ayağa kalkması, 80/443 portlarıyla TLS’in yönetilmesi ve gizli bilgilerin korunması.

Önerilen düzende ziyaretçinin isteği önce Nginx’e gelir, Nginx onu sunucunun içinde 127.0.0.1:3000 adresini dinleyen uygulamaya iletir. Nginx tarafının temelleri Ubuntu Nginx kurulumu rehberindedir; komutlar Ubuntu 24.04 LTS içindir.

Node.js uygulaması yayınlamanın mimarisi nasıldır?

Üretim ortamında bir Node.js uygulaması, her biri ayrı bir işi üstlenen katmanlarla birlikte yayınlanır:

Uygulamayı doğrudan 80 portunda çalıştırmak önerilmez: Linux’ta 1024’ün altındaki portlar root yetkisi ya da özel bir yetenek (capability) ister ve root olarak çalışan bir Node.js sürecindeki tek bir açık tüm sunucuyu tehlikeye atar. Reverse proxy ayrıca aynı IP üzerinde birden fazla uygulamayı farklı alan adlarıyla yayınlamanızı sağlar.

Node.js LTS sürümü nasıl kurulur?

Üretimde Node.js’in LTS (uzun süreli destek) sürümünü kullanın. Ubuntu deposundaki nodejs paketi çoğu zaman eski bir ana sürümde kaldığından iki yaygın yol tercih edilir.

NodeSource deposu (sistem geneli)

curl -fsSL https://deb.nodesource.com/setup_lts.x -o nodesource_setup.sh
sudo bash nodesource_setup.sh
sudo apt install nodejs
node -v
npm -v

Betik o anki LTS dalının deposunu ekler; Node.js /usr/bin/node altına kurulur ve npm pakete dahildir. Systemd servisleri ve PM2’nin açılış betiği için en sorunsuz yoldur; betiği çalıştırmadan önce içeriğine göz atmak iyi bir alışkanlıktır.

nvm (kullanıcı bazında)

nvm, Node.js’i yalnızca kurulduğu kullanıcının ev dizinine yükler ve birden fazla sürümü yan yana tutmanıza izin verir. nvm’i GitHub sayfasındaki güncel kurulum komutuyla yükledikten sonra:

nvm install --lts
nvm alias default "lts/*"
node -v

Bu yöntemde Node.js’in yolu kullanıcıya özgüdür; systemd servisi yazarken which node çıktısındaki tam yolu kullanın.

Uygulama hangi kullanıcıyla ve nasıl hazırlanmalı?

Uygulamayı root ile değil, yalnızca bu iş için açtığınız ayrı bir kullanıcıyla çalıştırın; bir açık istismar edilse bile saldırganın erişimi o kullanıcının dosyalarıyla sınırlı kalır.

sudo adduser deploy
sudo su - deploy
git clone [email protected]:kullanici/api.git ~/api
cd ~/api
npm ci --omit=dev

npm ci, package-lock.json dosyasındaki sürümleri birebir kurar; --omit=dev geliştirme bağımlılıklarını dışarıda bırakır. TypeScript ya da Next.js gibi derleme gerektiren projelerde önce bayraksız npm ci ile tüm paketleri kurup npm run build çalıştırın.

Uygulama yalnızca yerel adresi dinlemelidir; Express’te bu app.listen(process.env.PORT || 3000, "127.0.0.1") biçimindedir. Veritabanı parolası ve API anahtarları gibi gizli bilgileri koda değil, proje klasöründeki .env dosyasına yazın; dosyayı chmod 600 .env ile yalnızca sahibine açın ve .gitignore listesine ekleyin. Güncel LTS sürümlerinde node --env-file=.env app.js parametresi bu dosyayı ek paket olmadan okur.

PM2 ile uygulama nasıl çalıştırılır ve açılışta başlatılır?

PM2, Node.js süreçlerini arka planda çalıştıran, çöktüğünde yeniden başlatan ve loglarını toplayan bir süreç yöneticisidir. NodeSource kurulumunda PM2’yi sudo yetkili yönetici hesabınızla genel paket olarak kurun (nvm kullanıyorsanız uygulama kullanıcısıyla, sudo olmadan); uygulamayı ise deploy kullanıcısıyla başlatın:

sudo npm install -g pm2          # yönetici hesabıyla
pm2 start app.js --name api      # deploy kullanıcısıyla
pm2 status
pm2 logs api

Ayarları proje kökündeki ecosystem.config.js dosyasında tutmak, dağıtımları tekrarlanabilir kılar:

module.exports = {
  apps: [{
    name: "api",
    script: "./app.js",
    instances: 2,
    exec_mode: "cluster",
    env: { NODE_ENV: "production", PORT: 3000 }
  }]
};

pm2 start ecosystem.config.js ile başlatın. instances değerini çekirdek sayısını aşmayacak şekilde seçin; LIONFIN VPS’inizi büyüttüğünüzde bu sayıyı da artırabilirsiniz. Açılışta otomatik başlatma için:

pm2 startup systemd
pm2 save

İlk komut sudo env PATH=... ile başlayan bir satır yazdırır; o satırı kopyalayıp sudo yetkili yönetici hesabınızla çalıştırın. pm2 save o anki süreç listesini kaydeder, açılışta bu liste geri yüklenir. Kod güncellemesinden sonra pm2 reload api kullanın; küme (cluster) kipinde süreçleri tek tek yenileyerek kesintisiz geçiş sağlar. Logların diski doldurmaması için pm2 install pm2-logrotate modülünü ekleyin.

PM2 yerine systemd servisi nasıl yazılır?

Ek araç kurmak istemiyorsanız uygulamayı doğrudan systemd servisi olarak çalıştırın; çökme sonrası yeniden başlatmayı ve açılışta başlatmayı systemd üstlenir. /etc/systemd/system/api.service dosyasını oluşturun:

[Unit]
Description=Node.js API
After=network.target

[Service]
Type=simple
User=deploy
WorkingDirectory=/home/deploy/api
Environment=NODE_ENV=production
EnvironmentFile=/home/deploy/api/.env
ExecStart=/usr/bin/node app.js
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now api
sudo journalctl -u api -f

PM2; küme kipi, kesintisiz reload ve pm2 monit gibi hazır izleme araçları sunar. systemd ise işletim sisteminin parçasıdır, ek bağımlılık getirmez ve loglar diğer servislerle birlikte journalctl altında durur. Tek süreçli küçük servislerde systemd, çok çekirdeğe yük dağıtmak isteyen uygulamalarda PM2 daha pratiktir.

Nginx reverse proxy nasıl yapılandırılır?

Nginx, alan adına gelen istekleri uygulamaya iletir ve ziyaretçinin gerçek bilgilerini başlıklarla aktarır. /etc/nginx/sites-available/api.ornek.com dosyası:

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

server {
    listen 80;
    listen [::]:80;
    server_name api.ornek.com;

    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_http_version 1.1 ile Upgrade ve Connection başlıkları, Socket.IO gibi WebSocket bağlantılarının çalışması için gereklidir. Express kullanıyorsanız app.set("trust proxy", 1) ayarıyla uygulamanın X-Forwarded-* başlıklarını dikkate almasını sağlayın; aksi hâlde tüm ziyaretçiler 127.0.0.1 olarak görünür. Siteyi etkinleştirip HTTPS ekleyin:

sudo ln -s /etc/nginx/sites-available/api.ornek.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d api.ornek.com

Certbot kurulumu ve yenileme kontrolü VPS WordPress kurulumu rehberindeki SSL bölümüyle aynıdır; yönlendirmenin tek adımda çalıştığını HTTP → HTTPS yönlendirme rehberindeki curl testleriyle doğrulayın.

Güvenlik ve güncellemeler nasıl yönetilir?

Yayındaki bir Node.js uygulamasında güvenlik, dışarıya açık yüzeyi küçük tutmak ve güncellemeleri düzenli yapmakla başlar:

• Portlar: Uygulama portunu (3000) güvenlik duvarında açmayın; dışarıda yalnızca 22, 80 ve 443 kalsın. Kurallar için UFW firewall kurulumu rehberine bakın.
• Bağımlılıklar: npm audit çıktısını düzenli inceleyin, Node.js’i LTS dalı içinde güncel tutun.
• Gizli bilgiler: .env dosyasını depoya göndermeyin; sızdığından şüphelendiğiniz anahtarları hemen yenileyin.
• Bellek: Sızıntı yapan bir süreç tüm sunucuyu yavaşlatabilir; PM2’de max_memory_restart ile üst sınır tanımlayın.

Tipik bir güncelleme döngüsü:

cd ~/api
git pull
npm ci --omit=dev
pm2 reload api

Uygulamayı konteyner olarak paketlemeyi tercih ederseniz aynı Nginx yapılandırması Docker kurulumu ile çalıştırılan bir konteynerin önünde de kullanılır. İşlemci yoğun iş yüklerinde ayrılmış çekirdekli bir VDS sunucu, kurumsal doğrulama isteyen API’lerde OV ya da EV SSL sertifikası değerlendirilebilir.