behind_glass/README-서버실행.md

Behind Glass 서버 배포본

• 버전: 2026-10-09 / 소스 7d82e3b1a9f083376bfd0b916568b1472dcb7f84
• 최신 세로 시점 보정, 사진 위치 조절, 홈 확인, 새 사진 입력 시 조작값 초기화 포함.
• dist는 Fastify 집계가 활성화된 서버용 빌드입니다. 바로 사용해도 됩니다.
• Vite/TypeScript 원본, Fastify/SQLite 코드, lockfile, 라이선스, 운영 예시를 포함합니다. public/참고 이미지 중 dist와 동일한 파일은 중복 보관하지 않으며 복원 스크립트가 원래 경로로 복사합니다. Blender 원본 제작 파일은 제외했습니다.
• DB·개인 설정·인증정보·node_modules·Git 이력은 포함하지 않습니다. 기존 DB가 있다면 외부 저장 위치를 그대로 유지하세요.

1. 설치

Node 24.x가 필요합니다. 검증 버전은 .node-version의 24.19.0입니다. ZIP을 풀고 behind-glass 폴더에서 실행하세요.

node --version
npm ci
node --input-type=module -e "import Database from 'better-sqlite3'; const db = new Database(':memory:'); console.log(db.prepare('select sqlite_version() as version').get()); db.close()"

다른 PC의 node_modules를 복사하지 마세요. better-sqlite3는 대상 OS/CPU에 맞춰 설치해야 합니다. 미리 빌드된 바이너리가 없는 환경에서는 해당 서버의 네이티브 빌드 도구가 필요할 수 있습니다.

Windows / PowerShell 로컬 실행

이 PC는 nvm으로 Node 24.19.0을 설치·활성화했습니다. 다른 터미널에서도 node --version을 확인하세요. 빌드 명령은 Node 스크립트로 환경변수를 지정하므로 Windows와 Linux에서 동일하게 사용할 수 있습니다.

nvm use 24.19.0
npm ci
node scripts/restore-source-assets.mjs
npm run build:server
npm run start:local

로컬 주소는 http://127.0.0.1:3000입니다. start:local은 deploy/arrival.local.env를 명시적으로 읽으며, 현재 PC의 DB는 C:\Users\horoli\AppData\Local\BehindGlass\analytics.sqlite에 저장합니다. 데이터 폴더는 현재 사용자와 SYSTEM만 접근하도록 설정했습니다. 이 설정 파일은 Git에서 제외됩니다. 실행 중인 터미널에서 Ctrl+C로 종료합니다.

새 PC에서는 아래처럼 해당 계정의 경로로 설정 파일을 만들고, 데이터 폴더의 Windows ACL을 확인하세요. 기존 DB가 있다면 새 경로를 만들기 전에 기존 DB_PATH를 유지하세요.

$localDataPath = Join-Path $env:LOCALAPPDATA 'BehindGlass'
@(
  'NODE_ENV=development'
  'HOST=127.0.0.1'
  'PORT=3000'
  'PUBLIC_ORIGIN=http://127.0.0.1:3000'
  "DB_PATH='$localDataPath\analytics.sqlite'"
) | Set-Content -LiteralPath 'deploy/arrival.local.env' -Encoding utf8

localhost와 127.0.0.1은 서로 다른 origin입니다. 집계가 필요하면 설정과 동일한 주소로 접속하세요. 로컬 HTTP 실행은 PC 확인용이며, 실제 모바일 센서 확인은 HTTPS 배포 후 진행합니다.

better-sqlite3 13.0.3은 플랫폼별 바이너리를 패키지에 포함합니다. npm이 이를 불필요하게 소스 빌드하지 않도록 lockfile에도 원래 패키지의 gypfile: false를 반영했습니다. npm의 설치 스크립트 허용 목록에는 고정된 ONNX Runtime 및 protobufjs 버전만 추가했습니다. 의존성 버전은 변경하지 않았습니다.

Windows 집계 테스트의 파일 링크 검증은 개발자 모드 또는 링크 생성 권한이 있는 터미널에서 실행하세요.

로컬 집계와 백업도 같은 설정 파일을 명시적으로 읽습니다. npm ci를 다시 실행하기 전에는 서버를 종료하세요. Windows에서는 실행 중인 서버가 SQLite DLL을 사용해 재설치 시 파일 삭제가 차단될 수 있습니다.

node --env-file=deploy/arrival.local.env server/metrics.mjs --month 2026-10
node --env-file=deploy/arrival.local.env server/backup.mjs --output "$env:LOCALAPPDATA\BehindGlass\backups\analytics-2026-10-09.sqlite"

2. 실행

DB는 프로젝트 바깥의 영구 로컬 디스크에 둡니다. 아래는 현재 계정의 홈 폴더를 사용하는 예시입니다. PUBLIC_ORIGIN은 실제 접속 HTTPS 주소로 바꾸세요. 경로 없이 도메인(필요하면 포트)까지만 입력합니다.

(umask 077; mkdir -p "$HOME/behind-glass-data")
DB_PATH="$HOME/behind-glass-data/analytics.sqlite" \
PUBLIC_ORIGIN="https://your-domain.example" \
NODE_ENV=production HOST=127.0.0.1 PORT=3000 npm start

처음 실행하면 빈 SQLite DB와 스키마가 만들어집니다. 기본 포트는 3000이며 nginx 뒤에서 사용할 수 있도록 127.0.0.1에만 바인딩합니다. SSH 종료 후에도 유지하려면 기존 프로세스 관리자 또는 deploy/behind-glass.service.example을 서버 경로·사용자에 맞춰 적용하세요. 단일 프로세스로 실행하고 PM2 cluster/multiple workers는 사용하지 마세요.

deploy/arrival.env.example은 예시입니다. 파일을 복사하는 것만으로 자동 로드되지는 않습니다. systemd의 EnvironmentFile 또는 Node의 명시적 --env-file=/절대경로/arrival.env 옵션을 사용하세요. 실제 설정 파일은 공개 폴더에 두지 마세요.

3. nginx / HTTPS

기존 HTTPS 도메인의 요청을 같은 Fastify 프로세스로 전달합니다. 정적 화면과 /api가 같은 origin이어야 합니다. 기존 server 블록 안의 location 예시:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

도메인·인증서·포트 충돌과 기존 location 설정을 확인한 뒤 적용하세요. 이 ZIP이 nginx나 시스템 설정을 자동 변경하지는 않습니다. 사진 처리는 브라우저 안에서 수행되며 AI 모델/WASM의 외부 다운로드에는 인터넷 연결이 필요합니다. 모바일 센서/보안 기능 확인은 실제 HTTPS 주소에서 진행하세요.

이 서버에는 자체 로그인 기능이 없습니다. 현재 비공개 테스트 범위를 유지하려면 HTTPS 프록시에서 소유자 전용 접근제어도 설정하세요. 외부 공개는 포함된 사진과 리소스의 공개 범위를 확인한 후 별도로 진행하세요.

현재 trustProxy는 false입니다. 리버스 프록시 뒤에서는 API 요청 제한(기본 60회/분)이 같은 연결 IP로 합산될 수 있으니 공개 트래픽을 늘리기 전에 프록시 신뢰 범위와 제한 정책을 검토하세요. Origin 검사는 로그인/인증을 대신하지 않습니다.

4. 수정 후 다시 빌드

처음 재빌드하기 전에 아래 복원 명령을 한 번 실행하세요. 기존 dist에 들어 있는 같은 파일을 복사하므로 인터넷 다운로드가 아닙니다. 복원 전 dist를 지우지 마세요.

node scripts/restore-source-assets.mjs
npm run build:server

주의: npm run build는 별도 정적 테스트 Site용이라 집계가 비활성화됩니다. 이 서버에서는 build:server를 사용하세요. 원본 소스에서 한 번 수정하더라도 각 서버의 재빌드·재배포는 별도로 해야 합니다.

5. 확인 / 집계 / 백업

npm run test:arrival
curl http://127.0.0.1:3000/api/arrivals/count
DB_PATH="$HOME/behind-glass-data/analytics.sqlite" npm run --silent metrics -- --month 2026-10

test:arrival은 임시 DB로 동작하며 운영 DB를 사용하지 않습니다. 실제 개인 사진의 성공한 도착만 누적하고 샘플 도착은 제외합니다. 방문 집계는 샘플 진입도 포함합니다.

백업·복원 및 집계 기준은 docs/arrival-backend-operations.md를 참고하세요. DB/WAL/SHM은 dist/public 및 프로젝트 밖에 보관하세요. 서비스 계정만 읽고 쓸 수 있도록 데이터 폴더와 DB 권한을 제한하세요.

검증 범위

현재 Windows 로컬 검증 (2026-10-09)

• Node 24.19.0 / npm 11.17.0에서 일반 npm ci, SQLite 로딩, 정적 빌드 및 서버용 빌드를 확인했습니다. 최종 dist는 서버용 빌드입니다.
• npm run test:arrival은 서버 33개 + 클라이언트 73개, 총 106개 통과했습니다.
• 기존 전체 테스트는 470개 중 467개 통과했습니다. 다음 3개 테스트는 원래 배포본에 포함되지 않은 QA 자료 때문에 실패하며, 해당 원본 자료 복원이 필요합니다. 통과로 처리하거나 임의 자료로 대체하지 않았습니다.
  • scripts/test-cutout-worker.mjs: docs/qa-countryside-cutout-2026-10-07/runtime/sample-320.rgba 누락
  • scripts/test-original-photo-only.mjs: docs/reference-assets/countryside/open-house.png 누락
  • scripts/test-surface-reflection.mjs: docs/qa-surface-reflection/baseline-mosaic.frag 누락
• 실제 127.0.0.1:3000 HTTP로 HTML, JS/CSS, 샘플 사진, GLB 및 ONNX 파일의 200 응답과 집계 API { "count": 0 }를 확인했습니다. 다른 Origin은 403, 비공개 파일 경로는 404입니다.
• Windows 자산 경로 구분자를 정규화하고, 테스트 DB를 닫은 뒤 임시 파일을 삭제하도록 수정했습니다. AI 테스트의 파일 URL도 Windows에서 동작하도록 수정했습니다.
• RELEASE-MANIFEST.json은 수령한 원본 배포본의 체크섬 기록입니다. 이번 로컬 수정 파일의 체크섬과는 구분합니다.

수령한 원본 릴리스의 검증 기록

• 이 릴리스의 서버용 빌드와 방문/도착 테스트를 실행했습니다.
• 최신 소스의 전체 자동 테스트 470개 및 두 빌드는 통과한 상태입니다.
• ZIP 추출본에서 Fastify inject + 실제 임시 SQLite로 정적 페이지와 집계/중복 처리를 확인했습니다. 네트워크 포트를 통한 실서비스 검증과는 다릅니다.
• 사용자의 서버 OS/CPU, nginx/HTTPS, 실제 모바일/WebGL/센서, 외부 AI 다운로드는 배포 후 확인해야 합니다.