PM2 ile Node.js Süreç Yönetimi

Node.js ile yazdığınız uygulamayı geliştirme makinenizde node app.js diyerek çalıştırmak kolaydır, ama aynı komutu bir üretim sunucusunda kullandığınızda işler hızla dağılır. Terminali kapattığınız an süreç ölür, uygulama beklenmedik bir hatayla çökerse kimse ayağa kaldırmaz, sunucu yeniden başladığında hiçbir şey açılmaz ve elinizde ne kadar bellek tükettiğini, kaç kez çöktüğünü gösteren tek bir kayıt bile olmaz. Bu, canlı bir servisi ayakta tutmanın kabul edilebilir bir yolu değildir. Üretimde bir Node uygulaması, siz uyurken bile kendi kendini toparlayabilmeli, yükü çekirdeklere dağıtabilmeli ve olan biteni kayıt altına almalıdır.

İşte PM2 (Process Manager 2) tam bu boşluğu doldurur. PM2, Node.js süreçlerini arka planda daemon olarak çalıştıran, çöktüklerinde otomatik yeniden başlatan, birden fazla çekirdeğe yayabilen (cluster modu), logları toplayan ve sunucu açılışında uygulamalarınızı geri getiren olgun bir süreç yöneticisidir. Bu rehberde PM2'yi sıfırdan kurup temel komutlarından ecosystem yapılandırma dosyasına, cluster modundan sıfır kesintili yeniden yüklemeye, log yönetiminden boot'ta otomatik başlatmaya kadar üretimde ihtiyacınız olacak her şeyi kıdemli bir sistem yöneticisinin bakış açısıyla ele alacağız. Sonunda önüne Nginx reverse proxy koymayı ve systemd alternatifini de kısaca değerlendireceğiz.

PM2 Kurulumu ve İlk Çalıştırma#

PM2 bir npm paketidir ve global olarak kurulur. Öncesinde sunucunuzda Node.js'in kurulu olduğundan emin olun; hâlâ kurmadıysanız bir sürüm yöneticisi (nvm) üzerinden LTS sürümü tercih etmenizi öneririm çünkü PM2'nin startup betiği Node'un tam yolunu kaydeder.

# PM2'yi global kur
npm install -g pm2

# Sürümü doğrula
pm2 --version

# Bir uygulamayı başlat
pm2 start app.js --name api

--name bayrağı önemlidir; uygulamalarınızı 0, 1 gibi indeksler yerine anlamlı isimlerle yönetmenizi sağlar. Uygulamanız bir başlangıç betiği üzerinden çalışıyorsa (npm start gibi), doğrudan onu da tetikleyebilirsiniz:

pm2 start npm --name api -- run start

Buradaki -- ayracından sonrası npm'e geçen argümanlardır. TypeScript ile yazılmış ve dist/ altına derlenen bir projede genellikle derlenmiş çıktıyı çalıştırmak en sağlıklısıdır (pm2 start dist/main.js), çünkü üretimde ts-node gibi bir katman fazladan bellek ve gecikme demektir.

Temel Komutlar: list, logs, monit ve restart#

PM2'nin gücü, çalışan süreçleri tek bir yerden görüp yönetebilmenizde. Günlük hayatta en çok kullanacağınız komutlar şunlardır:

pm2 list          # Tüm süreçleri tablo halinde göster
pm2 logs          # Tüm logları canlı akış olarak izle
pm2 logs api      # Sadece "api" uygulamasının logları
pm2 monit         # Terminal içi canlı CPU/RAM izleme paneli
pm2 restart api   # Uygulamayı yeniden başlat
pm2 stop api      # Durdur (kayıt listede kalır)
pm2 delete api    # PM2 listesinden tamamen kaldır
pm2 describe api  # Bir uygulamanın tüm ayrıntıları

pm2 list çıktısı size her uygulamanın durumunu (online, stopped, errored), yeniden başlatma sayısını (↺), bellek ve CPU kullanımını gösterir. Yeniden başlatma sayısının sürekli artıyor olması, uygulamanın bir döngü içinde çökup çökup ayağa kalktığının en net işaretidir; böyle bir durumda ilk bakılacak yer loglardır.

Aşağıdaki tablo en sık başvurulan komutları özetler:

Ecosystem Dosyası ile Yapılandırma#

Komut satırından bayraklarla uğraşmak birkaç uygulama sonrası hızla yorucu hale gelir. PM2 bunun yerine tüm yapılandırmanızı tek bir dosyada tutmanıza izin verir: ecosystem dosyası. Bu dosyayı versiyon kontrolüne ekleyip sunucularınız arasında tutarlılık sağlayabilirsiniz.

Bir şablon oluşturmak için:

pm2 ecosystem

Bu, ecosystem.config.js adında bir dosya üretir. İçeriğini ihtiyacınıza göre düzenleyin:

module.exports = {
  apps: [
    {
      name: "api",
      script: "dist/main.js",
      instances: "max",
      exec_mode: "cluster",
      max_memory_restart: "500M",
      env: {
        NODE_ENV: "development",
        PORT: 3000
      },
      env_production: {
        NODE_ENV: "production",
        PORT: 8080
      },
      error_file: "/var/log/pm2/api-error.log",
      out_file: "/var/log/pm2/api-out.log",
      time: true
    }
  ]
};

Buradaki max_memory_restart üretimde altın değerindedir: uygulama bellek sızıntısı nedeniyle 500 MB'ı aşarsa PM2 onu otomatik yeniden başlatır, böylece sunucu OOM (bellek yetersiz) durumuna düşmez. env_production bloğu ise ortama özel değişkenleri ayırır. Dosyayı üretim ortamıyla başlatmak için:

pm2 start ecosystem.config.js --env production

Ecosystem dosyasında birden çok uygulamayı apps dizisine ekleyerek (bir API, bir worker, bir zamanlanmış görev süreci gibi) hepsini tek komutla yönetebilirsiniz. Bu yaklaşım, sunucu yapılandırmanızı belgelenebilir ve tekrar üretilebilir kılar.

Cluster Modu ve Sıfır Kesintili Yeniden Yükleme#

Node.js tek iş parçacıklıdır; varsayılan haliyle sunucunuzda 8 çekirdek olsa bile uygulamanız yalnızca birini kullanır. PM2'nin cluster modu, Node'un yerleşik cluster modülünü sizin için yöneterek uygulamanızın birden fazla kopyasını (worker) çalıştırır ve gelen bağlantıları bunlar arasında dağıtır. Kod tarafında hiçbir değişiklik yapmanız gerekmez.

# Çekirdek sayısı kadar worker başlat
pm2 start app.js -i max --name api

# Ya da net bir sayı belirt
pm2 start app.js -i 4 --name api

-i max PM2'ye mevcut CPU çekirdeği sayısı kadar süreç aç demektir. Bu, hem yatay ölçekleme sağlar hem de bir worker çöktüğünde diğerleri hizmete devam ettiği için dayanıklılık kazandırır.

Cluster modunun en büyük avantajı reload komutuyla ortaya çıkar. Yeni bir sürüm yayınladığınızda pm2 restart tüm süreçleri aynı anda öldürür ve o kısa anda istekler düşer. pm2 reload ise worker'ları teker teker, biri hazır olduğunda diğerini kapatarak yeniler; bu sayede kullanıcı hiçbir kesinti hissetmez.

# Sıfır kesintili yeniden yükleme
pm2 reload api

Bir noktaya dikkat: cluster modu yalnızca durumsuz (stateless) uygulamalarda sorunsuz çalışır. Bellekte oturum tutuyor ya da WebSocket bağlantılarını süreç belleğinde saklıyorsanız, worker'lar arasında bu durum paylaşılmaz. Böyle durumlarda oturumu Redis gibi harici bir depoya taşımanız gerekir. Yükün altyapı seviyesinde dağıtımı için birden fazla makineye ihtiyaç duyduğunuzda ise VDS sunucu çözümlerimize veya ölçeklenebilir sanal sunucu seçeneklerimize bakabilirsiniz.

Log Yönetimi ve İzleme#

PM2, her uygulamanın standart çıktısını (stdout) ve hata çıktısını (stderr) ayrı dosyalara yazar. Varsayılan konum ~/.pm2/logs/ altındadır, ama ecosystem dosyasında out_file ve error_file ile bunu istediğiniz yere yönlendirebilirsiniz.

# Son 200 satırı göster ve canlı takip et
pm2 logs api --lines 200

# Log dosyalarını temizle (disk şişince)
pm2 flush

Zamanla log dosyaları büyür ve diski doldurabilir. Bunu önlemek için pm2-logrotate modülünü kurmanızı şiddetle öneririm; bu modül logları belirli bir boyuta ulaştığında döndürür (rotate) ve eski dosyaları sıkıştırır.

# Log döndürme modülünü kur
pm2 install pm2-logrotate

# Maksimum dosya boyutunu ve saklanacak dosya sayısını ayarla
pm2 set pm2-logrotate:max_size 10M
pm2 set pm2-logrotate:retain 7

Anlık kaynak kullanımını izlemek için pm2 monit size terminal içi bir pano sunar; her sürecin CPU ve bellek grafiğini canlı görürsünüz. Daha uzun vadeli, disk temelli izleme ve alarm için ise sunucu tarafında ayrı bir metrik toplama katmanı düşünebilirsiniz. Node uygulamanızın önünde çalışan servislerin erişilebilirliğini ölçmek isterseniz araç setimizdeki ücretsiz çevrimiçi araçlara göz atabilirsiniz.

Sunucu Açılışında Otomatik Başlatma (startup + save)#

Buraya kadar yaptıklarınız tek bir sorunu çözmez: sunucu yeniden başlarsa (güncelleme, bakım ya da beklenmedik kesinti) PM2 ve altındaki tüm uygulamalar kaybolur. Üretim için bu kabul edilemez. PM2 bunu iki adımlı bir mekanizmayla çözer.

Önce PM2'ye, işletim sisteminizin başlatma sistemine (systemd) kendini kaydettiren betiği ürettirin:

pm2 startup

Bu komut ekrana sudo ile çalıştırmanız gereken bir satır basar; onu aynen kopyalayıp çalıştırın. Bu, boot sırasında PM2'nin ayağa kalkmasını sağlar. Ardından o an çalışan süreç listenizi kalıcı hale getirmeniz gerekir:

# Mevcut süreç listesini diske kaydet
pm2 save

pm2 save, çalışan uygulamaların bir anlık görüntüsünü ~/.pm2/dump.pm2 dosyasına yazar. Boot sırasında PM2 bu dosyayı okuyup tüm uygulamaları geri getirir. Kritik nokta şudur: uygulama listenizde her değişiklik yaptığınızda (yeni servis ekleme, silme) mutlaka tekrar pm2 save çalıştırın; yoksa bir sonraki yeniden başlatmada değişiklik kaybolur.

Kurulumu test etmek için sunucuyu bilinçli olarak yeniden başlatıp pm2 list ile uygulamaların geri geldiğini doğrulayın:

sudo reboot
# Yeniden bağlandıktan sonra
pm2 list

Bu üç komut — startup, save ve düzenli test — PM2 kurulumunuzu gerçekten üretime hazır hale getiren şeydir. Bu tür sistem seviyesi yapılandırmaları sizin yerinize kurmamızı isterseniz sunucu yönetimi hizmetimiz devrede.

Nginx Reverse Proxy ile Önüne Geçme#

Node uygulamanızı doğrudan 80 veya 443 portunda çalıştırmak birçok açıdan sorunludur: SSL sonlandırma, statik dosya sunumu, sıkıştırma ve güvenlik başlıkları gibi işler Node'un asıl işi değildir. Doğru mimari, PM2'nin uygulamanızı yüksek bir portta (örneğin 8080) çalıştırması ve önüne bir Nginx reverse proxy koymanızdır.

Basit bir Nginx yapılandırması şöyle görünür:

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

    location / {
        proxy_pass http://127.0.0.1:8080;
        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;
    }
}

Buradaki Upgrade ve Connection başlıkları WebSocket bağlantılarının proxy üzerinden geçmesi için gereklidir; X-Forwarded-* başlıkları ise uygulamanızın gerçek istemci IP'sini ve protokolünü doğru görmesini sağlar. Nginx kurulumunun tüm ayrıntılarını Ubuntu üzerinde Nginx kurulumu rehberimizde adım adım bulabilirsiniz.

HTTPS için bu yapıya bir SSL sertifikası eklemeniz gerekir; ücretsiz Let's Encrypt yerine kurumsal projelerde daha güçlü doğrulama isterseniz SSL sertifikası çözümlerimizi inceleyebilirsiniz. Uygulamanızı bir saldırı yüzeyine karşı korumak içinse önüne web uygulama güvenlik duvarı (WAF) yerleştirebilirsiniz.

PM2 mi, systemd mi?#

PM2 harika bir araçtır ama tek seçenek değildir. Linux'un yerleşik başlatma sistemi systemd de bir Node uygulamasını daemon olarak çalıştırıp çöktüğünde yeniden başlatabilir. Peki hangisini seçmelisiniz?

Aşağıdaki tablo iki yaklaşımı karşılaştırır:

Pratik tavsiyem şudur: geliştirme ekibinin süreçleri kolayca yönetmesi, cluster modu ve sıfır kesintili yayın önemliyse PM2 kullanın. Minimalist bir sunucu istiyor, ek bir Node bağımlılığı taşımak istemiyor ve tek örnekli bir servis çalıştırıyorsanız systemd yeterlidir. İlginç olan, pm2 startup'ın da arka planda zaten bir systemd unit'i oluşturmasıdır — yani ikisi rakip değil, katmanlıdır. systemd'yi doğrudan kullanmak isterseniz konuyu ele aldığımız systemd servis yönetimi rehberine bakın.

Sıkça Sorulan Sorular#

PM2 uygulamamı neden sürekli yeniden başlatıyor?#

Uygulamanız başlar başlamaz çöküyor demektir ve PM2 onu ayakta tutmaya çalışırken bir döngüye girer. pm2 logs api --lines 100 ile son hatalara bakın; genellikle eksik bir ortam değişkeni, kullanımdaki bir port ya da veritabanına bağlanamama gibi bir başlangıç hatası görürsünüz. Kök nedeni çözmeden yeniden başlatma sayısı pm2 list çıktısında sürekli artmaya devam eder.

Cluster modu her uygulama için uygun mu?#

Hayır, cluster modu yalnızca durumsuz (stateless) uygulamalarda sorunsuz çalışır. Uygulamanız oturumu, WebSocket bağlantısını veya önbelleği süreç belleğinde tutuyorsa, worker'lar bu durumu paylaşamaz ve tutarsızlık yaşarsınız. Bu tür durumlarda paylaşılan durumu Redis gibi harici bir depoya taşımanız, ardından cluster moduna geçmeniz gerekir.

pm2 save ile pm2 startup arasındaki fark nedir?#

pm2 startup işletim sisteminin boot sürecine PM2'yi kaydeder, yani sunucu açıldığında PM2'nin kendisinin ayağa kalkmasını sağlar. pm2 save ise o an çalışan uygulama listesini diske yazar, böylece PM2 açıldığında hangi uygulamaları geri getireceğini bilir. İkisi birlikte çalışır; sadece birini yaparsanız ya PM2 açılır ama uygulama listesi boş olur ya da liste kaydedilir ama PM2 hiç başlamaz.

PM2 loglarım diski dolduruyor, ne yapmalıyım?#

Bu çok yaygın bir sorundur ve çözümü pm2-logrotate modülüdür. pm2 install pm2-logrotate ile kurup max_size ve retain değerlerini ayarladığınızda loglar belirli bir boyuta ulaşınca döndürülür ve eski dosyalar sıkıştırılıp otomatik silinir. Acil durumda pm2 flush komutu tüm mevcut log dosyalarını anında temizler, ama kalıcı çözüm log döndürmeyi kurmaktır.

PM2'yi Nginx olmadan doğrudan 443 portunda çalıştırabilir miyim?#

Teknik olarak mümkündür ama önerilmez. SSL sonlandırma, statik dosya sunumu, sıkıştırma, hız sınırlama ve güvenlik başlıkları Node'un asıl işi değildir ve bunları uygulama kodunda çözmek hem performans hem bakım açısından maliyetlidir. Doğru mimari, uygulamayı yüksek bir portta çalıştırıp önüne bir Nginx reverse proxy koymak, SSL ve statik içerik gibi işleri Nginx'e bırakmaktır.

PM2 ücretsiz mi, yoksa ödeme gerektiren bir kısmı var mı?#

PM2'nin çekirdek süreç yöneticisi tamamen ücretsiz ve açık kaynaktır; bu rehberde anlattığımız her şey (cluster modu, ecosystem, startup, loglar) ücretsiz sürümde vardır. PM2 Plus adında, merkezi bir panelden izleme sunan ücretli bir bulut hizmeti de mevcuttur, ancak tek sunucuda çalışan tipik bir üretim kurulumu için ücretsiz PM2 fazlasıyla yeterlidir.

Kapanış#

PM2, bir Node.js uygulamasını "çalışıyor" durumundan "üretime hazır" durumuna taşıyan köprüdür. Doğru kurulduğunda uygulamanız arka planda kesintisiz çalışır, çöktüğünde kendini toparlar, çekirdeklerin tamamını kullanır, sürüm geçişlerini kullanıcıyı rahatsız etmeden yapar ve sunucu yeniden başladığında hiçbir müdahaleye gerek kalmadan ayağa kalkar. Bu rehberdeki adımları — startup ve save ile boot kalıcılığı, ecosystem dosyasıyla düzen, cluster moduyla ölçek ve Nginx ile sağlam bir ön kapı — bir kez doğru kurduğunuzda uygulamanız gecenin ortasında bile kendi başının çaresine bakar.

Node.js uygulamanızı üzerine kuracağınız sağlam bir altyapı arıyorsanız Clou.TR olarak yanınızdayız. Tam kök erişimi ve yeterli kaynakla gelen VDS sunucu ve sanal sunucu planlarımızla PM2 kurulumunuzu özgürce yapabilir, kurulumu bizden isterseniz sunucu yönetimi hizmetimizden faydalanabilir, uygulamanızı SSL ve WAF ile güvence altına alabilirsiniz. Tüm sunucu ve hosting seçeneklerimizi sunucu sayfamızda inceleyerek projeniz için en uygun olanı seçebilirsiniz.