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 프록시), 사용자 인증, 토큰/비용 통계 관리, 모델 엔드포인트 라우팅을 수행하는 독립형 클라우드 백엔드를 제공합니다.

```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 암호화 접속이 가능합니다.