OMyPIc 데스크톱 앱 실행/패키징 안내

이 문서는 OMyPIc를 Electron 기반 단일 실행 앱으로 개발/배포하는 방법을 설명합니다.

1) 구성

• Backend: Spring Boot (backend/)
• Frontend: React + Vite (frontend/)
• Desktop: Electron (frontend/electron/)
• 번들 리소스: Backend JAR + MongoDB + JRE17 (frontend/electron/resources/)

2) 개발 실행

개발 모드에서는 Electron이 Vite dev 서버를 띄우며, Backend/MongoDB는 외부 실행을 기본으로 가정합니다.

• Node.js 버전: >= 20.19.0 (프로젝트 루트 .nvmrc 참고)

# terminal 1
cd backend
./gradlew bootRun

# terminal 2
cd frontend
npm install
npm run dev

• Backend 기본 포트: 4317
• Vite dev 서버: http://localhost:5173

3) 배포 패키징

electron:prep 단계에서 아래 작업이 자동 수행됩니다.

1. Backend :bootstrap:bootJar 빌드
2. JAR를 electron/resources/backend/omypic-backend.jar로 복사
3. 현재 OS/아키텍처용 MongoDB 바이너리 다운로드 및 sha256 검증
4. 현재 OS/아키텍처용 Temurin JRE17 다운로드 및 sha256 검증
5. (옵션) 사전학습 임베딩 모델을 electron/resources/models/에 복사
6. 리소스를 electron/resources로 정리

cd frontend
npm install

# 공통 빌드 (현재 플랫폼 기준)
npm run electron:build

# Windows 설치형 (NSIS)
npm run electron:build:win

# macOS 설치형 (DMG)
npm run electron:build:mac

# 오프라인 배포용: 임베딩 모델 번들 포함
OMYPIC_BUNDLE_EMBEDDING=1 \
OMYPIC_EMBEDDING_MODEL_SOURCE=/absolute/path/to/cc.ko.300.vec.gz \
OMYPIC_EMBEDDING_MODEL_SHA256=<sha256> \
OMYPIC_EMBEDDING_MODEL_VERSION=cc.ko.300.vec.gz \
npm run electron:build

산출물은 frontend/dist/ 하위에 생성됩니다. Windows 설치형은 Windows 환경에서, macOS DMG는 macOS 환경에서 빌드하는 것을 권장합니다.

4) 런타임 기동 순서

패키지된 앱 실행 시 Electron 메인 프로세스는 아래 순서로 동작합니다.

1. 번들된 mongod 실행
2. 포트 27017 준비 대기
3. 번들된 JRE로 Backend JAR 실행
4. /actuator/health 준비 대기
5. 프론트 UI 로드

5) 환경 변수

Electron/Backend 공통

• OMYPIC_BACKEND_URL
  • 기본값: http://localhost:4317
• OMYPIC_MONGODB_URI
  • 기본값: mongodb://127.0.0.1:27017/omypic
• OMYPIC_DATA_DIR
  • 기본값: Electron userData 하위 omypic-data
• OMYPIC_RAG_MODEL_PATH
  • 기본값: 미지정
  • 패키지 앱에서 번들 모델이 있으면 Electron이 자동 주입
• OMYPIC_RAG_PROVIDER
  • 기본값: fasttext
• OMYPIC_RAG_MODEL_VERSION
  • 기본값: cc.ko.300.vec.gz
• OMYPIC_RAG_MODEL_SHA256
  • 기본값: cc.ko.300.vec.gz 고정 SHA-256
  • 번들 모델 사용 시 manifest.json에서 자동 주입
• OMYPIC_RAG_DOWNLOAD_URL
  • 기본값: fastText 공식 배포 URL (cc.ko.300.vec.gz)
• OMYPIC_RAG_ALLOW_HASH_FALLBACK
  • 기본값: false

별도 설정이 없으면 첫 실행 시 모델이 자동 다운로드됩니다. 모델 파일이 크기 때문에(약 1.27GB) 네트워크 환경에 따라 초기 기동 시간이 길어질 수 있습니다.

기동 Override

• OMYPIC_BACKEND_CMD
  • 지정 시 해당 명령으로 Backend 실행
• OMYPIC_MONGODB_BIN
  • 지정 시 해당 mongod 경로 실행
• OMYPIC_BACKEND_URL 또는 OMYPIC_MONGODB_URI를 외부 서버로 지정하면 로컬 번들 Backend/MongoDB를 기동하지 않고 외부 서버를 사용합니다.

패키징 옵션

• OMYPIC_BUNDLE_EMBEDDING
  • 1이면 임베딩 모델 파일을 electron/resources/models에 포함
• OMYPIC_EMBEDDING_MODEL_SOURCE
  • 번들 포함할 모델 파일 경로(필수 when OMYPIC_BUNDLE_EMBEDDING=1)
• OMYPIC_EMBEDDING_MODEL_SHA256
  • 번들 파일 sha256 검증값(권장)
• OMYPIC_EMBEDDING_MODEL_VERSION
  • 번들 파일명 override(기본: source 파일명)

6) 코드서명 정책

• 현재 빌드는 개발/사내 배포용 unsigned 아티팩트를 기준으로 합니다.
• Windows 코드서명, macOS notarization은 후속 단계에서 적용합니다.

7) API Key 저장

• API Key는 Electron에서 OS Keychain(keytar)에 저장됩니다.
• Backend에는 저장하지 않고 요청 시 헤더로 전달됩니다.
• 현재 앱은 OpenAI API Key만 지원합니다.

8) 피드백 모델 지원 범위

• 지원 모델:
  • gpt-5-mini
  • gpt-5-nano
  • gpt-4.1
  • gpt-4.1-mini
  • gpt-4.1-nano
  • gpt-4o
  • gpt-4o-mini
• 기본 피드백 모델: gpt-5-nano
• 기본 설정(gpt-5-nano) 기준 세션 1회당 비용은 약 50원 수준이며, 실제 비용은 발화 길이/선택 모델에 따라 달라질 수 있습니다.
• 비용 정책상 gpt-5-mini보다 상위 GPT-5 계열(gpt-5, gpt-5.1, gpt-5.2, gpt-5-pro)은 지원 대상에서 제외됩니다.

9) 음성 청크 전송 보장

• 클라이언트는 음성 turn 청크를 HTTP 2xx 응답 전까지 유지합니다(at-least-once).
• 업로드 실패 시 지수 백오프로 재시도합니다: 0.5s -> 1s -> 2s -> 4s -> 4s (최대 5회).
• 같은 청크는 동일 sequence로 재전송되며, 서버는 세션 단위로 중복 sequence를 무시합니다.
• turn 캡처 길이는 최대 2분 30초로 제한되며, 초과 시 세션을 종료해 메모리 사용 폭증을 방지합니다.