Головна / Статті / Розгортання додатку Node.js на спільному хостингу cPanel за допомогою Passenger

Node.js cPanel Passenger Express Deployment Shared Hosting

Розгортання додатку Node.js на спільному хостингу cPanel за допомогою Passenger

Покроковий посібник з запуску додатку Express на спільному хостингу cPanel за допомогою Application Manager та Passenger, включаючи перезапуск, змінні середовища та вирішення проблем 503.

1265 слів

Багато хостингових планів cPanel з можливістю спільного використання можуть ефективно запускати додатки Express чи сервери API, за умови, що обліковий запис підтримує Node.js через Phusion Passenger у рамках Менеджера додатків cPanel. Вам не потрібно самостійно налаштовувати Nginx, зворотний проксі Apache чи PM2; Passenger запускає додаток та направляє до нього запити. Цей посібник охоплює весь процес розгортання — від перевірки увімкнення цієї функції до діагностики помилки 503 — та закінчується списком перевірок перед запуском.

Що потрібно для вашого хостингового облікового запису

Перед завантаженням будь-чого переконайтеся, що обліковий запис має наступне:

Підтримку Node.js
Менеджер додатків cPanel
Passenger
Доступ до терміналу або SSH
npm
Домен чи піддомен для розміщення додатку
Доступ до бази даних, якщо це необхідно для додатку

Якщо менеджер додатків відсутній, попросіть вашого хоста увімкнути Node.js та Passenger. Хости, які використовують CloudLinux, можуть називати цей інструмент інакше.

Крок 1: Перевірка наявності Node.js

У cPanel відкрийте розділ Software, а потім Application Manager (у деяких версіях опції Node.js відображаються під розділом керування веб-сайтом). Якщо він відкривається, акаунт готовий.

Крок 2: Завантаження додатку

Завантажте проект за допомогою File Manager або Git у папку вашого особистого каталогу, наприклад:

/home/username/my-node-app

Типова структура проекту виглядає так:

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

Зберігайте вихідний код поза каталогом public_html, оскільки браузери можуть безпосередньо запитувати будь-які файли, розташовані там.

Крок 3: Підготовка файлу `package.json` та встановлення залежностей

Проєкт потребує дійсного файлу package.json, який вказує на його залежності та скрипт запуску. Мінімальний приклад для Express:

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

Потім відкрийте Terminal у cPanel, перейдіть у папку проєкту та встановіть необхідне:

cd ~/my-node-app
npm install

Це встановлює зазначені залежності на сервері. За наявності файлу lock, команда npm ci --omit=dev є легшою та відтворюваною альтернативою.

Крок 4: Створення файлу запуску

Passenger потребує точки входу, з якої можна запустити програму, наприклад:

app.js

Для додатку Express цей файл починається з завантаження бібліотеки Express:

const express = require('express');

потім створюється об’єкт додатку, визначається маршрут та починається прослуховування. Наведений нижче код стиснутий у кілька рядків, але залишається коректним JavaScriptом, оскільки кожне речення закінчується крапкою з комою.

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

Чому порт має походити з `process.env.PORT`

Не використовуйте жорстко закодований публічний порт. Passenger визначає, як запити надходять до вашого процесу, тому читайте порт з середовища та мати локальний запасний варіант:

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

Той самий код потім запускається локально на порту 3000 та під Passenger без змін.

Крок 5: Реєструйте додаток у cPanel

У менеджері додатків натисніть Створити додаток або Зареєструвати додаток. Дайте додатку назву, наприклад my-node-app, виберіть домен (наприклад example.com) та / як базову URL, встановіть коренем папку проекту та файл для запуску як app.js, оберіть стабільну версію Node.js, яку підтримують ваші залежності, та виберіть середовище Production. Потім натисніть Створити або Розгорнути. Шлях запиту виглядає так:

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

Apache отримує запит, а Passenger передає його процесу Node.js, який запускається з вашого файлу для запуску.

Крок 6: Встановлення змінних середовища

Визначайте змінні середовища у налаштуваннях додатку, а не в коді. Наприклад:

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

Ваш код читає їх через process.env:

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

Таємні дані слід зберігати лише на серверній стороні: ніколи не в фронтенд-JavaScript чи у файлі, доступному для публіки, такому як .env у каталозі public_html.

Крок 7: Перезапуск після кожної зміни

Passenger утримує додаток у робочому стані, тож зміни набувають чинності лише після перезапуску з Application Manager. У випадках, коли підтримується конвенція файлу для перезапуску, працює також термінал:

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

Passenger стежить за часовою міткою файлу tmp/restart.txt та перезапускає додаток після наступного запиту, коли вона змінюється, що підходить для скриптів розгортання.

Усунення проблеми 503 Service Unavailable

Найімовірнішою проблемою, з якою ви зіткнетеся, є саме ця:

503 Service Unavailable

Код 503 рідко означає, що сервер не працює; зазвичай Passenger не зміг запустити або встановити зв’язок із вашим додатком. Спочатку спробуйте запустити його самостійно:

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

Якщо він зупиняється, спочатку виправте це. Якщо він запускається, перевірте типові причини.

Неправильний файл запуску

Менеджер додатків має вказувати на файл, який дійсно існує та запускає сервер:

app.js

Відсутні залежності

Якщо папка node_modules відсутня або неповна, встановіть її знову:

npm install

Несумісна версія Node.js

Перевірте, яку версію використовує термінал, та які версії вимагають ваші залежності:

node -v

Потім оберіть відповідну версію у налаштуваннях додатку.

Жорстко закодований порт

Переконайтеся, що сервер прослуховує на:

process.env.PORT

а не на фіксований публічний порт.

Відсутні змінні середовища

Переконайтеся, що облікові дані, ключі API, режим додатку та інші необхідні значення встановлені; невизначена змінна, яка заважає запуску, також призводить до коду 503.

Журнали

Журнали Passenger або cPanel зазвичай відображають точну помилку запуску.

Спільне хостингу проти VPS

Ці два типи середовищ відрізняються переважно тим, хто контролює сервер. У спільному хостингу з cPanel структура виглядає приблизно так:

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

Хост та Passenger керують веб-сервером та процесами. У VPS ви контролюєте кожен рівень:

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

VPS забезпечує значно більший контроль та зазвичай краще підходить для застосунків, які потребують багато ресурсів або мають високий ступінь налаштування; див. практичну схему для випуску застосунків на Node.js у продакшн. Спільне хостингу ж пропонує простоту за рахунок обмеженого контролю.

Чиста структура каталогів

Акуратна налаштування в cPanel дозволяє тримати застосунок та публічну кореневу директорію поруч одна з одною:

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

Запити надходять до my-node-app через Apache та Passenger, а public_html залишається без коду сервера.

Кінцевий перелік перевірок

Перш ніж вважати розгортання завершеним, переконайтеся, що:

для облікового запису увімкнено Node.js
доступний Application Manager
обрана сумісна версія Node.js
файли проекту завантажені поза дирекцією public_html
є файл package.json
операція npm install завершилась без помилок
налаштування файлу запуску є правильними
сервер прослуховує на process.env.PORT
налаштовані змінні середовища
середовище встановлено як Production
додаток було перезапущено після останніх змін
домен відкривається у браузері

у журналах немає помилок запуску

Підсумки

У сервісах спільного хостингу cPanel інструмент Application Manager з Passenger є надійним рішенням, яке дозволяє запускати додатки Express та API без прав root. Дозвольте Passenger керувати портом, перезапускати додаток після кожних змін, а у разі проблем вручну запустити додаток та переглянути журнали перед зміною конфігурації.

Усі статті Надіслати бриф