87683ca000
- NAS fail-fast: 시작 시 /documents/PKM 존재 확인, NFS 미마운트 방지 - ollama/ai-gateway 포트를 127.0.0.1로 제한 (외부 무인증 접근 차단) - deploy.md: Caddy HTTPS 자동발급 → 앞단 프록시 HTTPS 종료 구조 반영 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
155 lines
3.4 KiB
Markdown
155 lines
3.4 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. 백업
|
|
|
|
### 우선순위
|
|
|
|
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
|
|
```
|