Node.js на сервере: установка, запуск и настройка
Node.js на сервере ставят из репозитория NodeSource, приложение запускают через pm2 или systemd, а наружу отдают через nginx с proxy_pass на 127.0.0.1:3000. Ошибки чаще всего связаны с занятым портом, правами на файлы и отсутствием автозапуска после перезагрузки.
Что такое Node.js на сервере и как он работает
Node.js это среда выполнения JavaScript вне браузера. На сервере приложение запускается как обычный процесс, слушает TCP-порт и отвечает на HTTP-запросы. Один процесс обслуживает один порт, поэтому несколько приложений на одной машине запускают на разных портах. Порты ниже 1024 может открыть только root, поэтому приложение слушает порт выше 1024 на 127.0.0.1, например 3000. Наружу его публикует nginx через proxy_pass. Такая схема позволяет держать Node.js без прав root и перезапускать приложение без остановки веб-сервера.
Установка Node.js на Ubuntu 24.04
В репозитории Ubuntu 24.04 лежит Node.js 18: пакет nodejs версии 18.19.1, а npm ставится отдельным пакетом npm. Для Node.js 24 подключают репозиторий NodeSource скриптом setup_24.x, затем ставят пакет nodejs. В пакете NodeSource уже есть npm и npx, отдельная установка не нужна. После установки проверьте версии командой node -v и npm -v. Если Node.js поставлен через nvm, он лежит в домашнем каталоге пользователя и не виден root, cron и службам systemd: им нужен полный путь к бинарнику node.
curl -fsSL https://deb.nodesource.com/setup_24.x -o nodesource_setup.sh
sudo bash nodesource_setup.sh
sudo apt install -y nodejs
node -v
npm -v
Зависимости и сборка проекта
Зависимости ставят от владельца сайта, без sudo, из каталога проекта. Команда npm ci ставит пакеты строго по package-lock.json, а npm run build собирает проект, если в package.json есть такой скрипт. На VPS с 1 ГБ памяти без swap сборка может упасть с JavaScript heap out of memory. Помогает swap-файл или ограничение кучи через NODE_OPTIONS=--max-old-space-size=1024.
cd /var/www/example.com
npm ci
npm run build
Запуск приложения через pm2
pm2 ставится глобально командой sudo npm install -g pm2, при Node.js из NodeSource бинарник оказывается в /usr/bin/pm2. Запуск с именем процесса: pm2 start server.js --name app. Логи пишутся в ~/.pm2/logs/app-out.log и ~/.pm2/logs/app-error.log, смотреть их удобно командой pm2 logs app, перезапуск делает pm2 restart app. После перезагрузки сервера pm2 сам не поднимается. Команда pm2 startup systemd печатает строку с sudo, её выполняют один раз, а pm2 save записывает список процессов в ~/.pm2/dump.pm2.
sudo npm install -g pm2
pm2 start server.js --name app
pm2 logs app
pm2 restart app
pm2 startup systemd
pm2 save
Автозапуск через systemd без pm2
Без pm2 приложение держит служба systemd. В unit-файле задают ExecStart=/usr/bin/node /var/www/example.com/server.js, User=deploy, WorkingDirectory=/var/www/example.com и Restart=always. Переменные окружения передают через Environment= или EnvironmentFile=. После правки unit-файла нужен sudo systemctl daemon-reload, затем sudo systemctl restart app. Путь к node указывают полный: служба не читает профиль пользователя и не видит Node.js из nvm.
[Unit]
Description=Node.js app
After=network.target
[Service]
User=deploy
WorkingDirectory=/var/www/example.com
ExecStart=/usr/bin/node /var/www/example.com/server.js
Restart=always
Environment=NODE_ENV=production
[Install]
WantedBy=multi-user.target
Проксирование через nginx
Сайты nginx лежат в /etc/nginx/sites-available/ и включаются симлинком в /etc/nginx/sites-enabled/. В location с proxy_pass на 127.0.0.1:3000 ставят proxy_set_header Host $host;, иначе приложение видит в заголовке Host адрес из proxy_pass. Для WebSocket добавляют proxy_http_version 1.1;, proxy_set_header Upgrade $http_upgrade; и proxy_set_header Connection "upgrade";. Конфиг проверяют командой sudo nginx -t, применяют через sudo systemctl reload nginx. При ошибке в конфиге nginx продолжает работать со старым и не рвёт соединения.
server {
listen 80;
server_name example.com;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
Права на файлы и безопасность
Владелец файлов сайта это пользователь, который деплоит. Каталоги держат права 755, файлы 644, запись нужна только туда, куда пишет само приложение. chown -R www-data на весь сайт позволяет процессу переписать собственный код, и при взломе этим пользуются первым делом. Права по всему пути показывает namei -l <путь>. nginx в Ubuntu 24.04 работает без профиля AppArmor, SELinux не используется, поэтому причины 403 и 502 ищут в правах и конфиге.
namei -l /var/www/example.com/server.js
sudo chown -R deploy:deploy /var/www/example.com
find /var/www/example.com -type d -exec chmod 755 {} \;
find /var/www/example.com -type f -exec chmod 644 {} \;
Типичные проблемы: EADDRINUSE, 502 и таймауты
Если порт занят, Node.js падает с Error: listen EADDRINUSE: address already in use 127.0.0.1:3000. Кто держит порт, показывает sudo ss -ltnp, после чего лишний процесс останавливают или меняют порт в конфиге приложения. Ответ 502 означает, что nginx не достучался до бэкенда: приложение не запущено, слушает другой порт или другой адрес. Проверка curl -I http://127.0.0.1:3000/ с сервера показывает, отвечает ли приложение напрямую. Таймаут ответа бэкенда по умолчанию 60 секунд, для proxy_pass его меняют директивой proxy_read_timeout.
sudo ss -ltnp
curl -I http://127.0.0.1:3000/
pm2 logs app
Частые ошибки
-
Приложение запускают от root или ставят Node.js через nvm, а потом служба systemd не находит node.
Ставьте Node.js из NodeSource и указывайте в unit-файле полный путь
/usr/bin/node. Приложение запускайте от отдельного пользователя. -
В location с proxy_pass не задан
proxy_set_header Host $host;, и приложение видит в заголовке Host адрес 127.0.0.1:3000.Добавьте в location строку
proxy_set_header Host $host;и перезагрузите nginx черезsudo systemctl reload nginx. -
После перезагрузки сервера приложение не поднимается, потому что pm2 не добавлен в автозапуск.
Выполните
pm2 startup systemd, затем команду с sudo, которую он напечатает, иpm2 save. -
Каталог сайта отдан пользователю www-data целиком через
chown -R www-data.Оставьте владельцем пользователя деплоя, а www-data дайте только чтение. Запись нужна лишь в каталоги, куда пишет само приложение.
Deploykin
Как это делается в Deploykin
В Deploykin приложение на Node.js создаётся как сайт типа «Приложение»: nginx проксирует запросы на его порт, SSL выпускается в один клик. Процесс запускает демон: укажите команду и пользователя, конфигурацию Supervisor панель соберёт сама и будет держать процесс запущенным.
7 дней бесплатно на тарифе Про, без привязки карты.
Вопросы и ответы
Какую версию Node.js ставить на Ubuntu 24.04?
В репозитории Ubuntu 24.04 лежит Node.js 18.19.1. Для Node.js 24 подключите репозиторий NodeSource скриптом setup_24.x и поставьте пакет nodejs, npm и npx войдут в него.
Почему приложение падает с ошибкой EADDRINUSE?
Порт уже занят другим процессом. Найдите его командой sudo ss -ltnp и остановите лишний процесс или задайте приложению другой порт.
Зачем нужен nginx, если Node.js сам принимает запросы?
nginx слушает порт 80 и 443, завершает TLS и отдаёт статику, а запросы к приложению передаёт через proxy_pass на 127.0.0.1:3000. Приложение при этом работает без прав root.
Почему nginx отдаёт 502 Bad Gateway?
nginx не получил ответ от бэкенда: приложение не запущено, слушает другой порт или другой адрес. Проверьте curl -I http://127.0.0.1:3000/ и логи pm2 logs app.
Нужно ли добавлять fastcgi_param HTTP_COOKIE для PHP рядом с Node.js?
Нет. nginx передаёт заголовки запроса в PHP-FPM сам, fastcgi_pass_request_headers on включён по умолчанию, и строки вида fastcgi_param HTTP_COOKIE $http_cookie; не нужны.
Всё по теме Node.js
Руководства по теме8
- Как установить Node.js на сервер Ubuntu 24.04
- Node index js: запуск приложения на сервере Ubuntu 24.04
- Node.js Express на сервере Ubuntu 24.04: настройка и запуск
- Как обновить Node.js на сервере Ubuntu 24.04
- Запуск Node.js скриптов на сервере Ubuntu 24.04
- Как установить Node.js через nvm и запустить приложение на Ubuntu 24.04
- Как установить Node.js 24 LTS и запустить приложение на Ubuntu 24.04
- Удаление Node.js и npm с Ubuntu 24.04