Node.js PM2 ile Production Kurulumu: Cluster, Log ve Deploy Rehberi

Node.js uygulamanız geliştirme ortamında node app.js ile çalışır; ancak üretim ortamında tek bir process çökerse tüm servis durur, loglar kaybolur ve CPU çekirdeklerinin çoğu boşta kalır. PM2, Node.js uygulamalarını üretimde yönetmek için standart haline gelmiş bir process manager'dır. Bu rehberde PM2'nin cluster mode, log yönetimi, zero-downtime deploy ve Nginx entegrasyonunu somut örneklerle ele alıyoruz.

PM2 Nedir ve Neden Gerekli?

Node.js tek thread üzerinde çalışır. Sunucunuzda 4 CPU çekirdeği varsa, varsayılan olarak yalnızca birini kullanır. Process çökerse yeniden başlatacak bir mekanizma yoktur. PM2 bu sorunları çözer: process izleme, otomatik restart, cluster mode ile çoklu çekirdek kullanımı ve merkezi log yönetimi sağlar. PM2 resmi dokümantasyonuna göre, dünya genelinde milyonlarca üretim sunucusunda aktif olarak kullanılmaktadır.

Kurulum ve Temel Komutlar

# Global kurulum
npm install -g pm2

# Uygulamayi baslat
pm2 start app.js --name "my-api"

# Durum kontrolu
pm2 status

# Loglari izle
pm2 logs my-api --lines 50

# Yeniden baslat
pm2 restart my-api

# Durdur ve sil
pm2 stop my-api
pm2 delete my-api

Ecosystem Dosyası ile Yapılandırma

Komut satırında her seferinde parametreleri tekrarlamak yerine, tüm yapılandırmayı tek bir dosyada tanımlayabilirsiniz. ecosystem.config.js dosyası PM2'nin kalbidir - uygulama adı, cluster sayısı, environment değişkenleri ve log ayarlarını merkezi olarak yönetir.

module.exports = {
  apps: [{
    name: 'my-api',
    script: './dist/server.js',
    instances: 'max',           // CPU cekirdek sayisi kadar
    exec_mode: 'cluster',       // Cluster mode
    max_memory_restart: '512M', // Bellek limiti
    watch: false,               // Production'da kapali olmali
    max_restarts: 10,           // 15 dk icinde max restart
    min_uptime: '10s',          // Stabil sayilma suresi

    // Log ayarlari
    error_file: './logs/error.log',
    out_file: './logs/output.log',
    log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
    merge_logs: true,

    // Environment degiskenleri
    env_production: {
      NODE_ENV: 'production',
      PORT: 3000
    }
  }]
};

# Ecosystem dosyasi ile baslat
pm2 start ecosystem.config.js --env production

# Sunucu yeniden basladiginda otomatik calistir
pm2 startup
pm2 save

Cluster Mode ile Çoklu Çekirdek Kullanımı

Node.js tek thread çalıştığı için varsayılan olarak sunucunuzun yalnızca bir CPU çekirdeğini kullanır. PM2'nin cluster mode'u, Node.js'in yerleşik cluster modülünü kullanarak her çekirdekte ayrı bir worker process başlatır. 4 çekirdekli bir sunucuda 4 worker çalıştırdığınızda, teorik olarak 4 kat daha fazla istek işleyebilirsiniz.

Log Yönetimi ve Rotasyon

Üretim ortamında loglar hızla büyür. PM2'nin yerleşik log yönetimi temel düzeydedir; pm2-logrotate modülü ile log dosyalarını otomatik olarak döndürebilir ve disk dolmasını önleyebilirsiniz.

# Log rotasyon modulunu kur
pm2 install pm2-logrotate

# Ayarlari yapilandir
pm2 set pm2-logrotate:max_size 50M      # Dosya basina max boyut
pm2 set pm2-logrotate:retain 7           # 7 dosya tut
pm2 set pm2-logrotate:compress true       # Eski loglari sikistir
pm2 set pm2-logrotate:dateFormat YYYY-MM-DD_HH-mm-ss
pm2 set pm2-logrotate:workerInterval 30   # 30 sn'de bir kontrol

Yapılandırılmış (structured) loglama için uygulamanızda Winston veya Pino gibi bir log kütüphanesi kullanmanız önerilir. JSON formatında loglar, ELK Stack veya Grafana Loki gibi merkezi log sistemleriyle kolayca entegre olur.

Zero-Downtime Deployment

Geleneksel pm2 restart komutu tüm worker'ları aynı anda durdurur ve yeniden başlatır - bu sürede gelen istekler kaybolur. pm2 reload ise graceful reload yapar: worker'ları sırayla yeniden başlatır, her zaman en az bir worker aktif kalır.

#!/bin/bash
# Zero-downtime deployment script

git pull origin main
npm ci --production
npm run build

# Graceful reload - sifir kesinti
pm2 reload ecosystem.config.js --env production

echo "Deploy tamamlandi: $(date)"

Graceful shutdown için uygulamanızda SIGINT sinyalini yakalayıp açık bağlantıları kapatmanız gerekir:

const server = app.listen(PORT);

process.on('SIGINT', () => {
  console.log('Graceful shutdown basladi...');
  server.close(() => {
    // DB baglantilari kapat
    mongoose.connection.close();
    process.exit(0);
  });

  // 10 saniye icinde kapanmazsa zorla kapat
  setTimeout(() => process.exit(1), 10000);
});

Nginx Reverse Proxy Entegrasyonu

Node.js uygulamasını doğrudan 80/443 portunda çalıştırmak güvenlik ve performans açısından önerilmez. Nginx'i reverse proxy olarak kullanarak SSL termination, statik dosya sunumu, rate limiting ve gzip sıkıştırma gibi işlemleri Node.js'ten ayırabilirsiniz.

upstream nodejs_backend {
    server 127.0.0.1:3000;
    keepalive 64;
}

server {
    listen 443 ssl http2;
    server_name api.example.com;

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

    # Statik dosyalar Nginx'ten sunulur
    location /static/ {
        alias /var/www/my-api/public/;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    location / {
        proxy_pass http://nodejs_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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_cache_bypass $http_upgrade;
    }
}

Nginx reverse proxy hakkında daha detaylı bilgi için Nginx Reverse Proxy rehberimizi inceleyebilirsiniz.

İzleme ve Metrikler

PM2, yerleşik bir monitoring dashboard'u sunar. pm2 monit komutu ile CPU, bellek, event loop lag ve aktif request sayısını terminal üzerinden izleyebilirsiniz.

# Canli izleme dashboard'u
pm2 monit

# Detayli bilgi
pm2 show my-api

# JSON formatinda metrikler (otomasyon icin)
pm2 jlist

• CPU Kullanımı Sürekli %80+ ise worker sayısını artırın veya sunucu kaynaklarını yükseltin.
• Bellek (Heap) Sürekli artan bellek kullanımı memory leak işaretidir. max_memory_restart ile otomatik restart ayarlayın.
• Restart Sayısı Sık restart, uygulamada çözülmemiş bir hata olduğunu gösterir. pm2 logs --err ile hata loglarını inceleyin.

Daha kapsamlı izleme için Prometheus + Grafana izleme rehberimize göz atabilirsiniz.

Sunucu Boyutlandırma

Node.js uygulamanızın kaynak ihtiyacı, istek hacmi ve işlem türüne göre değişir. I/O yoğun uygulamalar (API gateway, proxy) daha az CPU gerektirirken, CPU yoğun işlemler (resim işleme, şifreleme) daha fazla çekirdek ister.

Node.js hosting altyapınız için Hosted Cloud bulut sunucularını değerlendirebilirsiniz.

Sıkça Sorulan Sorular

Sonuç

Node.js uygulamanızı üretim ortamında PM2 ile yönetmek, cluster mode ile tüm CPU çekirdeklerini kullanmanızı, otomatik restart ile kesintisiz çalışmayı ve merkezi log yönetimi ile sorun tespitini kolaylaştırır. Ecosystem dosyası ile yapılandırmanızı kodlayın, Nginx reverse proxy ile güvenliği artırın ve pm2 reload ile zero-downtime deploy yapın.