# 배포 가이드

## 1. 사전 요구사항

- Docker & Docker Compose (Mac mini)
- NAS SMB 마운트 (`/Volumes/Document_Server`)
- Tailscale VPN 연결 (Mac mini ↔ GPU 서버 ↔ NAS)

## 2. Mac mini 배포

### 2-1. 코드 가져오기

```bash
cd ~/Documents/code/
git clone https://git.hyungi.net/hyungi/hyungi_document_server.git hyungi_Document_Server
cd hyungi_Document_Server
```

### 2-2. 인증 정보 설정

```bash
cp credentials.env.example credentials.env
nano credentials.env  # 실제 값 입력
chmod 600 credentials.env
```

필수 값: `POSTGRES_PASSWORD`, `JWT_SECRET`, `TOTP_SECRET`, `MLX_ENDPOINT`
선택 값: `CLAUDE_API_KEY`, `LAW_OC` (법령 API 승인 후)

### 2-3. NAS SMB 마운트 확인

```bash
# macOS에서 SMB 마운트 (Finder 또는 CLI)
mount -t smbfs //hyungi@ds1525.hyungi.net/Document_Server /Volumes/Document_Server

# 확인
ls /Volumes/Document_Server/PKM/
```

Docker 컨테이너에서 이 경로를 `/documents`로 바인드 마운트한다.

### 2-4. 서비스 시작

```bash
docker compose up -d

# 상태 확인
docker compose ps
docker compose logs -f fastapi
```

### 2-5. 확인

```bash
# FastAPI OpenAPI 문서
curl http://localhost:8000/docs

# PostgreSQL 테이블 확인
docker compose exec postgres psql -U pkm -d pkm -c '\dt'

# kordoc 헬스체크
curl http://localhost:3100/health
```

### 2-6. 외부 접근 (Caddy)

HTTPS는 앞단 프록시(Mac mini nginx)에서 처리하고, Caddy는 HTTP only로 동작한다.
- `document.hyungi.net` → Mac mini nginx (HTTPS 종료) → GPU 서버 Caddy (:8080) → FastAPI/Frontend
- `office.hyungi.net` → Synology Office (NAS 프록시)

DNS 레코드가 Mac mini의 공인 IP를 가리켜야 한다. Caddy는 `auto_https off` 설정.

## 3. GPU 서버 배포

### 3-1. AI Gateway + Ollama

```bash
cd ~/Documents/code/hyungi_Document_Server/gpu-server/
cp ../credentials.env .env  # 필요한 값만 복사
docker compose up -d
```

### 3-2. 모델 확인

```bash
# Ollama 모델 목록
docker compose exec ollama ollama list

# 필요 모델 pull
docker compose exec ollama ollama pull nomic-embed-text
docker compose exec ollama ollama pull qwen2.5-vl:7b
docker compose exec ollama ollama pull bge-reranker-v2-m3
```

### 3-3. AI Gateway 확인

```bash
curl http://localhost:8080/health
```

## 4. 업데이트

```bash
# Mac mini
cd ~/Documents/code/hyungi_Document_Server/
git pull
docker compose up -d --build

# GPU 서버
cd ~/Documents/code/hyungi_Document_Server/gpu-server/
git pull
docker compose up -d --build
```

## 5. 로그 확인

```bash
# FastAPI 로그
docker compose logs -f fastapi

# 특정 워커 로그
docker compose logs -f fastapi | grep law_monitor
docker compose logs -f fastapi | grep mailplus
docker compose logs -f fastapi | grep digest

# PostgreSQL 로그
docker compose logs -f postgres
```

## 6. 자동화 스케줄 (APScheduler)

Docker 내부에서 APScheduler로 관리 (launchd 대체):

| 시간 | 작업 | 주기 |
|------|------|------|
| 07:00 | law_monitor | 매일 |
| 07:00, 18:00 | mailplus_archive | 매일 2회 |
| 20:00 | daily_digest | 매일 |
| */5분 | file_watcher | 상시 |
| */10분 | processing_queue consumer | 상시 |

## 7. 업로드 한도 정책

업로드 크기 제한의 단일 진실 공급원은 `config.yaml` 의 `upload` 블록.

```yaml
upload:
  max_bytes: 100000000              # 100 MB (SI). authoritative policy value.
  content_length_slack_ratio: 1.05  # multipart 오버헤드 여유.
  stream_chunk_bytes: 1048576       # 1 MiB 단위 스트리밍 read/write.
```

### 책임 경계

| 레이어 | 역할 | 값 출처 |
|---|---|---|
| home-caddy (edge proxy) | DoS 방어선 | infra config |
| FastAPI `POST /api/documents/` | **authoritative policy enforcement** (스트리밍 누적 검사, 413) | `upload.max_bytes` |
| `GET /api/config/public` | 프론트용 공개 값 노출 | `upload.max_bytes` 재사용 |
| 프론트 `UploadDropzone.svelte` | **pre-check UX** (드롭 시 즉시 차단) | API 응답 구독 (fallback 100MB) |

### 정책식 (단일 기준)

> **proxy `request_body max_size` ≥ `upload.max_bytes * upload.content_length_slack_ratio`**

현재 기본값 기준 → 최소 proxy 한도 **105,000,000 바이트 (≈105MB SI)**. home-caddy 도
이 식을 만족해야 하며, 다른 배수("1.1배" 등) 를 별도로 관리하지 말 것.

### `GET /api/config/public` 범위 제한

이 엔드포인트는 **민감정보 없는 프론트 필수 설정만** 제공. 임의의 서버 설정을
프론트에 노출하는 범용 창구로 확장 금지. 필드 추가 시 리뷰 기준:

1. 민감정보 포함 여부 (비밀/내부 정책/경로 등 배제)
2. 프론트 동작 필수 여부 (UI 가 실제로 소비하지 않으면 불추가)

## 8. 백업

### 우선순위

1. **NAS 원본 파일** — Synology Drive 버전 이력 + Hyper Backup
2. **PostgreSQL** — `pg_dump` 정기 백업
3. **Docker volumes** — pgdata, caddy_data

### PostgreSQL 백업

```bash
docker compose exec postgres pg_dump -U pkm pkm > backup_$(date +%Y%m%d).sql
```