PM2 — zarządzanie procesami Node.js na VPS

Opublikowano: 9 kwietnia 2026 · Kategoria: VPS / Node.js

Uruchomiłeś aplikację Node.js komendą node app.js i zamknąłeś terminal — serwer padł. Crash aplikacji? Restart VPS? Znów trzeba logować się i uruchamiać ręcznie. PM2 rozwiązuje wszystkie te problemy: działa jako dæmon, restartuje procesy po awarii, startuje automatycznie po restarcie serwera i umożliwia uruchamianie wielu instancji (cluster mode) dla maksymalnego wykorzystania CPU.

Instalacja PM2

PM2 instalujesz globalnie przez npm. Upewnij się, że masz Node.js i npm na VPS (zalecane: Node.js 18 LTS lub nowszy):

# Instalacja PM2 globalnie
npm install -g pm2

# Sprawdzenie wersji
pm2 --version

# Opcjonalnie: aktualizacja PM2
npm install -g pm2@latest
pm2 update

Podstawowe komendy

Najważniejsze komendy PM2, których używasz codziennie:

# Uruchomienie aplikacji
pm2 start app.js --name "moja-aplikacja"

# Lista wszystkich procesów
pm2 list
pm2 ls       # skrót

# Szczegółowe info o procesie
pm2 show moja-aplikacja

# Restart / stop / usunięcie
pm2 restart moja-aplikacja
pm2 stop moja-aplikacja
pm2 delete moja-aplikacja

# Restart wszystkich procesów
pm2 restart all

# Logi na żywo
pm2 logs
pm2 logs moja-aplikacja          # tylko jeden proces
pm2 logs moja-aplikacja --lines 100  # ostatnie 100 linii

ecosystem.config.js — konfiguracja jako kod

Zamiast długich komend startowych, definiuj aplikacje w pliku konfiguracyjnym ecosystem.config.js (lub .cjs). Plik ten możesz dodać do repozytorium — konfiguracja jako kod:

// ecosystem.config.js
module.exports = {
  apps: [
    {
      name: 'moja-aplikacja',
      script: 'dist/server.js',        // główny plik po build
      instances: 'max',                // cluster mode: tyle ile rdzeni CPU
      exec_mode: 'cluster',
      watch: false,                    // NIE włączaj na produkcji
      max_memory_restart: '500M',      // restart gdy RAM > 500 MB

      // Zmienne środowiskowe
      env: {
        NODE_ENV: 'development',
        PORT: 3000,
      },
      env_production: {
        NODE_ENV: 'production',
        PORT: 3000,
        DATABASE_URL: 'postgres://user:pass@localhost/db',
      },

      // Logi
      out_file: '/var/log/pm2/app-out.log',
      error_file: '/var/log/pm2/app-err.log',
      merge_logs: true,
      log_date_format: 'YYYY-MM-DD HH:mm:ss',
    },
  ],
};

# Uruchomienie z ecosystem
pm2 start ecosystem.config.js

# Uruchomienie w trybie produkcyjnym (env_production)
pm2 start ecosystem.config.js --env production

# Reload (bez downtime, graceful restart)
pm2 reload ecosystem.config.js --env production

Cluster mode — wiele rdzeni CPU

Node.js jest jednowątkowy — domyślnie utilizuje tylko jeden rdzeń procesora, nawet na 8-rdzeniowym VPS. Cluster mode uruchamia N kopii aplikacji i rozkłada ruch między nimi:

# Uruchom 4 instancje (ręcznie)
pm2 start app.js -i 4

# Automatycznie: tyle instancji ile rdzeni CPU
pm2 start app.js -i max

# W ecosystem.config.js (zalecane):
# instances: 'max'  lub  instances: 4
# exec_mode: 'cluster'

# Sprawdzenie ile workers działa
pm2 list

Ważne: cluster mode działa bezproblemowo dla aplikacji bezstanowych (stateless). Jeśli Twoja aplikacja trzyma stan w pamięci procesu (np. sesje w Map), różne requesty mogą trafić do różnych instancji — przenieś stan do Redis lub bazy danych.

pm2 startup — autostart po restarcie VPS

Bez konfiguracji autostartu po restarcie serwera procesy PM2 nie wznowią się. Dwie komendy załatwiają sprawę na stałe:

# Krok 1: wygeneruj i uruchom skrypt systemd
pm2 startup
# PM2 wyświetli polecenie do skopiowania, np.:
# sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u ubuntu --hp /home/ubuntu
# Skopiuj i uruchom to polecenie!

# Krok 2: zapisz aktualną listę procesów
pm2 save

# Opcjonalnie: wyłączenie autostartu
pm2 unstartup systemd

Po restarcie VPS możesz weryfikować: pm2 list — procesy powinny być w stanie online.

Monitoring — pm2 monit i pm2 plus

# Terminal dashboard (CPU, RAM, logi na żywo)
pm2 monit

# Metryki JSON (przydatne do skryptów)
pm2 prettylist
pm2 show moja-aplikacja

pm2 monit to wbudowany dashboard terminalowy — pokazuje zużycie CPU i RAM każdego procesu w czasie rzeczywistym, listę procesów i strumień logów. Wystarczy do codziennego monitorowania.

Rotacja logów — pm2-logrotate

Domyślnie PM2 nie rotuje logów — plik rośnie bez ograniczeń. Moduł pm2-logrotate dodaje rotację automatycznie:

# Instalacja modułu
pm2 install pm2-logrotate

# Konfiguracja
pm2 set pm2-logrotate:max_size 10M       # rotuj gdy plik > 10 MB
pm2 set pm2-logrotate:retain 7           # przechowuj 7 plików
pm2 set pm2-logrotate:compress true      # kompresuj stare logi (gzip)
pm2 set pm2-logrotate:rotateInterval '0 0 * * *'  # codziennie o północy

# Sprawdzenie konfiguracji
pm2 conf pm2-logrotate

Zero-downtime deployment

W cluster mode PM2 obsługuje graceful reload: restaruje instancje jedna po drugiej, bez przerwy w ruchu:

# Graceful reload (zero downtime) — cluster mode
pm2 reload moja-aplikacja

# Twardy restart (krótka przerwa)
pm2 restart moja-aplikacja

# Reload z nowym ecosystem
pm2 reload ecosystem.config.js --env production

Tip: W aplikacji Express/Fastify obsługuj sygnał SIGINT i zamykaj serwer gracefully (czekaj na dokończenie aktywnych requestów). PM2 wyśle ten sygnał przed restartem workerów. Bez tego Reload działa, ale aktywne requesty mogą zostać przerwane.

Najczęstsze pytania