hyungi_document_server/docs/deploy.md

배포 가이드

1. 사전 요구사항

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

2. Mac mini 배포

2-1. 코드 가져오기

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

2-2. 인증 정보 설정

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 마운트 확인

# 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. 서비스 시작

docker compose up -d

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

2-5. 확인

# 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

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

3-2. 모델 확인

# 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 확인

curl http://localhost:8080/health

4. 업데이트

# 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. 로그 확인

# 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. 백업

우선순위

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

PostgreSQL 백업

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