Sidecar на Node.js
Backend NeoTavern — это сервер Fastify, и в десктоп-приложении он работает как встроенный sidecar на Node.js: самодостаточный бинарник Node.js 24, упакованный рядом с оболочкой.
Зачем sidecar
Упаковка backend как отдельного процесса держит оболочку тонкой, а backend — настоящим:
- Backend — это то же приложение Fastify 5, которое запускает самостоятельная установка, поэтому десктоп и сервер ведут себя одинаково.
- Node.js и SQLite скомпилированы в дистрибутив, поэтому первому запуску не нужны ни npm install, ни терминал.
- Граница процесса означает, что сбой или зависание backend не может уронить цикл событий оболочки, а оболочка может обеспечивать гарантии жизненного цикла.
Запуск
При запуске оболочка порождает исполняемый файл sidecar и ждёт готовности перед открытием webview. Backend:
- слушает только случайный свободный порт на
127.0.0.1; - создаёт базу данных SQLite и выполняет ожидающие миграции схемы в каталоге данных, снимая резервную копию перед ожидающими миграциями;
- обслуживает продакшн-веб-ресурсы и API.
Первый запуск полностью автоматический: каталог данных, база данных, встроенные темы и стартовый персонаж настраиваются без какого-либо участия пользователя.
Корректное завершение
Завершение совместное и упорядоченное:
- Оболочка получает событие закрытия и говорит backend остановиться.
- Backend перестаёт принимать новые соединения, завершает текущую работу в пределах своего дедлайна и корректно закрывает базу данных.
- Sidecar выходит, и оболочка выходит.
Неожиданное завершение backend обнаруживается оболочкой и сообщается как
выход с ошибкой, никогда не оставляя процесс backend осиротевшим молча.
Поэтому после закрытия окна в системе никогда не остаётся посторонний
процесс neotavern-server.
Упаковка и проверка
Sidecar собирается для каждой целевой платформы. Нативные аддоны
(better-sqlite3, Sharp) и продакшн-веб-ресурсы подготавливаются на том же
целевом раннере и упаковываются вместе с исполняемым файлом; перенос
подготовленных ресурсов между операционными системами не поддерживается.
Смоук-гейт в CI запускает упакованный sidecar в безголовом режиме на каждой
платформе, проверяя настоящий исполняемый файл Node, SQLite, Sharp,
упакованную SPA, диагностику и отсутствие оставшихся процессов.
Портативный вариант
Портативная сборка Windows использует ту же схему sidecar: основной
исполняемый файл, исполняемый файл sidecar, маркер portable.flag и папку
resources/. Флаг переключает корень данных на локальную папку data/
рядом с приложением. Оболочка нормализует пути ресурсов Windows перед
передачей их упакованному бинарнику Node.
О форматах и опыте первого запуска см. Упаковка; об оболочке, управляющей этим процессом, — Оболочка Tauri.