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` 폴더에서 실행하세요.

```sh
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에서 동일하게 사용할 수 있습니다.

```powershell
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:3600`입니다. `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`를 유지하세요.

```powershell
$localDataPath = Join-Path $env:LOCALAPPDATA 'BehindGlass'
@(
  'NODE_ENV=development'
  'HOST=127.0.0.1'
  'PORT=3600'
  'PUBLIC_ORIGIN=http://127.0.0.1:3600'
  "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을 사용해 재설치 시 파일 삭제가 차단될 수 있습니다.

```powershell
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 주소로 바꾸세요.** 경로 없이 도메인(필요하면 포트)까지만 입력합니다.

```sh
(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=3600 npm start
```

처음 실행하면 빈 SQLite DB와 스키마가 만들어집니다. 기본 포트는 3600이며 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` 옵션을 사용하세요. 실제 설정 파일은 공개 폴더에 두지 마세요.

PM2에서는 `server/index.mjs`를 직접 실행합니다. PM2가 ESM 파일을 import하는 경우에도 서버가 시작되도록 실행 진입점을 처리했습니다. nginx가 다른 장비에 있으면 `HOST`를 nginx가 접근할 앱 서버의 IP로 지정하세요. 예를 들어 nginx가 `192.168.0.250:3600`으로 전달한다면 `HOST=192.168.0.250 PORT=3600`으로 실행합니다. 기존 PM2 프로세스의 환경변수 변경은 `--update-env`로 적용합니다. PM2의 `online` 표시만으로 HTTP 서버 시작을 판단하지 말고, nginx 장비에서 `/api/arrivals/count`에 연결되는지 확인하세요.

## 3. nginx / HTTPS

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

```nginx
location / {
    proxy_pass http://127.0.0.1:3600;
    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를 지우지 마세요.

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

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

## 5. 확인 / 집계 / 백업

```sh
npm run test:arrival
curl http://127.0.0.1:3600/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`은 서버 34개 + 클라이언트 73개, 총 107개 통과했습니다. PM2 방식의 ESM import 시작 검증을 포함합니다.
- 기존 전체 테스트는 471개 중 468개 통과했습니다. 다음 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:3600` 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 다운로드는 배포 후 확인해야 합니다.