0ca78640ee
- Integrate ollama + ai-gateway into root docker-compose.yml (NVIDIA GPU runtime, single compose for all services) - Change NAS mount from SMB (NAS_SMB_PATH) to NFS (NAS_NFS_PATH) Default: /mnt/nas/Document_Server (fstab registered on GPU server) - Update config.yaml AI endpoints: primary → Mac mini MLX via Tailscale (100.76.254.116:8800) fallback/embedding/vision/rerank → ollama (same Docker network) gateway → ai-gateway (same Docker network) - Update credentials.env.example (remove GPU_SERVER_IP, add NFS path) - Mark gpu-server/docker-compose.yml as deprecated - Update CLAUDE.md network diagram and AI model config - Update architecture.md, deploy.md, devlog.md for GPU server as main - Caddyfile: auto_https off, HTTP only (TLS at upstream proxy) - Caddy port: 127.0.0.1:8080:80 (localhost only) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
151 lines
5.2 KiB
Markdown
151 lines
5.2 KiB
Markdown
# hyungi_Document_Server — Claude Code 작업 가이드
|
|
|
|
## 프로젝트 개요
|
|
|
|
Self-hosted PKM(Personal Knowledge Management) 웹 애플리케이션.
|
|
FastAPI + PostgreSQL(pgvector) + SvelteKit + Docker Compose 기반.
|
|
Mac mini M4 Pro를 애플리케이션 서버, Synology NAS를 파일 저장소, GPU 서버를 AI 추론에 사용한다.
|
|
|
|
## 핵심 문서
|
|
|
|
1. `docs/architecture.md` — 전체 시스템 아키텍처 (DB 스키마, AI 전략, 인프라, UI 설계)
|
|
2. `docs/deploy.md` — Docker Compose 배포 가이드
|
|
3. `docs/development-stages.md` — Phase 0~5 개발 단계별 가이드
|
|
|
|
## 기술 스택
|
|
|
|
| 영역 | 기술 |
|
|
|------|------|
|
|
| 백엔드 | FastAPI (Python 3.11+) |
|
|
| 데이터베이스 | PostgreSQL 16 + pgvector + pg_trgm |
|
|
| 프론트엔드 | SvelteKit |
|
|
| 문서 파싱 | kordoc (Node.js, HWP/HWPX/PDF → Markdown) |
|
|
| 리버스 프록시 | Caddy (자동 HTTPS) |
|
|
| 인증 | JWT + TOTP 2FA |
|
|
| 컨테이너 | Docker Compose |
|
|
|
|
## 네트워크 환경
|
|
|
|
```
|
|
GPU 서버 (RTX 4070 Ti Super, Ubuntu, 메인 서버):
|
|
- Docker Compose: FastAPI(:8000), PostgreSQL(:5432), kordoc(:3100),
|
|
Caddy(:8080 HTTP only), Ollama(:11434), AI Gateway(:8081), frontend(:3000)
|
|
- NFS 마운트: /mnt/nas/Document_Server → NAS /volume4/Document_Server
|
|
- 외부 접근: document.hyungi.net (앞단 프록시 → Caddy)
|
|
- 로컬 IP: 192.168.1.186
|
|
|
|
Mac mini M4 Pro (AI 서버):
|
|
- MLX Server: http://100.76.254.116:8800/v1/chat/completions (Qwen3.5-35B-A3B)
|
|
- Tailscale IP: 100.76.254.116
|
|
|
|
Synology NAS (DS1525+):
|
|
- 도메인: ds1525.hyungi.net
|
|
- Tailscale IP: 100.101.79.37
|
|
- 포트: 15001
|
|
- 파일 원본: /volume4/Document_Server/PKM/
|
|
- NFS export → GPU 서버
|
|
- Synology Office: 문서 편집/미리보기
|
|
- Synology Calendar: CalDAV 태스크 관리 (OmniFocus 대체)
|
|
- MailPlus: IMAP(993) + SMTP(465)
|
|
```
|
|
|
|
## 인증 정보
|
|
|
|
- 위치: `credentials.env` (프로젝트 루트, .gitignore에 포함)
|
|
- 템플릿: `credentials.env.example`
|
|
- 스크립트에서 python-dotenv 또는 Docker env_file로 로딩
|
|
|
|
## AI 모델 구성
|
|
|
|
```
|
|
Primary (Mac mini MLX, Tailscale 경유, 상시, 무료):
|
|
mlx-community/Qwen3.5-35B-A3B-4bit — 분류, 태그, 요약
|
|
→ http://100.76.254.116:8800/v1/chat/completions
|
|
|
|
Fallback (GPU Ollama, 같은 Docker 네트워크, MLX 장애 시):
|
|
qwen3.5:35b-a3b
|
|
→ http://ollama:11434/v1/chat/completions
|
|
|
|
Premium (Claude API, 종량제, 수동 트리거만):
|
|
claude-sonnet — 복잡한 분석, 장문 처리
|
|
→ 일일 한도 $5, require_explicit_trigger: true
|
|
|
|
Embedding (GPU Ollama, 같은 Docker 네트워크):
|
|
nomic-embed-text → 벡터 임베딩 → http://ollama:11434/api/embeddings
|
|
Qwen2.5-VL-7B → 이미지/도면 OCR → http://ollama:11434/api/generate
|
|
bge-reranker-v2-m3 → RAG 리랭킹 → http://ollama:11434/api/rerank
|
|
```
|
|
|
|
## 프로젝트 구조
|
|
|
|
```
|
|
hyungi_Document_Server/
|
|
├── docker-compose.yml ← Mac mini용
|
|
├── Caddyfile
|
|
├── config.yaml ← AI 엔드포인트, NAS 경로, 스케줄
|
|
├── credentials.env.example
|
|
├── app/ ← FastAPI 백엔드
|
|
│ ├── main.py
|
|
│ ├── core/ (config, database, auth, utils)
|
|
│ ├── models/ (document, task, queue)
|
|
│ ├── api/ (documents, search, tasks, dashboard, export)
|
|
│ ├── workers/(file_watcher, extract, classify, embed, law_monitor, mailplus, digest)
|
|
│ ├── prompts/classify.txt
|
|
│ └── ai/client.py
|
|
├── services/kordoc/ ← Node.js 마이크로서비스
|
|
├── gpu-server/ ← GPU 서버용 (별도 배포)
|
|
│ ├── docker-compose.yml
|
|
│ └── services/ai-gateway/
|
|
├── frontend/ ← SvelteKit
|
|
├── migrations/ ← PostgreSQL 스키마
|
|
├── scripts/migrate_from_devonthink.py
|
|
├── docs/
|
|
└── tests/
|
|
```
|
|
|
|
## 데이터 3계층
|
|
|
|
1. **원본 파일** (NAS `/volume4/Document_Server/PKM/`) — 유일한 진짜 원본
|
|
2. **가공 데이터** (PostgreSQL) — 텍스트 추출, AI 메타데이터, 검색 인덱스
|
|
3. **파생물** (pgvector + 캐시) — 벡터 임베딩, 썸네일
|
|
|
|
## 코딩 규칙
|
|
|
|
- Python 3.11+, asyncio, type hints
|
|
- SQLAlchemy 2.0+ async 세션
|
|
- 인증 정보는 credentials.env에서 로딩 (하드코딩 금지)
|
|
- 로그는 `logs/`에 저장 (Docker 볼륨)
|
|
- AI 호출은 반드시 `app/ai/client.py`의 `AIClient`를 통해 (직접 HTTP 호출 금지)
|
|
- 한글 주석 사용
|
|
|
|
## 개발/배포 워크플로우
|
|
|
|
```
|
|
MacBook Pro (개발) → Gitea push → GPU 서버에서 pull
|
|
|
|
개발:
|
|
cd ~/Documents/code/hyungi_Document_Server/
|
|
# 코드 작성 → git commit & push
|
|
|
|
GPU 서버 배포 (메인):
|
|
cd ~/Documents/code/hyungi_Document_Server/
|
|
git pull
|
|
docker compose up -d
|
|
```
|
|
|
|
## v1 코드 참조
|
|
|
|
v1(DEVONthink 기반) 코드는 `v1-final` 태그로 보존:
|
|
```bash
|
|
git show v1-final:scripts/law_monitor.py
|
|
git show v1-final:scripts/pkm_utils.py
|
|
git show v1-final:scripts/prompts/classify_document.txt
|
|
```
|
|
|
|
## 주의사항
|
|
|
|
- credentials.env는 git에 올리지 않음 (.gitignore)
|
|
- NAS SMB 마운트 경로: Docker 컨테이너 내 `/documents`
|
|
- 법령 API (LAW_OC)는 승인 대기 중 — 스크립트만 만들고 실제 호출은 승인 후
|
|
- GPU 서버 Tailscale IP는 credentials.env에서 관리
|