Размешчэнне прыкладку Node.js на cPanel Shared Hosting з аддонам Passenger

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

Што патрэбна ваша аблікованая установка

Перад тым, як чаго-небудзь заваносіць, пераканайцеся, што аблікованне мае наступнае:

• Падтрымка Node.js
• cPanel Application Manager
• Passenger
• Доступ через тэрмінал чы SSH
• npm
• Домэн чы паддомэн, з якога будзе служыць аплікацыя
• Доступ да базы дадзеных, якшо аплікацыя яго патрабуе

Якщо Адміністратор застосункŭ не існуе, папрабавце, каб ён увёўкнуў Node.js і Passenger. У хостах, які выкарыстоўваюць CloudLinux, гэты інструмент можа мець іншую назву.

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

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

Крок 2: Аплодзіце застосунак

Аплодзіце проект за дапамою Менеджера файлŭ або 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

Эта процедура запускае прызначаныя залежнасці на сервера. З наявнасцю файлу блокавання, 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.

Логі

Логія прыёмніка або праграмы 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
• Є Адміністратар прыемлень
• Выбрана сумесная версія Node.js
• Файлы проекта заванесены за межы папкі public_html
• Існуе файл package.json
• Каманда npm install завершылася без адных бядаў
• Налажаны файл для запуску
• Сервер праслухоўвае на process.env.PORT
• Настроеныя зменныя сэрвера
• Режым працы заданы як Production
• Проект перазапусцаны пасля последніх змян
• Домэн праверна адкрываецца ў браузеры

У логах няма паказанняя прычын запуску

Заключэнне

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