Rozwijanie aplikacji Node.js na współdzielonej hostingu cPanel z użyciem Passenger

Wiele hostów współdzielonych cPanel potrafi dobrze uruchamiać aplikacje Express lub serwery API, pod warunkiem że konto posiada wsparcie dla Node.js wraz z Phusion Passenger za pośrednictwem Application Managera cPanel. Nie musisz sam konfigurować Nginx, odwrotnego proxya Apache ani PM2; Passenger uruchamia aplikację i kieruje do niej żądania. Ten przewodnik omawia cały proces wdrożenia, od sprawdzenia aktywacji tej funkcji po diagnozowanie błędu 503, a na końcu znajduje się lista kontrolna przed uruchomieniem.

Czego potrzebuje twoje konto hostingowe

Zanim cokolwiek przesuniesz, upewnij się, że konto oferuje następujące elementy:

• Wsparcie dla Node.js
• cPanel Application Manager
• Passenger
• Dostęp przez terminal lub SSH
• npm
• Domenę lub poddomenę, z której ma być serwowana aplikacja
• Dostęp do bazy danych, jeśli aplikacja go wymaga

Jeśli brakuje Application Manager, poproś swojego hosta o włączenie Node.js i Passenger. Hostowie używający CloudLinux mogą nazywać to narzędzie inaczej.

Krok 1: Sprawdzenie dostępności Node.js

W cPanel otwórz Software, a następnie Application Manager (w niektórych wersjach opcje Node.js znajdują się zamiast tego pod zakładką zarządzania stroną internetową). Jeśli się otworzy, konto jest gotowe.

Krok 2: Wgranie aplikacji

Za pomocą File Manager lub Git wgraj projekt do folderu w swoim katalogu domowym, na przykład:

/home/username/my-node-app

Typowy układ projektu wygląda tak:

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

Zachowaj plik źródłowy poza katalogiem public_html, ponieważ przeglądarki mogą bezpośrednio żądać dowolnych plików umieszczonych tam.

Krok 3: Przygotowanie pliku package.json i zainstalowanie zależności

Projekt wymaga ważnego pliku package.json, który określa jego zależności oraz skrypt uruchamiania. Minimalny przykład z Express:

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

Następnie otwórz Terminal w cPanel, przenieś się do folderu projektu i zainstaluj:

cd ~/my-node-app
npm install

To instaluje określone zależności na serwerze. Przy użyciu pliku lock, npm ci --omit=dev jest lżejszą i powtarzalną alternatywą.

Krok 4: Napisanie pliku uruchamiania

Passenger potrzebuje punktu wejścia, który może uruchomić, na przykład:

app.js

Dla aplikacji Express ten plik zaczyna się od załadunku biblioteki Express:

const express = require('express');

a następnie tworzy aplikację, definiuje trasę i rozpoczyna odsłuchiwanie. Poniższy kod jest skompresowany na kilka wierszy, ale pozostaje poprawnym JavaScriptem, ponieważ każde zdanie kończy się średnikiem.

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}`);
});

Dlaczego port musi pochodzić z process.env.PORT

Nie wpisywaj portu publicznego bezpośrednio w kodzie. Passenger decyduje o tym, jak żądania docierają do twojego procesu, dlatego odczytuj port z środowiska i zachowaj lokalną alternatywę:

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

Ten sam kod jest następnie uruchamiany lokalnie na porcie 3000 oraz w środowisku Passenger bez żadnych zmian.

Krok 5: Zarejestruj aplikację w cPanel

W Application Manager kliknij Create Application lub Register Application. Nadaj aplikacji nazwę, na przykład my-node-app, wybierz domenę (na przykład example.com) oraz / jako podstawową adresację URL, ustaw foldер projektu jako katalog korzeniowy, a plik app.js jako plik startowy, wybierz stabilną wersję Node.js obsługiwaną przez twoje zależności i wybierz środowisko Production. Następnie kliknij Create lub Deploy. Path żądania będzie wyglądał w ten sposób:

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

Apache otrzymuje żądanie, a Passenger przekazuje je do procesu Node.js uruchomionego z twojego pliku startowego.

Krok 6: Ustawienie zmiennych środowiskowych

Zdefiniuj zmienne środowiskowe w ustawieniach aplikacji, a nie w kodzie. Na przykład:

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

Twój kod odczytuje je za pomocą process.env:

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

Tajemnice należy przechowywać wyłącznie po stronie serwera: nigdy w JavaScriptu front-endowym ani w pliku dostępnym publicznie, takim jak .env w katalogu public_html.

Krok 7: Ponowne uruchomienie po każdej zmianie

Passenger utrzymuje aplikację w stanie uruchomionym, więc zmiany zostaną zastosowane dopiero po ponownym uruchomieniu przez Application Manager. Tam, gdzie obsługiwana jest konwencja pliku restartu, działa również terminal:

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

Passenger monitoruje datę i godzinę pliku tmp/restart.txt i ponownie uruchamia aplikację przy następnym żądaniu po jej zmianie, co nadaje się do skryptów deployowych.

Rozwiązywanie problemu 503 Service Unavailable

Błąd, z którym najczęściej się spotykasz, to właśnie ten:

503 Service Unavailable

503 rzadko oznacza wyłączenie serwera; zazwyczaj Passenger nie był w stanie uruchomić lub połączyć się z twoją aplikacją. Najpierw spróbuj uruchomić ją sam:

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

Jeśli wystąpi awaria, napraw to najpierw. Jeśli aplikacja uruchomi się, sprawdź typowe przyczyny problemów.

Niezgodny plik startowy

Menedżer aplikacji musi wskazywać na plik, który rzeczywiście istnieje i uruchamia serwer:

app.js

Brak zależności

Jeśli katalog node_modules jest nieobecny lub niekompletny, zainstaluj go ponownie:

npm install

Niezgodna wersja Node.js

node -v

Następnie wybierz odpowiadającą wersję w ustawieniach aplikacji.

Port zapisany w kodzie

Upewnij się, że serwer słucha na:

process.env.PORT

a nie na stałym porcie publicznym.

Brak zmiennych środowiskowych

Potwierdź, że dane logowania, klucze API, tryb działania aplikacji oraz inne wymagane wartości są ustawione; niezdefiniowana zmienna powodująca awarię startu również skutkuje błędem 503.

Logi

Łogi aplikacji Passenger lub cPanel zazwyczaj pokazują dokładny błąd uruchamiania.

Hosting współdzielony versus VPS

Różnice między tymi dwoma środowiskami wynikają głównie z tego, kto kontroluje serwer. W przypadku hostingu współdzielonego z cPanel stack wygląda mniej więcej w ten sposób:

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

Host i Passenger zarządzają serwerem internetowym oraz procesami. W przypadku VPS masz kontrolę nad każdą warstwą:

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

VPS oferuje znacznie większą kontrolę i zazwyczaj lepiej nadaje się do aplikacji wymagających dużych zasobów lub silnie spersonalizowanych; patrz praktyczne ramy pracy przy przenoszeniu aplikacji Node.js do produkcji. Hosting współdzielony oferuje prostotę w zamian za ograniczoną kontrolę.

Czysta struktura katalogów

Uporządkowana implementacja w cPanel umożliwia umieszczenie aplikacji oraz publicznego katalogu głównego obok siebie:

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

Zapytania trafiają do my-node-app przez Apache i Passenger, a katalog public_html pozostaje wolny od kodu serwera.

Ostateczna lista kontrolna

Zanim uznasz, że implementacja jest ukończona, upewnij się, że:

• Dla konta jest włączone Node.js
• Dostępny jest Application Manager
• Została wybrana kompatybilna wersja Node.js
• Pliki projektu zostały przesłane poza katalog public_html
• Istnieje plik package.json
• Komenda npm install zakończyła się bez błędów
• Ustawienie pliku startowego jest poprawne
• Serwer nasłuchuje na adresie process.env.PORT
• Zmienne środowiskowe są skonfigurowane
• Środowisko zostało ustawione na Production
• Aplikacja została ponownie uruchomiona po ostatniej modyfikacji
• Domena otwiera się w przeglądarce

zapisy z logów nie wykazują błędów startowych

Podsumowanie

W usługach hostingu współdzielonego cPanel, Application Manager z Passenger to niezawodne rozwiązanie, które umożliwia uruchamianie aplikacji Express i API bez uprawnień root. Pozwala to Passengerowi zarządzać portem, restartować aplikację po każdej zmianie oraz, gdy coś się zepsuje, uruchamiać aplikację ręcznie i czytać logi przed modyfikacją konfiguracji.