Startseite / Artikel / Einrichten einer Node.js-App auf cPanel-Shared-Hosting mit Passenger

Node.js cPanel Passenger Express Deployment Shared Hosting

Einrichten einer Node.js-App auf cPanel-Shared-Hosting mit Passenger

Ein Schritt-für-Schritt-Leitfaden zur Ausführung einer Express-Anwendung auf cPanel-Shared-Hosting mit Application Manager und Passenger, einschließlich Neustarts, Umgebungsvariablen und Lösungen für Fehler 503.

1265 Wörter

Viele cPanel-Shared-Hosts können eine Express-Anwendung oder einen API-Server gut betreiben, sofern das Konto Node.js-Unterstützung mit Phusion Passenger hinter dem cPanel Application Manager bietet. Sie müssen weder Nginx noch einen Apache-Reverse-Proxy oder PM2 selbst konfigurieren; Passenger startet die Anwendung und leitet die Anfragen dorthin weiter. Diese Anleitung behandelt den gesamten Bereitstellungsprozess – von der Überprüfung, ob die Funktion aktiviert ist, über die Diagnose eines 503-Fehlers bis hin zu einer Checkliste vor dem Start.

Was Ihr Hosting-Konto benötigt

Stellen Sie vor dem Hochladen von Inhalten sicher, dass das Konto Folgendes bietet:

Node.js-Unterstützung
cPanel Application Manager
Passenger
Zugang zum Terminal oder über SSH
npm
Eine Domain oder Subdomain, von der aus die Anwendung bereitgestellt werden soll
Zugang zu einer Datenbank, falls die Anwendung eine benötigt

Falls der Application Manager fehlt, bitten Sie Ihren Host, Node.js und Passenger zu aktivieren. Hosts, die CloudLinux verwenden, können das Tool unterschiedlich benennen.

Schritt 1: Überprüfen, ob Node.js verfügbar ist

In cPanel öffnen Sie Software und anschließend Application Manager (in einigen Versionen werden die Node.js-Optionen stattdessen unter der Websiteverwaltung angezeigt). Wenn diese Seite öffnet wird, ist das Konto bereit.

Schritt 2: Die Anwendung hochladen

Laden Sie das Projekt mit dem Dateimanager oder Git in einen Ordner in Ihrem Home-Verzeichnis hoch, zum Beispiel:

/home/username/my-node-app

Die typische Projektstruktur sieht so aus:

my-node-app/
├── package.json
├── package-lock.json
├── app.js
├── src/
└── ...

Lassen Sie die Quelldateien außerhalb von public_html, da Browser direkt auf alles zugreifen können, was dort platziert ist.

Schritt 3: `package.json` vorbereiten und Abhängigkeiten installieren

Das Projekt benötigt eine gültige package.json-Datei, die seine Abhängigkeiten sowie ein Startskript angibt. Ein minimales Express-Beispiel:

{
  "name": "my-node-app",
  "version": "1.0.0",
  "scripts": {
    "start": "node app.js"
  },
  "dependencies": {
    "express": "^5.1.0"
  }
}

Öffnen Sie anschließend das Terminal in cPanel, wechseln Sie in den Projektordner und führen Sie die Installation aus:

cd ~/my-node-app
npm install

Dadurch werden die angegebenen Abhängigkeiten auf dem Server installiert. Mit einer gespeicherten Lock-Datei ist npm ci --omit=dev eine leichtere und reproduzierbare Alternative.

Schritt 4: Schreiben Sie die Startdatei

Passenger benötigt einen Einstiegspunkt, den es starten kann, wie zum Beispiel:

app.js

Bei einer Express-Anwendung beginnt diese Datei damit, Express zu laden:

const express = require('express');

danach wird die Anwendung erstellt, eine Route definiert und das Zuhören gestartet. Der folgende Code ist auf wenige Zeilen komprimiert, bleibt aber gültiges JavaScript, da jeder Satz mit einem Semikolon endet.

const app = express();const PORT = process.env.PORT || 3000;app.get('/', (req, res) => {
    res.send('Node.js application is working!');
});app.listen(PORT, '0.0.0.0', () => {
    console.log(`Application running on port ${PORT}`);
});

Warum der Port aus `process.env.PORT` stammen muss

Codeien Sie keinen öffentlichen Port fest ein. Passenger bestimmt, wie Anfragen zu Ihrem Prozess gelangen, daher sollten Sie den Port aus der Umgebung abrufen und einen lokalen Ersatz bereithalten:

const PORT = process.env.PORT || 3000;

Derselbe Code läuft anschließend lokal auf Port 3000 sowie unter Passenger unverändert.

Schritt 5: Die Anwendung in cPanel registrieren

In Application Manager klicken Sie auf Create Application oder Register Application. Geben Sie der Anwendung einen Namen wie my-node-app, wählen Sie die Domain (zum Beispiel example.com) sowie / als Basis-URL, legen Sie den Projektordner als Wurzelort und app.js als Startdatei fest, wählen Sie eine stabile Node.js-Version, die von Ihren Abhängigkeiten unterstützt wird, und wählen Sie die Produktionsumgebung aus. Klicken Sie anschließend auf Create oder Deploy. Der resultierende Anfragenpfad sieht wie folgt aus:

https://example.com
       ↓
     Apache
       ↓
    Passenger
       ↓
   Node.js App
       ↓
     app.js

Apache erhält die Anfrage, und Passenger leitet sie an den aus Ihrer Startdatei gestarteten Node.js-Prozess weiter.

Schritt 6: Umgebungsvariablen festlegen

Definieren Sie Umgebungsvariablen in den Einstellungen der Anwendung und nicht im Code. Zum Beispiel:

APP_ENV=production
DB_HOST=localhost
DB_DATABASE=mydb
DB_USERNAME=myuser
DB_PASSWORD=your_password

Ihr Code liest sie über process.env ein:

process.env.DB_HOST
process.env.DB_DATABASE
process.env.DB_USERNAME

Bewahren Sie Geheimnisse ausschließlich auf der Serverseite auf: niemals in Frontend-JavaScript oder in einer öffentlich zugänglichen Datei wie einem .env in public_html.

Schritt 7: Nach jeder Änderung neu starten

Passenger hält die Anwendung geladen, sodass Änderungen erst nach einem Neustart über den Application Manager wirksam werden. Wo die Restart-Datei-Konvention unterstützt wird, funktioniert auch die Terminal-Lösung:

mkdir -p ~/my-node-app/tmp
touch ~/my-node-app/tmp/restart.txt

Passenger überwacht das Zeitstempel von tmp/restart.txt und startet die Anwendung beim nächsten Aufruf erneut, sobald sich dieser Zeitstempel geändert hat – was sich gut für Deployment-Skripte eignet.

Fehlerbehebung bei 503 Service Unavailable

Der Fehler, dem Sie am ehesten begegnen werden, ist dieser:

503 Service Unavailable

Ein 503-Fehler bedeutet selten, dass der Server down ist; in der Regel konnte Passenger Ihre Anwendung nicht starten oder darauf zugreifen. Führen Sie sie zunächst selbst aus:

cd ~/my-node-app
node app.js

Falls es abstürzt, beheben Sie das zuerst. Wenn es startet, überprüfen Sie die üblichen Ursachen.

Falsches Startdatei

Der Application Manager muss auf die tatsächlich vorhandene Datei verweisen, mit der der Server gestartet wird:

app.js

Fehlende Abhängigkeiten

Falls node_modules fehlt oder unvollständig ist, installieren Sie es erneut:

npm install

Inkompatible Node.js-Version

Überprüfen Sie, welche Version die Terminalanwendung verwendet und welche Versionen von Ihren Abhängigkeiten erforderlich sind:

node -v

Wählen Sie anschließend in den Anmeldeeinstellungen eine passende Version aus.

Hart kodierter Port

Stellen Sie sicher, dass der Server auf folgendem Port lauscht:

process.env.PORT

anstatt auf einem festgelegten öffentlichen Port.

Fehlende Umgebungsvariablen

Überprüfen Sie, ob Zugangsdaten, API-Schlüssel, der Anwendungsmodus sowie weitere erforderliche Werte gesetzt sind; eine undefinierte Variable, die den Start verhindert, führt ebenfalls zu einem 503-Fehler.

Protokolle

Die Logs von Passenger oder cPanel zeigen in der Regel den genauen Startfehler an.

Shared Hosting gegenüber VPS

Die beiden Umgebungen unterscheiden sich hauptsächlich darin, wer den Server kontrolliert. Bei cPanel Shared Hosting sieht die Architektur ungefähr so aus:

cPanel
   │
   ├── Apache
   ├── Passenger
   └── Node.js
          │
          └── Your Application

Der Host und Passenger verwalten den Webserver sowie die Prozesse. Bei einem VPS gehören alle Schichten Ihnen:

VPS
 │
 ├── Nginx/Apache
 ├── Node.js
 ├── PM2
 ├── Firewall
 ├── SSL
 └── Application

Ein VPS bietet viel mehr Kontrolle und eignet sich in der Regel besser für ressourcenintensive oder stark angepasste Anwendungen; siehe ein praktisches Framework zur Bereitstellung von Node.js-Anwendungen in der Produktion. Shared Hosting tauscht diese Kontrolle gegen Einfachheit ein.

Eine saubere Verzeichnisstruktur

Eine ordentliche cPanel-Deployment hält die Anwendung sowie den öffentlichen Web-Root nebeneinander:

/home/username/
│
├── my-node-app/
│   ├── app.js
│   ├── package.json
│   ├── package-lock.json
│   ├── node_modules/
│   ├── src/
│   └── tmp/
│       └── restart.txt
│
└── public_html/

Anfragen erreichen my-node-app über Apache und Passenger, wobei public_html frei von Servercode bleibt.

Endkontrolliste

Bevor Sie die Bereitstellung für abgeschlossen halten, überprüfen Sie Folgendes:

Node.js ist für das Konto aktiviert
Application Manager ist verfügbar
eine kompatible Node.js-Version wurde ausgewählt
die Projektdateien wurden außerhalb von public_html hochgeladen
package.json ist vorhanden
npm install wurde ohne Fehler abgeschlossen
die Einstellung der Startdatei ist korrekt
der Server hört auf process.env.PORT zu
Umgebungsvariablen sind konfiguriert
die Umgebung ist auf Production eingestellt
die Anwendung wurde seit der letzten Änderung neu gestartet
die Domain lädt im Browser

Die Protokolle zeigen keine Startfehler an

Zusammenfassung

Bei cPanel-Shared Hosting ist der Application Manager mit Passenger der zuverlässige Ansatz, um Express-Anwendungen und APIs ohne Root-Zugriff auszuführen. Lassen Sie Passenger den Port verwalten, nach jeder Änderung neu starten und bei Problemen die Anwendung manuell ausführen sowie vor Konfigurationsänderungen die Protokolle prüfen.

Alle Artikel Brief senden