PM2 Node.js process manager dashboard with terminal

PM2
Node.js
Deployment
Process Management
VPS

PM2 Node.js Prozessverwaltung – Leitfaden

Ein vollständiger Leitfaden zu PM2 für Node.js-Anwendungen – Starten, Stoppen, Überwachen, Clustering, Log-Management, Ecosystem-Konfigurationsdateien und automatischer Neustart nach Server-Reboots.

3. August 20264 Min. Lesen

PM2 ist der Standard-Prozessmanager für Node.js-Anwendungen in der Produktion. Er hält deine App nach Abstürzen am Laufen, startet sie bei Server-Neustarts neu, bietet integriertes Log-Management und unterstützt Cluster-Modus für Multi-Core-Performance. Dieser Leitfaden behandelt alles, was du für ein Produktions-Setup brauchst.

Installation

PM2 global mit npm installieren:

sudo npm install -g pm2

Installation überprüfen:

pm2 --version

Anwendungen starten

Skript direkt starten

pm2 start app.js --name "meine-app"

npm-Skript starten

pm2 start npm --name "meine-app" -- start

Spezifischen Einstiegspunkt starten

Für Astro (Node-Adapter), Next.js Standalone oder eine benutzerdefinierte Server-Datei:

# Astro (Node-Adapter)
pm2 start dist/server/entry.mjs --name "astro-app"

# Next.js Standalone
pm2 start .next/standalone/server.js --name "next-app"

# Benutzerdefinierter Express-Server
pm2 start server.js --name "api-server"

Umgebungsvariablen beim Start übergeben

pm2 start app.js --name "meine-app" --env production
# oder explizit:
PORT=8080 NODE_ENV=production pm2 start app.js --name "meine-app"

Grundlegende Prozess-Befehle

pm2 list                    # Alle laufenden Prozesse auflisten
pm2 status                  # Wie pm2 list
pm2 show meine-app          # Detaillierte Infos für einen Prozess

pm2 stop meine-app          # Stoppen (bleibt in der Liste)
pm2 start meine-app         # Gestoppten Prozess starten
pm2 restart meine-app       # Neustart (kurze Downtime)
pm2 reload meine-app        # Zero-Downtime-Neustart (Cluster-Modus)
pm2 delete meine-app        # Komplett aus der Liste entfernen

pm2 stop all                # Alle Prozesse stoppen
pm2 restart all             # Alle Prozesse neu starten
pm2 delete all              # Alle Prozesse entfernen

Prozesse können nach Name oder numerischer ID aus pm2 list referenziert werden.

Server-Neustarts überleben

Das ist der wichtigste Schritt für Produktion. Ohne ihn startet deine App nach einem Reboot nicht.

1. Startup-Skript generieren

pm2 startup

PM2 gibt einen auf dein System zugeschnittenen Befehl aus. Kopieren und ausführen – er sieht so aus:

sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u ubuntu --hp /home/ubuntu

2. Aktuelle Prozessliste speichern

pm2 save

Dies speichert die Liste der laufenden Prozesse in ~/.pm2/dump.pm2. Beim Reboot stellt PM2 sie automatisch wieder her.

pm2 save erneut ausführen, wenn ein Prozess hinzugefügt, entfernt oder geändert wird.

3. Startup überprüfen

pm2 ls          # Bestätigen, dass Prozesse aufgelistet sind
sudo systemctl status pm2-$(whoami)

Ecosystem-Konfigurationsdatei

Für mehr als eine einfache Zeile eine Ecosystem-Datei verwenden. Sie hält die gesamte PM2-Konfiguration in der Versionskontrolle.

ecosystem.config.cjs im Projektstamm erstellen:

// ecosystem.config.cjs
module.exports = {
  apps: [
    {
      name: 'meine-app',
      script: 'dist/server/entry.mjs',

      // Anzahl der Instanzen — 'max' nutzt alle CPU-Kerne
      instances: 1,

      // Automatisch bei Absturz neu starten
      autorestart: true,

      // Dateien beobachten und bei Änderungen neu starten (nur in der Entwicklung)
      watch: false,

      // Speicherlimit — neu starten, wenn überschritten
      max_memory_restart: '512M',

      // Umgebungsvariablen pro Modus
      env: {
        NODE_ENV: 'development',
        PORT: 4321,
      },
      env_production: {
        NODE_ENV: 'production',
        PORT: 4321,
      },
    },
  ],
};

Mit der Ecosystem-Datei starten:

# Entwicklungsumgebung
pm2 start ecosystem.config.cjs

# Produktionsumgebung
pm2 start ecosystem.config.cjs --env production

Andere Befehle funktionieren genauso:

pm2 restart ecosystem.config.cjs --env production
pm2 reload ecosystem.config.cjs --env production   # Zero-Downtime
pm2 stop ecosystem.config.cjs
pm2 delete ecosystem.config.cjs

Cluster-Modus

Der Cluster-Modus startet einen Prozess pro CPU-Kern und verteilt eingehende Verbindungen auf diese. Das ist der schnellste Weg, alle Kerne auf einem Multi-Core-VPS ohne Code-Änderungen zu nutzen.

// ecosystem.config.cjs
module.exports = {
  apps: [
    {
      name: 'meine-app',
      script: 'server.js',
      instances: 'max',     // einer pro CPU-Kern
      exec_mode: 'cluster', // für Load Balancing erforderlich
      autorestart: true,
      env_production: {
        NODE_ENV: 'production',
        PORT: 3000,
      },
    },
  ],
};

Im Cluster-Modus pm2 reload statt pm2 restart verwenden, um Zero-Downtime-Updates zu erreichen – PM2 wechselt Worker nacheinander.

Achtung: Der Cluster-Modus erfordert eine zustandslose App. In-Memory-Session-Storage, WebSocket-Verbindungen und alles in globalen Variablen Gespeicherte wird nicht über Worker hinweg geteilt. Redis oder eine Datenbank für geteilten Zustand verwenden.

Log-Management

Logs anzeigen

pm2 logs                       # Alle Logs streamen
pm2 logs meine-app             # Logs einer App streamen
pm2 logs meine-app --lines 100 # Letzte 100 Zeilen anzeigen

Log-Dateispeicherorte

Logs werden in ~/.pm2/logs/ gespeichert:

~/.pm2/logs/meine-app-out.log   # stdout
~/.pm2/logs/meine-app-error.log # stderr

Logs löschen

pm2 flush            # Alle Log-Dateien löschen
pm2 flush meine-app  # Logs einer App löschen

Log-Rotation

PM2 Log-Rotation-Modul installieren, um zu verhindern, dass Logs die Festplatte füllen:

pm2 install pm2-logrotate

Konfigurieren:

pm2 set pm2-logrotate:max_size 50M      # rotieren, wenn Datei 50 MB überschreitet
pm2 set pm2-logrotate:retain 14         # 14 rotierte Dateien behalten
pm2 set pm2-logrotate:compress true     # rotierte Dateien gzippen
pm2 set pm2-logrotate:dateFormat YYYY-MM-DD_HH-mm-ss

Monitoring

Eingebautes Terminal-Dashboard

pm2 monit

Zeigt CPU- und Speichernutzung pro Prozess in Echtzeit.

Prozess-Metriken

pm2 show meine-app

Zeigt Uptime, Neustart-Anzahl, Speicher, CPU, Log-Pfade und mehr.

Web-Dashboard (PM2 Plus)

PM2 bietet ein gehostetes Web-Dashboard unter app.pm2.io. Kostenlose Stufe verfügbar. Verbinden mit:

pm2 link <secret_key> <public_key>

Deployment-Workflow

Typisches Deployment nach einer Code-Aktualisierung:

# 1. Neuesten Code auf dem Server pullen
git pull

# 2. Neue Abhängigkeiten installieren
npm install --omit=dev

# 3. Neu bauen (falls zutreffend)
npm run build

# 4. Prozess neu laden (Zero-Downtime im Cluster-Modus, sonst kurzer Neustart)
pm2 reload meine-app

# 5. Prozessliste speichern, wenn sich etwas geändert hat
pm2 save

Watch-Modus (nur Entwicklung)

PM2 kann Dateien beobachten und den Prozess bei Änderungen automatisch neu starten. Niemals in der Produktion verwenden – er startet bei jeder Dateiänderung neu und verursacht übermäßige CPU-Nutzung.

pm2 start app.js --name "dev-app" --watch
pm2 start app.js --name "dev-app" --watch --ignore-watch="node_modules logs"

Wichtige Hinweise

Nach dem Hinzufügen oder Ändern von Prozessen immer pm2 save ausführen, damit der Zustand über Reboots hinweg erhalten bleibt.
Im Cluster-Modus pm2 reload statt pm2 restart für Zero-Downtime-Updates verwenden.
--watch in der Produktion vermeiden – nur für die Entwicklung gedacht.
ecosystem.config.cjs in der Versionskontrolle speichern, damit das PM2-Setup reproduzierbar ist.
pm2-logrotate auf jedem Langzeit-Server verwenden, um zu verhindern, dass Logs die Festplatte füllen.

Häufig gestellte Fragen

Was ist der Unterschied zwischen pm2 restart und pm2 reload?

restart beendet den Prozess und startet einen neuen – es gibt einen kurzen Moment Downtime. reload (nur Cluster-Modus) ersetzt Worker nacheinander, während die anderen Anfragen weiter verarbeiten, und erreicht so Zero Downtime.

Meine App startet nach einem Server-Reboot nicht neu. Was ist falsch?

Wahrscheinlich wurde einer der zwei Schritte übersprungen: Den pm2 startup-Befehl ausführen (einschließlich des sudo env ...-Befehls, den er ausgibt) und pm2 save ausführen. Beide sind erforderlich.

Wie betreibe ich mehrere Apps auf demselben Server?

Alle in das apps-Array der Ecosystem-Datei eintragen oder jeden einzeln mit einem eindeutigen --name starten. Jeder App einen anderen Port geben und für jede Domain einen separaten Nginx-Server-Block erstellen.

Wie setze ich Umgebungsvariablen sicher?

Keine Secrets in ecosystem.config.cjs speichern, wenn sie in der Versionskontrolle sind. Stattdessen in einer .env-Datei auf dem Server festlegen und beim Start laden, oder im Shell exportieren, bevor PM2 ausgeführt wird. Alternativ den env_production-Block in der Ecosystem-Datei nur für nicht-sensible Konfiguration verwenden.

Kann PM2 Nicht-Node.js-Prozesse verwalten?

Ja – PM2 kann jede ausführbare Datei verwalten. interpreter: 'python3' oder interpreter: 'none' in der Ecosystem-Datei verwenden. PM2 wurde jedoch für Node.js entwickelt, und sprachspezifische Features (Cluster-Modus, --harmony-Flags usw.) gelten nur für Node.js-Prozesse.

Wie deinstalliere ich PM2 komplett?

pm2 delete all
pm2 unstartup
sudo npm uninstall -g pm2
rm -rf ~/.pm2