WardPane
Скачать

Node.js

Обработчик Node.js запускает ваше приложение (Express, Fastify, Next.js, Nuxt, API-сервер или что угодно ещё, что слушает порт) и передаёт ему запросы к сайту. Среду выполнения Node.js, менеджер процессов PM2, песочницу systemd, HTTPS, проверки защиты и раздачу статических файлов обеспечивает WardPane.

Как всё устроено

посетитель -> WardPane на 80/443 -> проверки защиты -> файл есть в public/? -> отдаётся напрямую
                                                    -> иначе                -> ваше приложение на 127.0.0.1:<port>
  • Каждому сайту Node.js панель назначает свой порт из диапазона от 10000 до 19999. Приложение слушает его на 127.0.0.1, так что снаружи до него можно добраться только через WardPane.
  • Приложения работают под PM2. У каждого владельца один демон PM2 в юните systemd wardpane-pm2@<owner>.service, и каждый сайт Node.js этого владельца работает в нём отдельным приложением PM2.
  • Приложение работает от имени владельца сайта (по умолчанию www-root) внутри песочницы systemd.

Структура папок

Папка сайта и есть папка приложения. Положите туда package.json рядом с папкой public/:

/var/www/www-root/data/www/example.com/
  package.json
  package-lock.json
  server.js
  node_modules/
  public/            отдаются напрямую как файлы
    favicon.ico
    css/app.css

Напрямую WardPane отдаёт только файлы из public/. Ваш код, node_modules и файлы .env лежат в папке сайта, и скачать их посетитель не может.

У сайта, созданного до версии 2.0, папка приложения находится в /var/www/<domain>, а package.json лежит рядом с её public/.

Настройка приложения

  1. Создайте сайт с обработчиком Node.js (или переключите существующий сайт на его вкладке Обработчик). В окне создания можно сразу выбрать версию Node.js.
  2. Загрузите приложение в папку сайта по SFTP или через git clone из терминала.
  3. На вкладке Обработчик выберите, как запускается приложение, и добавьте переменные окружения.
  4. Нажмите Сохранить изменения. Панель назначит порт, при необходимости скачает Node.js и запустит приложение.
  5. Нажмите npm install, чтобы установить зависимости, затем Перезапустить.

Карточка «Приложение Node.js» вверху вкладки Обработчик показывает состояние приложения (работает, остановлено, сбой, запускается), точную версию Node.js и порт.

Настройки

Все они находятся на вкладке Обработчик сайта.

Версия Node.js

Выберите мажорную версию Node.js. WardPane 2.0 предлагает 20, 22, 24 и 26; новые сайты получают 24. Поддержка Node.js 20 закончилась в апреле 2026 года, поэтому для новых приложений берите 22 или новее.

Свежий выпуск выбранной ветки скачивается, когда он впервые понадобится какому-то сайту, см. Среды выполнения. Ветка задаётся для каждого сайта отдельно, так что два приложения одного владельца могут работать на разных версиях Node.js.

Команда запуска

Запустить приложение можно двумя способами:

  • Скрипт npm: скрипт из package.json, например start. Нажмите Прочитать package.json, чтобы увидеть скрипты приложения и выбрать один.
  • Файл запуска: файл JavaScript, который запускает сервер, например server.js, путь относительно папки сайта. Подходят файлы .js, .mjs и .cjs.

Переменные окружения

Можно добавить до 20 переменных. Имена состоят из букв, цифр и _ и начинаются с буквы или _; значение может быть длиной до 4096 символов.

Некоторые переменные панель задаёт сама:

Переменная Значение
PORT Порт, который панель назначила сайту. Ваше приложение должно слушать его.
HOST 127.0.0.1. Ваше приложение должно слушать этот адрес.
NODE_ENV production, если вы не задали другое значение.

PORT, HOST, PATH, HOME и PM2_HOME переопределить нельзя. Панель хранит значения открытым текстом, и прочитать их может любой, у кого есть доступ к настройкам сайта.

Порт

Панель назначает порт, когда сайт впервые становится сайтом Node.js. Ни у одного другого сайта такого порта не будет, и он не меняется, даже если переключить сайт на другой обработчик и обратно. Поле доступно только для чтения.

Отдавать файлы из public/ напрямую

По умолчанию включено. Файлы, которые есть в public/, отдаёт сам WardPane (с ETag и докачкой, как на статическом сайте), а всё остальное уходит в приложение. Выключите, если приложение должно видеть каждый запрос, включая запросы к статическим файлам.

Ограничения

Настройка По умолчанию Диапазон
Лимит памяти, МБ 512 от 64 до 16384
Лимит CPU, % 100 (одно ядро) от 10 до 800

Когда приложение выходит за лимит памяти, PM2 его перезапускает. Юниту PM2 владельца systemd выставляет лимит памяти и квоту CPU, равные сумме лимитов его приложений (плюс немного для самого PM2).

Запретить исходящие соединения

С этой настройкой приложение может обращаться только к этому серверу. Запросы к внешним API, отправка почты и скачивание работать не будут. Все приложения Node.js одного владельца работают в одном демоне PM2, поэтому запрет действует, только когда он включён у всех приложений Node.js этого владельца.

PM2 из терминала

PM2 хранит своё состояние в домашней папке владельца (/var/www/<owner>/data/.pm2), поэтому обычные команды работают из терминала этого владельца, например в терминале в браузере:

pm2 list                    # приложения владельца, названные по их доменам
pm2 restart example.com     # перезапустить одно приложение
pm2 logs example.com        # следить за его выводом

Версию, команду запуска, окружение и лимиты меняйте в панели. Панель собирает конфигурацию PM2 заново из своих настроек и затрёт правки, сделанные вручную.

Прокси

Запросы, которые не отдаются из public/, уходят на http://127.0.0.1:<port>:

  • Сначала они проходят все проверки защиты сайта (Bot Fight, гео, лимиты запросов, обязательные параметры ссылки, пароль сайта), в том же месте, где сайт на PHP передал бы запрос в PHP.
  • Тела запросов и ответов передаются потоком.
  • X-Forwarded-For, X-Real-IP, X-Forwarded-Proto и X-Forwarded-Host передают настоящий адрес посетителя, схему и хост, в том числе за Cloudflare. Если клиент сам присылает эти заголовки (или Forwarded), они отбрасываются. В Express включите доверие к локальному прокси через app.set('trust proxy', 'loopback'), и IP посетителя окажется в req.ip.
  • WebSocket работают. Запрос на upgrade проходит те же проверки защиты, что и любой другой запрос, прежде чем дойти до приложения.
  • Hop-by-hop заголовки удаляются, а X-Powered-By убирается из ответов приложения.
  • Если приложение упало или не слушает свой порт, посетители видят простую страницу 502 Bad Gateway без сведений о сервере. Если приложение не начало отвечать за 2 минуты, ответ будет 504. Причина попадает в журнал панели не чаще раза в минуту на сайт.
  • Тела запросов до 100 МБ передаются приложению; на запросы крупнее приходит 413.

Перезапуск и npm install

В карточке «Приложение Node.js» две кнопки:

  • Перезапустить перезапускает приложение в PM2.
  • npm install ставит зависимости: npm ci, если в папке есть package-lock.json, иначе npm install. Команда выполняется от имени владельца, в песочнице, с версией Node.js этого сайта и прерывается через 10 минут. Вывод попадает в npm-install.log сайта.

Журналы

Карточка Журналы на вкладке Обработчик показывает три файла: Вывод (node-out.log), Ошибки (node-error.log) и npm install (npm-install.log).

Структура Где журналы
Новые сайты (2.0) /var/www/<owner>/data/logs/<domain>-node-out.log, <domain>-node-error.log, <domain>-npm-install.log
Сайты до версии 2.0 /var/www/<domain>/logs/node-out.log, node-error.log, npm-install.log

Среды выполнения и безопасность

  • Сборки Node.js скачиваются с https://nodejs.org/dist/ (linux-x64 или linux-arm64) и перед распаковкой сверяются с опубликованным SHASUMS256.txt. Хранятся они в /opt/wardpane-runtimes. Версию, которой больше не пользуется ни один сайт, панель удаляет.
  • PM2 ставит install.sh, версия зафиксирована.
  • Код из среды выполнения никогда не запускается от root. Root-помощник только скачивает и распаковывает её, а приложения и npm работают от имени владельца.
  • Юнит PM2 работает в песочнице systemd: система доступна только для чтения, записывать можно только в папки владельца, новые привилегии запрещены, /tmp свой.

Развёртывание приложения на Express

  1. Создайте сайт api.example.com с обработчиком Node.js и версией 24. Сначала направьте его DNS на сервер, тогда сертификат выпустится сразу.

  2. В приложении слушайте порт и адрес, которые даёт панель:

    const express = require('express');
const app = express();
app.set('trust proxy', 'loopback');
app.get('/api/hello', (req, res) => res.json({ hello: req.ip }));
app.listen(process.env.PORT, process.env.HOST);

  3. Добавьте скрипт запуска в package.json:

    {
  "name": "api",
  "scripts": { "start": "node server.js" },
  "dependencies": { "express": "^4.21.0" }
}

  4. Загрузите package.json, package-lock.json, server.js и папку public/ в папку сайта (для владельца по умолчанию: /var/www/www-root/data/www/api.example.com).

  5. На вкладке Обработчик выберите Скрипт npm и start (или нажмите Прочитать package.json и выберите его), затем Сохранить изменения.

  6. Нажмите npm install и дождитесь завершения (следите за журналом npm install).

  7. Нажмите Перезапустить. Карточка состояния должна показать, что приложение работает; откройте https://api.example.com/api/hello.

Если сайт показывает 502, загляните в журнал Ошибки. Чаще всего не хватает зависимости, в скрипте запуска опечатка или приложение слушает фиксированный порт вместо PORT.