Sails.js на Debian 11: установка и настройка

Введение

Sails.js — полнофункциональный фреймворк для Node.js поверх Express и socket.io. Он реализует паттерн MVC и ориентирован на создание масштабируемых и сервисно-ориентированных приложений, удобен для разработки data‑driven API и современных веб‑приложений уровня предприятия. В этой статье показаны практические шаги по установке и развёртыванию Sails.js на Debian 11 (Bullseye) с примерами конфигураций и рекомендациями по эксплуатации.

Ключевые понятия в одну строку:

Sails.js — Node.js MVC фреймворк с автогенерацией REST API.
Waterline — ORM Sails для работы с разными СУБД (MySQL, PostgreSQL, MongoDB и т. д.).

Требования

Операционная система: Debian 11 (Bullseye)
Права root или sudo
Рекомендовано: непривилегированный пользователь для запуска приложения

Важно: в примерах используется порт по умолчанию 1337 и Node.js LTS 16.x. При необходимости замените эти значения на свои.

Установка инструментов разработки

Обновите списки пакетов:

sudo apt update

Установите базовые инструменты сборки (build-essential, компиляторы):

sudo apt install curl build-essential gcc g++ make -y

Подтвердите установку, если потребуется.

Установка Node.js LTS и Yarn

Мы используем официальный скрипт NodeSource для Node.js 16.x (LTS). Этот метод добавляет APT‑репозиторий и устанавливает стабильную LTS‑ветвь.

Добавьте репозиторий NodeSource и установите зависимости:

curl -fsSL https://deb.nodesource.com/setup_16.x | bash -

Добавьте GPG‑ключ и репозиторий Yarn:

curl -sL https://dl.yarnpkg.com/debian/pubkey.gpg | gpg --dearmor | sudo tee /usr/share/keyrings/yarnkey.gpg >/dev/null

echo "deb [signed-by=/usr/share/keyrings/yarnkey.gpg] https://dl.yarnpkg.com/debian stable main" | sudo tee /etc/apt/sources.list.d/yarn.list

Обновите кэши APT и установите nodejs и yarn:

sudo apt update && sudo apt install nodejs yarn -y

Проверьте версии:

node --version
yarn --version

Ожидаемый вывод (пример):

# nodejs version
v16.13.1

# yarn version
1.22.15

Совет: если команда sails будет установлена глобально через yarn и не найдена в PATH при запуске из systemd, узнайте её путь командой which sails.

Установка Sails.js глобально

Для установки Sails.js используйте yarn global:

sudo yarn global add sails

Проверьте версию:

sails --version

Пример версии: 1.5.0.

Также можно просмотреть справку по команде:

sails --help

(Вывод доступных опций и команд останется тем же, что и при установке.)

Создание первого проекта Sails.js

Рекомендуется создавать проекты и запускать приложения от непривилегированного пользователя.

Переключитесь на вашего пользователя (замените username):

su - username

Создайте приложение (в примере — testapp):

sails new testapp

При выборе шаблона вас попросят выбрать опции:

Введите 1 для полного веб‑шаблона с базовыми страницами и аутентификацией.
Введите 2 для пустого классического приложения Sails.

Создание нового приложения Sails.js

Перейдите в каталог и запустите приложение в режиме разработки:

cd testapp/
sails lift

Если всё в порядке, в логах вы увидите сообщение о запуске в среде development и порте 1337.

Запуск приложения Sails.js в терминале

Откройте в браузере http://192.168.1.50:1337/ (замените IP на свой) — вы увидите дефолтную страницу Sails.

Дефолтная главная страница Sails.js

Остановите приложение в терминале комбинацией Ctrl+C.

Настройка systemd‑сервиса для Sails.js

Для постоянного запуска приложения рекомендуется создать systemd‑сервис. Ниже — пример юнита с улучшениями: определение пользователя, рабочей директории, переменных окружения и логирования.

Создайте файл сервиса (замените johndoe и путь):

sudo nano /etc/systemd/system/testapp.service

Пример содержимого сервиса:

[Unit]
Description=Sails.js application - testapp
After=network.target

[Service]
Type=simple
User=johndoe
Group=www-data
WorkingDirectory=/home/johndoe/testapp
Environment=NODE_ENV=production
ExecStart=/usr/local/bin/sails lift --prod
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal
LimitNOFILE=4096

[Install]
WantedBy=multi-user.target

Важно:

Проверьте путь до бинарника sails: which sails (в некоторых системах путь может быть /usr/bin or /home/username/.yarn/bin/sails). Если путь отличается — замените ExecStart.
Если вы используете yarn глобально в домашнем каталоге пользователя, лучше явно указывать полный путь к sails.

Примените новую конфигурацию systemd и запустите сервис:

sudo systemctl daemon-reload
sudo systemctl start testapp
sudo systemctl enable testapp

Проверка статуса и просмотр логов:

sudo systemctl status testapp
journalctl -u testapp -f

Статус systemd сервиса Sails.js

Совет: для автоматического управления процессами и кластеризации можно рассмотреть pm2 как альтернативу systemd, однако systemd хорошо интегрируется с современными дистрибутивами и системным мониторингом.

Настройка Nginx как обратного прокси

Nginx часто используется перед Sails.js для обработки TLS, статики и оптимизации соединений websocket.

Установите Nginx:

sudo apt install nginx -y

Создайте конфигурацию серверного блока:

sudo nano /etc/nginx/sites-available/testapp

Пример конфигурации (замените dev.example.io на ваш домен или IP):

server {
  listen       80;
  server_name  dev.example.io;

  location / {
    proxy_pass        http://localhost:1337/;
    proxy_http_version 1.1;
    proxy_set_header  Upgrade $http_upgrade;
    proxy_set_header  Connection "upgrade";
    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  X-Forwarded-Proto $scheme;
    proxy_buffering   off;
  }
}

Объяснение важных опций:

proxy_set_header Upgrade/Connection — необходимы для поддержки WebSocket (socket.io).
proxy_buffering off — рекомендуется для real‑time приложений.

Активируйте сайт и проверьте конфигурацию:

sudo ln -s /etc/nginx/sites-available/testapp /etc/nginx/sites-enabled/
sudo nginx -t

Перезапустите Nginx:

sudo systemctl restart nginx

Nginx в роли обратного прокси для Sails.js

Настройка прав: дайте группе www-data доступ к файлам приложения (замените имя пользователя и путь):

cd /home/johndoe/
sudo chown -R johndoe:www-data testapp
sudo chmod -R g+rw testapp

Эти команды помогут Nginx (www-data) читать и обслуживать статические файлы, если это требуется.

(Опционально) Настройка HTTPS с certbot (Let’s Encrypt):

sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d dev.example.io

Следуйте подсказкам certbot для получения и автоматического обновления сертификатов.

Проверка приложения через домен

На локальной машине отредактируйте /etc/hosts (для тестирования без DNS):

sudo nano /etc/hosts

Добавьте строку (замените IP и домен):

192.168.1.50  dev.example.io

Откройте в браузере http://dev.example.io/ — вы должны увидеть индексную страницу Sails.

Интерфейс Sails.js приложения

Пример регистрации нового пользователя и панели управления приведён для полноты картины.

Пример аутентификации в Sails.js

Панель пользователя Sails.js

Критерии приёмки

Приложение успешно поднимается командой sudo systemctl start testapp и остаётся active.
Nginx корректно проксирует запросы на http://localhost:1337/ и страницы доступны по домену.
WebSocket соединения (socket.io) проходят через Nginx.
Логи доступны через journalctl -u testapp -f.

Тесты и сценарии приёмки

Запуск приложения: systemctl start/stop/restart — приложение должно правильно инициироваться и завершаться.
Проверка статуса на нагрузке: отправить несколько параллельных HTTP и WebSocket запросов (ручной smoke‑test).
Обновление кода: деплой новой версии и плавный перезапуск сервиса без потери соединений.
Нагрузочный corner case: проверить поведение при отключенном бэкенде БД — приложение не должно падать при некритичной ошибке.

Отладка и типичные проблемы

Приложение не запускается через systemd, но запускается вручную:

Проверьте путь до sails: which sails и подставьте полный путь в ExecStart.
Проверьте переменные окружения (Environment или файл .env).

Permission denied при доступе к файлам:

Проверьте владельца каталога и права: ls -la /home/johndoe/testapp.
Обеспечьте, чтобы группа www-data имела доступ, если Nginx должен читать файлы.

Port 1337 уже занят:

Найдите процесс: sudo ss -ltnp | grep 1337.
Измените порт в конфигурации Sails (config/local.js или переменная окружения PORT).

WebSocket не работает через Nginx:

Убедитесь, что в конфигурации Nginx присутствуют заголовки Upgrade и Connection для websocket.
Проверьте проксирование и отсутствие промежуточного кеширования.

Логи systemd:

journalctl -u testapp -b --no-pager | tail -n 200

Ошибка «module not found» при запуске сервисом:

Проверьте, что все зависимости установлены (yarn install в каталоге проекта).
Если зависимости установлены глобально в домашней директории пользователя, убедитесь, что systemd видит тот же PATH или используйте абсолютный путь в ExecStart.

Безопасность и рекомендации по эксплуатации

Запускайте приложение от непривилегированного пользователя.
Обновляйте Node.js и зависимости по графику безопасности.
Ограничьте доступ к порту 1337 в брандмауэре (например, UFW) — разрешайте доступ только localhost, если используете Nginx:

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable

Защитите панели администратора, используйте HTTPS и HSTS.
Логи: настройте ротацию логов или агрегируйте в централизованный лог‑шиппер.

Альтернативные подходы

PM2: менеджер процессов для Node.js с поддержкой кластеров и zero‑downtime перезапуска.
Docker: контейнеризация приложения и запуск через systemd/unit в контейнерах для изоляции окружения.
CI/CD: интеграция сборки и развёртывания (GitHub Actions, GitLab CI) для автоматического деплоя.

Справочник конфигураций и команд (cheat sheet)

Установка зависимостей и инструментов:

sudo apt update
sudo apt install curl build-essential gcc g++ make -y
curl -fsSL https://deb.nodesource.com/setup_16.x | bash -
sudo apt install nodejs yarn -y

Установка Sails.js:

sudo yarn global add sails
sails --version

Создание приложения:

sails new testapp
cd testapp/
sails lift

Systemd управление:

sudo systemctl daemon-reload
sudo systemctl start testapp
sudo systemctl enable testapp
sudo systemctl status testapp
journalctl -u testapp -f

Nginx (проверка):

sudo nginx -t
sudo systemctl restart nginx

Роль‑ориентированные контрольные списки

Для разработчика:

[ ] Создать проект и запустить локально sails lift.
Покрыть критические маршруты тестами.
Проверить поддержку WebSocket и REST API.

Для DevOps:

Настроить systemd unit с NODE_ENV=production.
Настроить Nginx и HTTPS.
Настроить мониторинг и логирование.

Для администратора безопасности:

Ограничить доступ к порту 1337 через брандмауэр.
Подключить автоматическое обновление сертификатов.
Обеспечить резервное копирование конфигураций и секретов.

Совместимость и советы по миграции

Sails.js 1.x стабилен для Node.js 12+; рекомендуется LTS (в статье — 16.x).
При миграции между мажорными версиями Sails проверяйте changelog и выполняйте тесты API.
Waterline поддерживает разные СУБД — при смене СУБД проверьте адаптер и миграции данных.

Короткое резюме

Вы установили и настроили Sails.js на Debian 11: подготовили систему, установили Node.js и Yarn, глобально установили Sails, создали приложение, оформили systemd‑сервис и настроили Nginx как обратный прокси. Включены рекомендации по безопасности, отладке и варианты развёртывания.

Важные точки: