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. 업로드 한도 정책

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

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

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