Hyungi Ahn
0807574986
Phase B 로 확립된 업로드 size 정책을 deploy.md 에 섹션으로 정리:
- config.yaml `upload` 블록 (단일 진실 공급원)
- 4 레이어 책임 경계 (home-caddy / FastAPI / /config/public / UploadDropzone)
- 정책식: `proxy max_size ≥ upload.max_bytes * content_length_slack_ratio`
- 다른 배수("1.1배" 등) 혼용 금지
- /api/config/public scope 제약 (민감정보 금지 / 프론트 필수 기준)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
190 lines
5.0 KiB
Markdown
190 lines
5.0 KiB
Markdown
# 배포 가이드
|
|
|
|
## 1. 사전 요구사항
|
|
|
|
- Docker & Docker Compose (Mac mini)
|
|
- NAS SMB 마운트 (`/Volumes/Document_Server`)
|
|
- Tailscale VPN 연결 (Mac mini ↔ GPU 서버 ↔ NAS)
|
|
|
|
## 2. Mac mini 배포
|
|
|
|
### 2-1. 코드 가져오기
|
|
|
|
```bash
|
|
cd ~/Documents/code/
|
|
git clone https://git.hyungi.net/hyungi/hyungi_document_server.git hyungi_Document_Server
|
|
cd hyungi_Document_Server
|
|
```
|
|
|
|
### 2-2. 인증 정보 설정
|
|
|
|
```bash
|
|
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 마운트 확인
|
|
|
|
```bash
|
|
# 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. 서비스 시작
|
|
|
|
```bash
|
|
docker compose up -d
|
|
|
|
# 상태 확인
|
|
docker compose ps
|
|
docker compose logs -f fastapi
|
|
```
|
|
|
|
### 2-5. 확인
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
cd ~/Documents/code/hyungi_Document_Server/gpu-server/
|
|
cp ../credentials.env .env # 필요한 값만 복사
|
|
docker compose up -d
|
|
```
|
|
|
|
### 3-2. 모델 확인
|
|
|
|
```bash
|
|
# 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 확인
|
|
|
|
```bash
|
|
curl http://localhost:8080/health
|
|
```
|
|
|
|
## 4. 업데이트
|
|
|
|
```bash
|
|
# 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. 로그 확인
|
|
|
|
```bash
|
|
# 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` 블록.
|
|
|
|
```yaml
|
|
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 백업
|
|
|
|
```bash
|
|
docker compose exec postgres pg_dump -U pkm pkm > backup_$(date +%Y%m%d).sql
|
|
```
|