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 엔드포인트 변경

현재 → 변경:

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 설정에는 불필요