hyungi_document_server/docs/gpu-migration-plan.md

# GPU 서버 이전 + NFS 전환 — Claude Code 작업 지시서

## 배경

Phase 0~4 완료. 현재 Mac mini에서 Docker 전체 구동 중.
GPU 서버(Ubuntu, RTX 4070 Ti Super)로 애플리케이션 이전.
NAS NFS 마운트로 Synology Drive 데드락 해결.

## 완료된 수동 작업

- ✅ Step 1: NAS NFS 서버 설정 (DSM에서 NFS 활성화, NFSv4.1)
- ✅ Step 2: GPU 서버 NFS 마운트 (`/mnt/nas/Document_Server`, fstab 등록 완료)
- ✅ Step 6: Mac mini MLX 서버 외부 접근 확인 (100.76.254.116:8800 응답 확인)

## 확정된 정보

- Mac mini Tailscale IP: `100.76.254.116`
- NAS 로컬 IP: `192.168.1.227`
- GPU 서버 로컬 IP: `192.168.1.186`
- NFS 마운트 경로: `/mnt/nas/Document_Server`
- MLX 모델: `mlx-community/Qwen3.5-35B-A3B-4bit` (Mac mini에서 계속 서빙)

## 목표 구조

```
GPU 서버 (Ubuntu, 메인 서버):
  Docker Compose 단일 파일:
    - postgres, fastapi, kordoc-service, frontend, caddy
    - ollama (NVIDIA GPU), ai-gateway
  NFS → NAS /volume4/Document_Server (/mnt/nas/Document_Server)

Mac mini M4 Pro (AI 서버만):
  MLX Server: http://100.76.254.116:8800 (Qwen3.5-35B-A3B)

NAS DS1525+ (파일 저장소):
  NFS export → GPU 서버
  Synology Office/Calendar/MailPlus 유지
```

---

## Claude Code 작업 목록

### 작업 1: docker-compose.yml 통합

현재 루트 `docker-compose.yml` (Mac mini용)에 `gpu-server/docker-compose.yml`의 서비스를 통합.

변경 사항:
- `version: '3.8'` 제거 (Docker Compose V2 기준)
- NAS 볼륨 변수: `NAS_SMB_PATH` → `NAS_NFS_PATH`, 기본값 `/mnt/nas/Document_Server`
- Ollama 서비스 추가 (NVIDIA GPU runtime, ollama_data 볼륨)
- AI Gateway 서비스 추가 (Ollama depends_on)
- AI Gateway 환경변수: PRIMARY_ENDPOINT=http://100.76.254.116:8800/v1/chat/completions
- Caddy 포트: `127.0.0.1:8080:80` 유지 (HTTPS는 앞단 프록시(UCG-Fiber)에서 처리, Caddy는 HTTP only)
- ollama_data 볼륨 추가

참고 — 현재 파일:
- 루트 docker-compose.yml: postgres, kordoc-service, fastapi, frontend, caddy
- gpu-server/docker-compose.yml: ollama, ai-gateway

### 작업 2: config.yaml AI 엔드포인트 변경

현재 → 변경:

```yaml
ai:
  gateway:
    endpoint: "http://ai-gateway:8080"           # gpu-server → ai-gateway (같은 Docker 네트워크)

  models:
    primary:
      endpoint: "http://100.76.254.116:8800/v1/chat/completions"  # host.docker.internal → Mac mini Tailscale IP
      # 나머지 동일

    fallback:
      endpoint: "http://ollama:11434/v1/chat/completions"  # gpu-server → ollama (같은 Docker 네트워크)
      # 나머지 동일

    embedding:
      endpoint: "http://ollama:11434/api/embeddings"  # gpu-server → ollama

    vision:
      endpoint: "http://ollama:11434/api/generate"    # gpu-server → ollama

    rerank:
      endpoint: "http://ollama:11434/api/rerank"      # gpu-server → ollama
```

핵심: `gpu-server` 호스트명이 전부 `ollama` 또는 `ai-gateway`로 변경 (같은 Docker 네트워크).
primary만 Mac mini Tailscale IP `100.76.254.116`으로 외부 호출.

### 작업 3: credentials.env.example 갱신

변경 사항:
- `NAS_SMB_PATH` → `NAS_NFS_PATH=/mnt/nas/Document_Server`
- `MLX_ENDPOINT` → `http://100.76.254.116:8800/v1/chat/completions`
- `GPU_SERVER_IP` 항목 제거 (로컬이 됨)
- `AI_GATEWAY_ENDPOINT` → `http://ai-gateway:8080` (같은 Docker 네트워크)
- 주석 업데이트: "Mac mini MLX" → "Mac mini MLX (Tailscale 경유)"

### 작업 4: Caddyfile 확인

변경 불필요. 현재 상태 유지:
- `auto_https off` + `http://document.hyungi.net` (HTTPS는 앞단 프록시 UCG-Fiber에서 처리)
- Caddy 포트: `127.0.0.1:8080:80` (localhost 바인딩, 443 불필요)

### 작업 5: 문서 업데이트

#### CLAUDE.md — 네트워크 환경 섹션 갱신

현재:
```
Mac mini M4 Pro (애플리케이션 서버):
  - Docker Compose: FastAPI(:8000), PostgreSQL(:5432), kordoc(:3100), Caddy(:80,:443)
  - MLX Server: http://localhost:8800/v1/chat/completions (Qwen3.5-35B-A3B)
  - 외부 접근: document.hyungi.net (Caddy 프록시)
```

변경:
```
GPU 서버 (RTX 4070 Ti Super, Ubuntu, 메인 서버):
  - Docker Compose: FastAPI(:8000), PostgreSQL(:5432), kordoc(:3100), Caddy(:8080, HTTP only), Ollama(:11434), AI Gateway(:8080), frontend(:3000)
  - NFS 마운트: /mnt/nas/Document_Server → NAS /volume4/Document_Server
  - 외부 접근: document.hyungi.net (Caddy 프록시)

Mac mini M4 Pro (AI 서버):
  - MLX Server: http://100.76.254.116:8800/v1/chat/completions (Qwen3.5-35B-A3B)
  - Roon Core
```

GPU 서버 Tailscale IP도 추가. AI 모델 구성 섹션에서 primary endpoint 변경 반영.

#### docs/architecture.md — 섹션 3 (인프라 역할 분담) 갱신

Mac mini가 애플리케이션 서버 → GPU 서버가 메인 서버로 변경.
Mac mini는 AI 서버(MLX)만 담당하는 것으로 변경.
아스키 다이어그램 업데이트.

#### docs/deploy.md — GPU 서버 기준 배포 가이드로 변경

- 전제조건: NFS 마운트 (/mnt/nas/Document_Server)
- clone 경로, docker compose 명령 등 GPU 서버 기준으로 변경
- pg_dump/pg_restore 마이그레이션 절차 추가

#### docs/devlog.md — GPU 이전 기록 추가

Phase 1~2는 이미 기록됨. 아래 추가:

1. Phase 3 완료 기록 (자동화 이전: law_monitor, mailplus_archive, daily_digest, automation_state, APScheduler cron) — 기록 안 되어 있으면 추가
2. Phase 4 완료 기록 (SvelteKit UI: 로그인, 대시보드, 문서 탐색/검색, Inbox, 설정, Docker 통합) — 기록 안 되어 있으면 추가
3. GPU 서버 이전 기록 (NFS 전환, docker-compose 통합, AI 엔드포인트 변경, Caddy HTTP only 구조)

### 작업 6: gpu-server/docker-compose.yml 비활성화

- 파일 상단에 주석 추가: "# 이 파일은 더 이상 사용하지 않음. 루트 docker-compose.yml로 통합됨."
- 또는 gpu-server/docker-compose.yml.bak으로 리네임

---

## 작업 순서 (추천)

1. docker-compose.yml 통합 (작업 1)
2. config.yaml 변경 (작업 2)
3. credentials.env.example 갱신 (작업 3)
4. gpu-server/docker-compose.yml 비활성화 (작업 6)
5. 문서 업데이트 (작업 5) — CLAUDE.md, architecture.md, deploy.md, devlog.md
6. Caddyfile 확인 (작업 4)

## 주의사항

- credentials.env 자체는 git에 올리지 않음 (.gitignore). example만 수정.
- Mac mini Tailscale IP `100.76.254.116`은 config.yaml에 직접 기입 (credentials.env에서 변수로 관리해도 됨)
- NAS 경로: Docker 컨테이너 내부에서는 `/documents`로 접근 (기존과 동일)
- GPU 서버 로컬 IP `192.168.1.186`은 NFS 마운트에만 사용, Docker 설정에는 불필요