site11/docs/DEPLOYMENT_GUIDE.md

# Site11 배포 가이드

## 📋 목차
- [배포 아키텍처](#배포-아키텍처)
- [배포 옵션](#배포-옵션)
- [하이브리드 배포 (권장)](#하이브리드-배포-권장)
- [포트 구성](#포트-구성)
- [Health Check](#health-check)
- [문제 해결](#문제-해결)

## 배포 아키텍처

### 현재 구성: 하이브리드 아키텍처
```
┌─────────────────────────────────────────────────────────┐
│                    사용자 브라우저                         │
└────────────┬────────────────────┬──────────────────────┘
             │                    │
        localhost:8080       localhost:8000
             │                    │
    ┌────────┴──────────┐ ┌──────┴──────────┐
    │ kubectl           │ │ kubectl         │
    │ port-forward      │ │ port-forward    │
    └────────┬──────────┘ └──────┬──────────┘
             │                    │
    ┌────────┴──────────────────┴──────────┐
    │        Kubernetes Cluster (Kind)      │
    │                                        │
    │  ┌──────────────┐  ┌──────────────┐  │
    │  │ Console      │  │ Console      │  │
    │  │ Frontend     │  │ Backend      │  │
    │  │ Service:3000 │  │ Service:8000 │  │
    │  └──────┬───────┘  └──────┬───────┘  │
    │         │                  │          │
    │  ┌──────┴───────┐  ┌──────┴───────┐  │
    │  │ nginx:80     │  │ FastAPI:8000 │  │
    │  │ (Pod)        │  │ (Pod)        │  │
    │  └──────────────┘  └──────┬───────┘  │
    │                            │          │
    │  ┌─────────────────────────┴───────┐  │
    │  │ Pipeline Workers (5 Deployments) │  │
    │  └──────────────┬──────────────────┘  │
    └─────────────────┼──────────────────┘
                      │
         host.docker.internal
                      │
    ┌─────────────────┴──────────────────┐
    │     Docker Compose Infrastructure   │
    │                                      │
    │  MongoDB | Redis | Kafka | Zookeeper│
    │  Pipeline Scheduler | Monitor        │
    └──────────────────────────────────────┘
```

## 배포 옵션

### 옵션 1: 하이브리드 배포 (현재/권장)
- **Docker Compose**: 인프라 서비스 (MongoDB, Redis, Kafka)
- **Kubernetes**: 애플리케이션 및 파이프라인 워커
- **장점**: 프로덕션 환경과 유사, 확장성 우수
- **단점**: 설정 복잡도 높음

### 옵션 2: 전체 Docker Compose
- **모든 서비스를 Docker Compose로 실행**
- **장점**: 설정 간단, 로컬 개발에 최적
- **단점**: 오토스케일링 제한

### 옵션 3: 전체 Kubernetes
- **모든 서비스를 Kubernetes로 실행**
- **장점**: 완전한 클라우드 네이티브
- **단점**: 로컬 리소스 많이 필요

## 하이브리드 배포 (권장)

### 1. 인프라 시작 (Docker Compose)
```bash
# Docker Compose로 인프라 서비스 시작
docker-compose -f docker-compose-hybrid.yml up -d

# 상태 확인
docker-compose -f docker-compose-hybrid.yml ps

# 서비스 확인
docker ps | grep -E "mongodb|redis|kafka|zookeeper|scheduler|monitor"
```

### 2. Kubernetes 클러스터 준비
```bash
# Docker Desktop Kubernetes 활성화 또는 Kind 사용
# Docker Desktop: Preferences → Kubernetes → Enable Kubernetes

# 네임스페이스 생성
kubectl create namespace site11-pipeline

# ConfigMap 및 Secrets 생성
kubectl -n site11-pipeline apply -f k8s/pipeline/configmap.yaml
kubectl -n site11-pipeline apply -f k8s/pipeline/secrets.yaml
```

### 3. 애플리케이션 배포 (Docker Hub)
```bash
# Docker Hub에 이미지 푸시
export DOCKER_HUB_USER=yakenator
./deploy-dockerhub.sh

# Kubernetes에 배포
cd k8s/pipeline
for yaml in *-dockerhub.yaml; do
  kubectl apply -f $yaml
done

# 배포 확인
kubectl -n site11-pipeline get deployments
kubectl -n site11-pipeline get pods
kubectl -n site11-pipeline get services
```

### 4. Port Forwarding 설정
```bash
# 자동 스크립트 사용
./scripts/start-k8s-port-forward.sh

# 또는 수동 설정
kubectl -n site11-pipeline port-forward service/console-frontend 8080:3000 &
kubectl -n site11-pipeline port-forward service/console-backend 8000:8000 &
```

## 포트 구성

### 하이브리드 배포 포트 매핑
| 서비스 | 로컬 포트 | Service 포트 | Pod 포트 | 설명 |
|--------|----------|-------------|---------|------|
| Console Frontend | 8080 | 3000 | 80 | nginx 정적 파일 서빙 |
| Console Backend | 8000 | 8000 | 8000 | FastAPI API Gateway |
| Pipeline Monitor | 8100 | - | 8100 | Docker 직접 노출 |
| Pipeline Scheduler | 8099 | - | 8099 | Docker 직접 노출 |
| MongoDB | 27017 | - | 27017 | Docker 내부 |
| Redis | 6379 | - | 6379 | Docker 내부 |
| Kafka | 9092 | - | 9092 | Docker 내부 |

### Port Forward 체인
```
사용자 → localhost:8080 → kubectl port-forward → K8s Service:3000 → Pod nginx:80
```

## Health Check

### Console 서비스 Health Check
```bash
# Console Backend Health
curl http://localhost:8000/health
curl http://localhost:8000/api/health

# Console Frontend Health (HTML 응답)
curl http://localhost:8080/

# Users Service Health (via Console Backend)
curl http://localhost:8000/api/users/health
```

### Pipeline 서비스 Health Check
```bash
# Pipeline Monitor
curl http://localhost:8100/health

# Pipeline Scheduler
curl http://localhost:8099/health
```

### Kubernetes Health Check
```bash
# Pod 상태
kubectl -n site11-pipeline get pods -o wide

# 서비스 엔드포인트
kubectl -n site11-pipeline get endpoints

# HPA 상태
kubectl -n site11-pipeline get hpa

# 이벤트 확인
kubectl -n site11-pipeline get events --sort-by='.lastTimestamp'
```

## 스케일링

### Horizontal Pod Autoscaler (HPA)
| 서비스 | 최소 | 최대 | CPU 목표 | 메모리 목표 |
|--------|-----|------|---------|------------|
| Console Frontend | 2 | 10 | 70% | 80% |
| Console Backend | 2 | 10 | 70% | 80% |
| RSS Collector | 1 | 5 | 70% | 80% |
| Google Search | 1 | 5 | 70% | 80% |
| Translator | 3 | 10 | 70% | 80% |
| AI Generator | 2 | 10 | 70% | 80% |
| Image Generator | 2 | 10 | 70% | 80% |

### 수동 스케일링
```bash
# 특정 디플로이먼트 스케일 조정
kubectl -n site11-pipeline scale deployment/pipeline-translator --replicas=5

# 모든 파이프라인 워커 스케일 업
for deploy in rss-collector google-search translator ai-article-generator image-generator; do
  kubectl -n site11-pipeline scale deployment/pipeline-$deploy --replicas=3
done
```

## 모니터링

### 실시간 모니터링
```bash
# Pod 리소스 사용량
kubectl -n site11-pipeline top pods

# 로그 스트리밍
kubectl -n site11-pipeline logs -f deployment/console-backend
kubectl -n site11-pipeline logs -f deployment/pipeline-translator

# HPA 상태 감시
watch -n 2 kubectl -n site11-pipeline get hpa
```

### Pipeline 모니터링
```bash
# Pipeline Monitor 웹 UI
open http://localhost:8100

# Queue 상태 확인
docker exec -it site11_redis redis-cli
> LLEN queue:translation
> LLEN queue:ai_generation
> LLEN queue:image_generation
```

## 문제 해결

### Pod가 시작되지 않을 때
```bash
# Pod 상세 정보
kubectl -n site11-pipeline describe pod <pod-name>

# 이미지 풀 에러 확인
kubectl -n site11-pipeline get events | grep -i pull

# 해결: Docker Hub 이미지 다시 푸시
docker push yakenator/site11-<service>:latest
kubectl -n site11-pipeline rollout restart deployment/<service>
```

### Port Forward 연결 끊김
```bash
# 기존 port-forward 종료
pkill -f "kubectl.*port-forward"

# 다시 시작
./scripts/start-k8s-port-forward.sh
```

### 인프라 서비스 연결 실패
```bash
# Docker 네트워크 확인
docker network ls | grep site11

# K8s Pod에서 연결 테스트
kubectl -n site11-pipeline exec -it <pod-name> -- bash
> apt update && apt install -y netcat
> nc -zv host.docker.internal 6379  # Redis
> nc -zv host.docker.internal 27017 # MongoDB
```

### Health Check 실패
```bash
# Console Backend 로그 확인
kubectl -n site11-pipeline logs deployment/console-backend --tail=50

# 엔드포인트 직접 테스트
kubectl -n site11-pipeline exec -it deployment/console-backend -- curl localhost:8000/health
```

## 정리 및 초기화

### 전체 정리
```bash
# Kubernetes 리소스 삭제
kubectl delete namespace site11-pipeline

# Docker Compose 정리
docker-compose -f docker-compose-hybrid.yml down

# 볼륨 포함 완전 정리 (주의!)
docker-compose -f docker-compose-hybrid.yml down -v
```

### 선택적 정리
```bash
# 특정 디플로이먼트만 삭제
kubectl -n site11-pipeline delete deployment <name>

# 특정 Docker 서비스만 중지
docker-compose -f docker-compose-hybrid.yml stop mongodb
```

## 백업 및 복구

### MongoDB 백업
```bash
# 백업
docker exec site11_mongodb mongodump --archive=/tmp/backup.archive
docker cp site11_mongodb:/tmp/backup.archive ./backups/mongodb-$(date +%Y%m%d).archive

# 복구
docker cp ./backups/mongodb-20240101.archive site11_mongodb:/tmp/
docker exec site11_mongodb mongorestore --archive=/tmp/mongodb-20240101.archive
```

### 전체 설정 백업
```bash
# 설정 파일 백업
tar -czf config-backup-$(date +%Y%m%d).tar.gz \
  k8s/ \
  docker-compose*.yml \
  .env \
  registry/
```

## 다음 단계

1. **프로덕션 준비**
   - Ingress Controller 설정
   - SSL/TLS 인증서
   - 외부 모니터링 통합

2. **성능 최적화**
   - Registry Cache 활성화
   - 빌드 캐시 최적화
   - 리소스 리밋 조정

3. **보안 강화**
   - Network Policy 적용
   - RBAC 설정
   - Secrets 암호화