Node.js-App deployen: PM2 und Nginx auf dem Server
Node.js-App deployen auf dem Linux-Server: Node.js LTS, npm ci, PM2 mit Autostart und Reload, Nginx als Reverse Proxy, HTTPS, Updates und typische Fehler.

Inhalt
- Voraussetzungen
- Schritt 1: Node.js LTS, PM2 und Nginx
- Schritt 2: Benutzer, Code und npm ci
- Schritt 3: Umgebungsvariablen und Listen-Adresse
- Schritt 4: Die App mit PM2 starten
- Schritt 5: Autostart beim Booten
- Schritt 6: Cluster-Modus
- Schritt 7: Nginx als Reverse Proxy
- Schritt 8: Firewall und HTTPS
- Updates deployen
- Logs und typische Fehler
- Ein Hinweis zu Next.js, Nuxt und NestJS
- Nodesty Server für Node.js-Apps
Wer eine Node.js-App deployen möchte, kommt mit node server.js in einer SSH-Sitzung nicht weit: Die App endet, sobald die Sitzung geschlossen wird, bleibt nach einem Absturz aus und kommt nach einem Neustart nicht zurück. Üblich ist auf einem Linux-vServer daher PM2 als Prozessmanager, der die App am Laufen hält, und davor Nginx als Reverse Proxy für HTTPS und WebSocket-Verbindungen. Steht dieses Setup einmal, besteht jedes Update nur noch aus einer Handvoll Befehle.
In dieser Anleitung zeigen wir, wie Sie eine Node.js-Anwendung, etwa eine Express-API, auf einem frischen Ubuntu-Server deployen: Node.js LTS installieren, ein eigener Benutzer, npm ci, Umgebungsvariablen, PM2 mit Autostart und Cluster-Modus, Nginx als Reverse Proxy, Firewall, HTTPS, Updates und die häufigsten Fehler.
Voraussetzungen
- Server: Ein Ubuntu-Server mit Root-Zugriff. In dieser Anleitung verwenden wir Ubuntu 24.04.
- Anwendung: Ein Node.js-Projekt in einem Git-Repository mit
package.jsonundpackage-lock.json. - Domain: Ein A-Eintrag, der auf die IP-Adresse Ihres Servers zeigt.
Ein Bot, der kein HTTP ausliefert, braucht kein Nginx; für diesen Fall lesen Sie unsere Anleitung Discord-Bot hosten.
Schritt 1: Node.js LTS, PM2 und Nginx
Nachdem Sie sich per SSH mit Ihrem Server verbunden haben:
sudo apt update
sudo apt install nginx git curl
curl -fsSL https://deb.nodesource.com/setup_lts.x -o nodesource_setup.sh
sudo -E bash nodesource_setup.sh
sudo apt install nodejs
sudo npm install -g pm2
node -v && npm -v && pm2 -v
Die eigenen Paketquellen von Ubuntu 24.04 enthalten Node.js 18, das nicht mehr unterstützt wird. Das NodeSource-Repository installiert die aktuelle LTS-Version systemweit als /usr/bin/node, zusammen mit npm; um bei einer Hauptversion zu bleiben, ersetzen Sie setup_lts.x zum Beispiel durch setup_24.x. Auf Servern ist uns dieser Weg lieber als nvm: nvm installiert Node.js im Home-Verzeichnis eines einzelnen Benutzers, was die Pfade für Dienste und den Autostart fehleranfälliger macht.
Unter AlmaLinux führen Sie curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash - und danach sudo dnf install nodejs nginx git aus. Nginx läuft dort als Benutzer nginx, und Site-Dateien gehören nach /etc/nginx/conf.d/. Die Grundlagen finden Sie in unserer Anleitung Nginx installieren.
Schritt 2: Benutzer, Code und npm ci
Führen Sie die Anwendung nicht als root aus. Legen Sie dafür einen Benutzer und einen Ordner unter /srv an:
sudo adduser --disabled-password --gecos "" deploy
sudo mkdir -p /srv/app
sudo chown deploy:deploy /srv/app
sudo -iu deploy
git clone git@github.com:user/app.git /srv/app
cd /srv/app
npm ci
npm run build # nur, wenn Ihr Projekt einen Build-Schritt hat
npm ci löscht node_modules und installiert genau die Versionen, die in der package-lock.json festgehalten sind; so erhält der Server dieselben Pakete, mit denen Sie getestet haben. Passen Lock-Datei und package.json nicht zusammen, bricht der Befehl mit einem Fehler ab. Hat das Projekt keinen Build-Schritt, überspringt npm ci --omit=dev die Entwicklungsabhängigkeiten. Deploy Keys behandeln wir in unserer Anleitung Deployment mit Git, die Benutzerverwaltung in Linux-Benutzer anlegen. Führen Sie die Befehle der folgenden Schritte als Benutzer deploy aus, sofern sie nicht mit sudo beginnen.
Schritt 3: Umgebungsvariablen und Listen-Adresse
Halten Sie Geheimnisse aus dem Code und dem Repository heraus. Legen Sie die Datei /srv/app/.env an, tragen Sie sie in die .gitignore ein und schützen Sie sie mit chmod 600 .env:
SESSION_SECRET=hier-einen-langen-zufallswert-einfuegen
DATABASE_URL=postgres://app:ein-starkes-passwort@127.0.0.1:5432/app
Einen passenden Zufallswert erzeugt openssl rand -hex 32. Node.js ab Version 20.6 kann diese Datei mit dem Flag --env-file laden, ein zusätzliches Paket ist also nicht nötig; nutzt Ihr Projekt bereits dotenv, funktioniert auch das. Lesen Sie die Werte mit process.env aus und lassen Sie die App nur auf der lokalen Adresse lauschen:
const port = Number(process.env.PORT) || 3000;
app.set('trust proxy', 1); // Express: den X-Forwarded-*-Headern von Nginx vertrauen
app.listen(port, '127.0.0.1');
Ohne Host-Argument lauscht Node.js auf allen Netzwerkschnittstellen; die App würde dann auch unter http://SERVER-IP:3000 antworten, an Nginx vorbei und ohne HTTPS. Testen Sie sie nun:
node --env-file=.env server.js
Aus einer zweiten SSH-Sitzung sollte curl -I http://127.0.0.1:3000 eine Antwort liefern. Beenden Sie die App mit Strg+C.
Schritt 4: Die App mit PM2 starten
Beschreiben Sie die App in der Datei /srv/app/ecosystem.config.js; so stehen die Einstellungen in einer Datei statt in einem langen Befehl:
module.exports = {
apps: [
{
name: 'app',
script: 'server.js',
cwd: '/srv/app',
node_args: '--env-file=.env',
env: {
NODE_ENV: 'production',
PORT: 3000,
},
},
],
};
pm2 start ecosystem.config.js
pm2 status
Enthält Ihre package.json den Eintrag "type": "module", nennen Sie die Datei stattdessen ecosystem.config.cjs. Die Befehle, die Sie am häufigsten brauchen:
| Befehl | Wirkung |
|---|---|
pm2 status | Listet die Prozesse mit Status, Zahl der Neustarts (↺) und Speicher auf |
pm2 logs app | Zeigt die Ausgabe der App live; die Dateien liegen in ~/.pm2/logs/ |
pm2 reload app | Startet den neuen Code; im Cluster-Modus Prozess für Prozess |
pm2 restart app | Stoppt und startet alle Prozesse der App gleichzeitig |
pm2 stop app / pm2 delete app | Stoppt die App / entfernt sie aus der PM2-Liste |
pm2 monit | Zeigt CPU, Speicher und Logs live im Terminal |
Zwei Dinge sollten Sie wissen:
- Umgebung: PM2 merkt sich die
env-Werte vom ersten Start. Führen Sie nach einer Änderungpm2 reload ecosystem.config.js --update-envaus;pm2 reload appallein behält die alten Werte. Die Datei.envwird dagegen bei jedem Start neu gelesen, dort genügt ein normaler Reload. - Logs: Die Logdateien von PM2 wachsen unbegrenzt.
pm2 install pm2-logrotateergänzt eine automatische Rotation, damit die Logs nicht irgendwann die Festplatte füllen.
Schritt 5: Autostart beim Booten
PM2 selbst muss beim Booten des Servers starten und Ihre Apps zurückbringen. Speichern Sie die Prozessliste als deploy, wechseln Sie dann zurück in Ihr Admin-Konto und registrieren Sie PM2 für diesen Benutzer als systemd-Dienst:
pm2 save
exit
sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u deploy --hp /home/deploy
pm2 startup legt einen Dienst namens pm2-deploy an und aktiviert ihn; beim Booten stellt er die Liste wieder her, die pm2 save nach /home/deploy/.pm2/dump.pm2 geschrieben hat. Führen Sie pm2 save erneut aus, sobald Sie eine App hinzufügen oder entfernen. Um sicherzugehen, starten Sie den Server einmal mit sudo reboot neu und prüfen Sie als deploy die Ausgabe von pm2 status. Möchten Sie die App lieber allein mit systemd verwalten, lesen Sie unsere Anleitung systemd-Service erstellen.
Schritt 6: Cluster-Modus
Ein Node.js-Prozess führt Ihr JavaScript auf einem einzigen CPU-Kern aus. Im Cluster-Modus startet PM2 mehrere Kopien der App, die sich denselben Port teilen. Ergänzen Sie den App-Eintrag in der ecosystem.config.js um zwei Zeilen:
instances: 'max',
exec_mode: 'cluster',
max startet einen Prozess pro CPU-Kern; Sie können auch eine Zahl angeben. Ein Wechsel des Modus erfordert einen frischen Start: pm2 delete app, danach pm2 start ecosystem.config.js und pm2 save. Von da an ersetzt pm2 reload app die Prozesse nacheinander, ohne Ausfallzeit.
- Kein Zustand im Speicher: Sitzungen, Caches oder Rate-Limit-Zähler, die in einer Variablen liegen, existieren einmal pro Prozess. Verlagern Sie sie in die Datenbank oder nach Redis. Socket.IO benötigt bei mehreren Instanzen zusätzlich Sticky Sessions.
- Sauberes Beenden: Bei einem Reload sendet PM2 dem alten Prozess
SIGINTund beendet ihn standardmäßig nach 1,6 Sekunden (kill_timeout). Fangen Sie das Signal ab, um offene Anfragen abzuschließen und Datenbankverbindungen zu schließen. - Speicher: Jede Instanz belegt ihren eigenen RAM. Leistet die App wenig CPU-Arbeit, reichen oft ein oder zwei Instanzen.
Schritt 7: Nginx als Reverse Proxy
Legen Sie die Datei /etc/nginx/sites-available/app an:
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 80;
listen [::]:80;
server_name example.com www.example.com;
client_max_body_size 20M;
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;
}
}
sudo ln -s /etc/nginx/sites-available/app /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
- Proxy-Header:
Host,X-Real-IP,X-Forwarded-ForundX-Forwarded-Prototeilen der App mit, welche Domain angefragt wurde, wer der Besucher ist und ob die Anfrage über HTTPS kam. Ohne sie sieht jede Anfrage wie einfaches HTTP von127.0.0.1aus. - WebSocket:
proxy_http_version 1.1zusammen mit den HeadernUpgradeundConnectionlässt WebSocket-Verbindungen (Socket.IO, Live-Updates) durch. Dermap-Block sendetConnection: upgradenur, wenn der Browser es anfordert. - Timeouts: Nginx schließt eine Proxy-Verbindung, auf der 60 Sekunden lang nichts ankommt (
proxy_read_timeout). Senden Sie bei WebSockets regelmäßig Ping-Nachrichten oder erhöhen Sie den Wert. client_max_body_size: Nginx erlaubt standardmäßig Uploads bis 1 MB; größere Anfragen erhalten einen 413-Fehler.127.0.0.1stattlocalhost:localhostwird auch zur IPv6-Adresse::1aufgelöst, auf der die App nicht lauscht.
Unter AlmaLinux speichern Sie die Datei als /etc/nginx/conf.d/app.conf und erlauben Nginx mit sudo setsebool -P httpd_can_network_connect 1 Verbindungen zu lokalen Ports; andernfalls blockiert SELinux den Proxy und Sie erhalten einen 502-Fehler.
Schritt 8: Firewall und HTTPS
Öffnen Sie nur SSH und die Web-Ports. Port 3000 bleibt geschlossen:
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable
Läuft SSH auf einem anderen Port, geben Sie diesen frei, bevor Sie die Firewall aktivieren, sonst sperren Sie sich aus. Mehr dazu in unserer Anleitung UFW Firewall. Unter AlmaLinux verwenden Sie sudo firewall-cmd --permanent --add-service=http --add-service=https und danach sudo firewall-cmd --reload. Holen Sie anschließend das Zertifikat:
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d example.com -d www.example.com
Certbot holt das Zertifikat, ergänzt den HTTPS-Serverblock und richtet die automatische Verlängerung ein. Details finden Sie in unserem Artikel Was ist ein SSL-Zertifikat?.
Updates deployen
sudo -iu deploy
cd /srv/app
git pull
npm ci
npm run build # nur, wenn Ihr Projekt einen Build-Schritt hat
pm2 reload app
Die laufenden Prozesse halten den alten Code bis zum Reload im Speicher. Prüfen Sie danach pm2 status und pm2 logs app --lines 50: Steigt die Zahl der Neustarts (↺) immer weiter, stürzt die neue Version beim Start ab. Da npm ci den Ordner node_modules neu aufbaut, während die alte Version noch läuft, bauen größere Projekte jedes Release in einem eigenen Ordner; diesen Ansatz und ein Deploy-Skript zeigt unsere Anleitung Deployment mit Git. Sichern Sie die Datenbank vor Migrationen, die Daten verändern; siehe unsere Anleitung Server-Backup.
Logs und typische Fehler
Die Ausgabe der App sehen Sie mit pm2 logs app, Nginx schreibt nach /var/log/nginx/error.log.
| Fehler | Häufige Ursache |
|---|---|
| 502 Bad Gateway | Die App läuft nicht oder stürzt immer wieder ab (errored in pm2 status), oder proxy_pass nutzt den falschen Port |
EADDRINUSE: address already in use | Ein anderer Prozess belegt Port 3000, oft ein von Hand gestartetes node server.js oder ein zweites PM2 als root |
Website öffnet sich unter http://SERVER-IP:3000 | Die App lauscht auf 0.0.0.0 oder :: statt auf 127.0.0.1 und die Firewall ist offen |
EACCES: permission denied beim Lauschen | Die App will als normaler Benutzer einen Port unter 1024 nutzen; nehmen Sie 3000 und überlassen Sie 80 und 443 Nginx |
EACCES bei npm ci oder beim Schreiben | Dateien gehören nach einem sudo npm oder sudo git pull root |
Cannot find module | npm ci wurde nach dem Update nicht ausgeführt, oder cwd zeigt auf den falschen Ordner |
| App ist nach einem Neustart verschwunden | pm2 startup wurde nie eingerichtet, oder pm2 save wurde nach der letzten Änderung nicht ausgeführt |
- Port belegt:
sudo ss -tlnp | grep :3000zeigt, welcher Prozess den Port hält. Alles Weitere steht in unserer Anleitung Port bereits belegt. - 127.0.0.1 oder 0.0.0.0: Läuft Nginx auf demselben Server, ist
127.0.0.1richtig. Nur wenn die App in einem Docker-Container läuft oder Nginx auf einem anderen Server steht, muss sie auf0.0.0.0lauschen; beschränken Sie den Port dann mit der Firewall. - Rechte: Korrigieren Sie den Besitzer mit
sudo chown -R deploy:deploy /srv/app. Verwenden Sie im Alltag keinsudo pm2 ...: Das startet ein zweites PM2 als root mit eigener Prozessliste unter/root/.pm2, und beide streiten sich um denselben Port.
Eine Schritt-für-Schritt-Checkliste für 502-Fehler finden Sie in unserer Anleitung 502 Bad Gateway beheben.
Ein Hinweis zu Next.js, Nuxt und NestJS
Frameworks mit Build-Schritt funktionieren genauso: Führen Sie npm run build aus und lassen Sie script dann auf den gebauten Server zeigen. Bei NestJS ist das dist/main.js, bei Nuxt .output/server/index.mjs (es liest die Variablen HOST und PORT) und bei Next.js node_modules/next/dist/bin/next mit args: 'start -H 127.0.0.1 -p 3000'. Die Abkürzung pm2 start npm --name app -- start führt das start-Skript aus der package.json aus, eignet sich aber nicht für den Cluster-Modus, weil PM2 dann npm statt Ihrer App verwaltet. Nginx und HTTPS bleiben unverändert.
Nodesty Server für Node.js-Apps
Die AMD Ryzen 9 9950X vServer von Nodesty sorgen mit hoher Single-Core-Leistung für kurze Antwortzeiten bei Node.js, das Ihren Code pro Prozess auf einem einzigen Kern ausführt; die AMD EPYC 7763 vServer bieten viele Kerne und viel RAM, um den PM2-Cluster-Modus, die Datenbank und Hintergrundjobs auf demselben Server zu betreiben. Mit vollem Root-Zugriff, NVMe-Speicher, DDoS-Schutz durch nShield und kostenlosen täglichen Backups mit 7 Tagen Aufbewahrung bringen Sie Ihre Express-, NestJS- oder Next.js-Projekte sicher online.
Häufig gestellte Fragen
Warum starte ich auf dem Server nicht einfach node server.js oder npm start?
Ein von Hand gestarteter Prozess endet, sobald Sie die SSH-Sitzung schließen, bleibt nach einem Absturz aus und kommt nach einem Neustart des Servers nicht zurück. Ein Prozessmanager wie PM2 lässt die App im Hintergrund laufen, startet sie nach einem Absturz neu, sammelt ihre Logs und startet sie beim Booten des Servers wieder.
Soll ich für eine Node.js-App PM2 oder systemd verwenden?
Beide halten die App am Laufen und starten sie beim Booten. PM2 bringt Node.js-spezifische Komfortfunktionen mit, etwa den Cluster-Modus, Reloads ohne Ausfallzeit und eine eigene Log-Ansicht. systemd ist bereits Teil des Systems und funktioniert für jede Sprache gleich. PM2 nutzt selbst einen kleinen systemd-Dienst, um beim Booten zu starten.
Brauche ich Nginx vor einer Node.js-App?
Node.js kann HTTP-Anfragen auch allein beantworten, doch Nginx davor übernimmt die Ports 80 und 443, HTTPS-Zertifikate, mehrere Websites auf einem Server, Upload-Limits und langsame Clients. Ihre App läuft dann als normaler Benutzer auf einem lokalen Port wie 3000 und ist nie direkt aus dem Internet erreichbar.
Was ist der Unterschied zwischen pm2 restart und pm2 reload?
pm2 restart stoppt alle Prozesse der App und startet sie neu, was eine kurze Unterbrechung verursacht. pm2 reload ersetzt die Prozesse im Cluster-Modus nacheinander, sodass immer einer Anfragen beantwortet. Im Fork-Modus mit nur einem Prozess verhält sich reload wie restart.
Wie viele Instanzen sollte ich im Cluster-Modus starten?
Ein guter Ausgangswert ist eine Instanz pro CPU-Kern, genau das bewirkt die Einstellung max. Jede Instanz ist ein eigener Prozess mit eigenem Speicher; behalten Sie daher den RAM-Verbrauch im Blick und senken Sie die Zahl, sobald der Server swappt. Die App darf Sitzungen oder anderen gemeinsamen Zustand nicht im Prozessspeicher halten.
Warum zeigt meine Website den Fehler 502 Bad Gateway?
Nginx kann die Node.js-App nicht erreichen. Entweder läuft die App nicht, sie stürzt beim Start immer wieder ab oder sie lauscht auf einem anderen Port als dem in proxy_pass. Prüfen Sie zuerst pm2 status und pm2 logs und danach das Nginx-Fehlerlog unter /var/log/nginx/error.log.
Über den Autor
Nodesty-Team · Infrastruktur und Support
Das Nodesty-Team betreibt unsere Server, unser Netzwerk und unseren DDoS-Schutz im Alltag und beantwortet Support-Anfragen rund um die Uhr. Diese Ratgeber entstehen aus dieser Arbeit.
Verwandte Artikel

LEMP-Stack installieren: Nginx, MariaDB und PHP-FPM
LEMP-Stack installieren unter Ubuntu und Debian: Nginx, MariaDB und PHP-FPM, Server Block, PHP-Socket, Dateirechte, HTTPS und typische Fehler.

tmux Anleitung: Programme nach dem SSH-Logout weiterlaufen lassen
tmux Anleitung: Programme nach dem SSH-Logout weiterlaufen lassen, Sitzungen trennen und fortsetzen, Panes, Scrollen, .tmux.conf und typische Fehler.

MySQL Backup erstellen und wiederherstellen
MySQL Backup erstellen mit mysqldump oder mariadb-dump: gzip, ~/.my.cnf, große Importe, tägliche Backups per Cron, Docker und Wiederherstellung testen.