Node 사이드카
NeoTavern의 백엔드는 Fastify 서버이며, 데스크톱 앱에서는 내장 Node.js 사이드카로 실행됩니다. 셸 옆에 패키징된 자체 포함 Node.js 24 바이너리입니다.
사이드카인 이유
백엔드를 별도 프로세스로 번들하면 셸이 가볍고 백엔드가 진짜로 유지됩니다.
- 백엔드는 자체 호스팅 설치가 실행하는 것과 같은 Fastify 5 애플리케이션이므로 데스크톱과 서버 동작이 동일하게 유지됩니다.
- Node.js와 SQLite가 배포판에 컴파일되어 있으므로 첫 실행에 npm 설치와 터미널이 필요하지 않습니다.
- 프로세스 경계 덕분에 백엔드의 크래시나 멈춤이 셸의 이벤트 루프를 무너뜨릴 수 없고, 셸이 라이프사이클 보장을 강제할 수 있습니다.
시작
실행 시 셸은 사이드카 실행 파일을 실행하고 웹뷰를 열기 전에 준비를 기다립니다. 백엔드는:
127.0.0.1의 무작위 여유 포트에서만 수신합니다;- 데이터 디렉터리에 SQLite 데이터베이스를 만들고 보류 중인 스키마 마이그레이션을 실행하며, 보류 중인 마이그레이션 전에 백업을 만듭니다;
- 프로덕션 웹 에셋과 API를 제공합니다.
첫 실행은 완전히 자동입니다. 데이터 디렉터리, 데이터베이스, 번들 테마, 시작 캐릭터가 사용자 상호작용 없이 설정됩니다.
정상 종료
종료는 협력적이고 순서가 있습니다.
- 셸이 닫기 이벤트를 받고 백엔드에 중지를 알립니다.
- 백엔드는 새 연결 수신을 멈추고, 마감 안에서 진행 중인 작업을 마치며, 데이터베이스를 깨끗하게 닫습니다.
- 사이드카가 종료되고 셸이 종료됩니다.
예상치 못한 백엔드 종료는 셸이 감지해 오류 종료로 보고하며, 조용히
백엔드 프로세스를 고아로 남기지 않습니다. 따라서 창을 닫은 후 앱이
떠돌이 neotavern-server 프로세스를 남기는 일이 없습니다.
번들링과 검증
사이드카는 대상 플랫폼별로 빌드됩니다. 네이티브 애드온
(better-sqlite3, Sharp)과 프로덕션 웹 에셋이 같은 대상 러너에서
준비되어 실행 파일과 함께 패키징됩니다. 운영 체제 간에 준비된
리소스를 옮기는 것은 지원되지 않습니다. 스모크 게이트가 CI에서 각
플랫폼의 패키징된 사이드카를 헤드리스로 실행해 실제 Node 실행 파일,
SQLite, Sharp, 패키징된 SPA, 진단, 잔여 프로세스 없음을
검증합니다.
포터블 변형
포터블 Windows 빌드는 같은 사이드카 구조를 실행합니다. 메인 실행
파일, 사이드카 실행 파일, portable.flag 마커, resources/
폴더입니다. 플래그가 데이터 루트를 애플리케이션 옆의 로컬 data/
폴더로 전환합니다. 셸은 패키징된 Node 바이너리에 넘기기 전에 Windows
리소스 경로를 정규화합니다.