d3ro-voice/docs/deployment/nas-deployment-guide.md

D3RO Voice — NAS 배포 및 Docker 운영 가이드

본 문서는 D3RO Voice 클라우드 백엔드 및 관리자 백오피스 서비스를 Synology, QNAP, Linux 등 개인 및 기업용 NAS(Network Attached Storage) 환경에 Docker로 배포하고 운영하는 전체 절차를 안내합니다.

---

1. 시스템 개요 및 아키텍처

D3RO Voice는 로컬 데스크톱(Windows, macOS), 모바일(iOS, Android), 웹 클라이언트와 통신하여 AI 처리(STT, LLM 프록시), 사용자 인증, 토큰/비용 통계 관리, 모델 엔드포인트 라우팅을 수행하는 독립형 클라우드 백엔드를 제공합니다.

graph TB
    subgraph Clients["D3RO Clients"]
        D1[Desktop App<br/>Windows / Mac]
        D2[Mobile App<br/>iOS / Android]
        D3[Web Client<br/>Browser]
    end

    subgraph NAS["NAS Server (Docker Container)"]
        subgraph Ports["Exposed Port 5000"]
            P1["/ (Portal Web)"]
            P2["/admin (BackOffice)"]
            P3["/api/* (REST API)"]
            P4["/swagger (OpenAPI)"]
            P5["/health (HealthCheck)"]
        end

        subgraph CoreService["D3RO Voice API Container"]
            API[ASP.NET Core Web API]
            AUTH[JWT Authentication]
            LLM[LLM Proxy Service]
            ADMIN[Admin BackOffice UI]
        end

        subgraph Storage["Persistent Volume (/app/data)"]
            DB[(d3ro_api.db<br/>SQLite EF Core)]
        end

        subgraph OptionalAI["Optional: On-NAS Local AI"]
            OLLAMA[Ollama Container<br/>Port 11434]
        end
    end

    subgraph ExternalCloud["External Cloud LLM Providers"]
        OAI[OpenAI API]
        ANT[Anthropic API]
        CUST[Custom API]
    end

    Clients -->|HTTP / REST Port 5000| Ports
    Ports --> CoreService
    CoreService --> Storage
    CoreService -.->|Optional Local AI| OptionalAI
    CoreService -->|API Calls with Keys| ExternalCloud

주요 구성 요소

1. D3RO Voice API Server (d3ro-voice-api:latest):
   • .NET 10 기반 고성능 경량 웹 API & 프록시 서버.
   • 사용자 가입/로그인 (JWT 인증, 첫 가입자 자동 Admin 승격).
   • 동적 LLM 엔드포인트 관리 (OpenAI, Anthropic, Custom LLM 지원 및 API 키 암호화 보관).
   • 실시간 토큰 사용량, 통화 시간, 비용 집계 및 에러 로그 기록.
   • 통합 Midnight Glass 테마의 Admin BackOffice 내장 (/admin).
2. 영구 스토리지 (Persistent SQLite Volume):
   • NAS 호스트 디렉토리(예: /volume1/docker/d3ro/data)를 컨테이너의 /app/data로 마운트하여 컨테이너 재시작/업데이트 시에도 모든 설정, 사용자 계정, 사용량 로그가 안전하게 유지됩니다.
3. 선택사항 (On-NAS Local LLM):
   • 사양에 따라 NAS에서 직접 로컬 Ollama 모델을 구동할 수 있도록 docker compose --profile ai up -d 지원.

---

2. 배포 패키지 자동 생성

로컬 개발 PC에서 NAS 배포용 독립 패키지를 원클릭으로 생성할 수 있습니다.

Windows (PowerShell)

# 1. Docker 이미지 빌드 및 NAS 배포 패키지 생성
.\scripts\deploy-nas.ps1

# 2. (선택) NAS로 SSH 자동 원격 배포
.\scripts\deploy-nas.ps1 -NasHost 192.168.1.100 -NasUser yunchan -NasPath /volume1/docker/d3ro -DeploySsh

Linux / macOS (Bash)

# 1. 패키지 생성
./scripts/deploy-nas.sh

# 2. (선택) SSH 원격 배포
./scripts/deploy-nas.sh 192.168.1.100 yunchan /volume1/docker/d3ro 5000

생성된 산출물 폴더 (out/nas-package/):

• d3ro-voice-api.tar: Docker 컨테이너 이미지 아카이브 (~116MB)
• docker-compose.yml: NAS용 Docker Compose 설정
• .env: 환경 변수 설정 템플릿
• nas-control.sh: NAS 전용 관리/제어 스크립트
• README.txt: 빠른 시작 안내

---

3. NAS별 설치 방법

방법 A: Synology NAS (DSM 7.2+ Container Manager GUI)

1. 파일 업로드:

   • Synology File Station을 열고 docker 공유 폴더 아래에 d3ro 폴더를 생성합니다: /volume1/docker/d3ro
   • out/nas-package/ 안의 파일들을 해당 폴더로 업로드합니다.

2. Docker 이미지 등록:

   • Container Manager 실행 > 이미지 (Image) 메뉴 클릭.
   • 상단의 작업 (Action) > 추가 (Add) > 파일에서 추가 (From File) 선택.
   • 업로드한 d3ro-voice-api.tar 파일을 선택하여 이미지를 로드합니다.

3. 프로젝트 생성 (Docker Compose):

   • Container Manager > 프로젝트 (Project) 메뉴 클릭 > 생성 (Create).
   • 프로젝트 이름: d3ro-voice
   • 경로: /docker/d3ro
   • 소스: 기존 docker-compose.yml 사용 선택.
   • 다음 > 완료를 클릭하면 컨테이너가 자동으로 빌드/실행됩니다.

---

방법 B: QNAP NAS (Container Station GUI)

1. 폴더 준비:
   • File Station에서 /share/Container/d3ro 폴더 생성 후 패키지 파일 업로드.
2. Container Station 실행:
   • Images 탭 > Import > d3ro-voice-api.tar 선택하여 로드.
   • Applications 탭 > Create > docker-compose.yml 내용을 붙여넣고 생성.

---

방법 C: Linux / TrueNAS SCALE / Unraid / SSH 터미널

1. SSH로 NAS에 접속합니다:

   ssh yunchan@<NAS_IP>
   

2. 작업 폴더 생성 및 이동:

   mkdir -p /volume1/docker/d3ro
   cd /volume1/docker/d3ro
   

3. Docker 이미지 로드 및 컨테이너 실행:

   # 이미지 로드
   docker load < d3ro-voice-api.tar
   
   # 컨테이너 구동
   docker compose up -d
   

---

4. 관리 및 접속 확인

컨테이너가 실행되면 브라우저에서 NAS IP와 5000번 포트로 접속합니다:

서비스	URL	설명
D3RO Cloud Portal	http://<NAS_IP>:5000/	서버 상태 및 빠른 바로가기 포털
Admin BackOffice	http://<NAS_IP>:5000/admin	AI 모델, API 키, 사용자 및 비용 관리
OpenAPI / Swagger	http://<NAS_IP>:5000/swagger	REST API 인터랙티브 테스트 문서
Health Check	http://<NAS_IP>:5000/health	컨테이너 상태 모니터링 엔드포인트

최초 관리자 계정 생성

1. http://<NAS_IP>:5000/admin에 접속합니다.
2. [회원가입] 버튼을 눌러 이메일과 비밀번호를 입력합니다.
3. 가장 처음 가입한 계정은 자동으로 Admin 최고 관리자 권한을 부여받습니다.
4. 로그인 후 [모델 관리] 탭에서 사용할 OpenAI / Claude API 키를 등록합니다.

---

5. D3RO 데스크톱 & 모바일 앱 연결

1. D3RO 데스크톱 앱을 실행하고 오른쪽 상단 [설정] (단축키 Ctrl+,)을 엽니다.
2. [LLM] 탭으로 이동합니다.
3. 엔진 선택: 온라인 (D3RO Cloud Server) 선택.
4. API 서버 URL: http://<NAS_IP>:5000 입력.
5. 등록한 계정으로 로그인하면, 데스크톱 앱에서 발생하는 모든 음성 보정, 번역, 회의록 요약 처리가 NAS 클라우드 서비스를 통해 안전하게 수행됩니다.

---

6. NAS 전용 관리 도구 (nas-control.sh)

NAS 터미널에서 다음 명령어로 손쉽게 컨테이너를 관리할 수 있습니다:

cd /volume1/docker/d3ro

# 서비스 시작
./nas-control.sh start

# 상태 및 헬스체크 확인
./nas-control.sh status

# 실시간 로그 확인
./nas-control.sh logs

# SQLite 데이터베이스 및 설정 백업 (tar.gz 자동 생성)
./nas-control.sh backup

# 새로운 버전 tar 파일로 업데이트 및 재시작
./nas-control.sh update d3ro-voice-api.tar

# 서비스 종료
./nas-control.sh stop

---

7. HTTPS 역방향 프록시 (외부 접속 설정)

외부 네트워크(카페, 외부 회의실, 모바일 LTE/5G)에서 NAS의 D3RO 서비스를 안전하게 사용하려면 Synology 역방향 프록시 설정을 권장합니다:

1. Synology DSM 제어판 > 로그인 포털 > 고급 > 역방향 프록시 클릭.
2. 생성 클릭:
   • 소스:
     • 프로토콜: HTTPS
     • 호스트 이름: d3ro.yourdomain.synology.me (또는 개인 도메인)
     • 포트: 443
     • HSTS 활성화 체크
   • 대상:
     • 프로토콜: HTTP
     • 호스트 이름: localhost
     • 포트: 5000
3. 사용자 지정 머리글 탭 > 생성 > WebSocket 클릭 (업그레이드 헤더 자동 추가).
4. 저장을 누르면 https://d3ro.yourdomain.synology.me로 안전한 SSL 암호화 접속이 가능합니다.