Главная / Статьи / Развертывание приложения 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:

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, режим работы приложения и другие необходимые значения; нedefинированная переменная, приводящая к сбою при запуске, также вызывает ошибку 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 управляет портом, перезагружается после каждых изменений, а при возникновении проблем — запускается вручную и логи анализируются перед изменением конфигурации.

Все статьи Прислать бриф