feat: complete release preparation, 10+ ad mediation, CI/CD, and docker deployment

docs/deployment/nas-deployment-guide.md

@@ -0,0 +1,231 @@
+# D3RO Voice — NAS 배포 및 Docker 운영 가이드
+
+본 문서는 **D3RO Voice 클라우드 백엔드 및 관리자 백오피스 서비스**를 Synology, QNAP, Linux 등 개인 및 기업용 **NAS(Network Attached Storage)** 환경에 Docker로 배포하고 운영하는 전체 절차를 안내합니다.
+
+---
+
+## 1. 시스템 개요 및 아키텍처
+
+D3RO Voice는 로컬 데스크톱(Windows, macOS), 모바일(iOS, Android), 웹 클라이언트와 통신하여 AI 처리(STT, LLM 프록시), 사용자 인증, 토큰/비용 통계 관리, 모델 엔드포인트 라우팅을 수행하는 독립형 클라우드 백엔드를 제공합니다.
+
+```mermaid
+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)
+```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)
+```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에 접속합니다:
+   ```bash
+   ssh yunchan@<NAS_IP>
+   ```
+
+2. 작업 폴더 생성 및 이동:
+   ```bash
+   mkdir -p /volume1/docker/d3ro
+   cd /volume1/docker/d3ro
+   ```
+
+3. Docker 이미지 로드 및 컨테이너 실행:
+   ```bash
+   # 이미지 로드
+   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 터미널에서 다음 명령어로 손쉽게 컨테이너를 관리할 수 있습니다:
+
+```bash
+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 암호화 접속이 가능합니다.