site11/README.md

# Site11 - Multi-Language News Platform with Microservices Architecture

## 📋 목차 (Table of Contents)
- [개요 (Overview)](#개요-overview)
- [시스템 요구사항 (System Requirements)](#시스템-요구사항-system-requirements)
- [빠른 시작 (Quick Start)](#빠른-시작-quick-start)
- [상세 설치 가이드 (Detailed Installation)](#상세-설치-가이드-detailed-installation)
- [서비스 구조 (Service Architecture)](#서비스-구조-service-architecture)
- [서비스 관리 (Service Management)](#서비스-관리-service-management)
- [환경 설정 (Configuration)](#환경-설정-configuration)
- [개발 가이드 (Development Guide)](#개발-가이드-development-guide)
- [문제 해결 (Troubleshooting)](#문제-해결-troubleshooting)
- [Git 저장소 관리 (Repository Management)](#git-저장소-관리-repository-management)

## 개요 (Overview)

Site11은 다국어 뉴스 콘텐츠를 자동으로 수집, 번역, 생성하는 마이크로서비스 기반 플랫폼입니다.

### 주요 기능
- 🌐 8개 언어 자동 번역 (한국어, 영어, 중국어, 일본어, 프랑스어, 독일어, 스페인어, 이탈리아어)
- 📰 실시간 뉴스 수집 및 AI 기반 콘텐츠 생성
- 🎨 자동 이미지 생성 및 최적화
- 🔄 비동기 작업 처리 파이프라인
- 📊 실시간 모니터링 및 통계

## 시스템 요구사항 (System Requirements)

### 필수 요구사항
- **Docker**: 20.10.0 이상
- **Docker Compose**: 2.0.0 이상
- **메모리**: 최소 8GB RAM (16GB 권장)
- **디스크**: 최소 50GB 여유 공간
- **OS**: Linux, macOS, Windows with WSL2

### 포트 사용

#### 하이브리드 배포 포트 구성 (현재 구성)
```
[ Docker Compose - 인프라 서비스 ]
- 27017: MongoDB (내부)
- 6379: Redis (내부)
- 9092: Kafka (내부)
- 2181: Zookeeper (내부)
- 5555: Docker Registry (내부)
- 8099: Pipeline Scheduler
- 8100: Pipeline Monitor

[ Kubernetes - 마이크로서비스 ]
- 8080: Console Frontend (kubectl port-forward → Service:3000 → Pod:80)
- 8000: Console Backend (kubectl port-forward → Service:8000 → Pod:8000)
- 30801-30802: Images Service (→ 8001-8002)
- 30803-30804: OAuth Service (→ 8003-8004)
- 30805-30806: Applications Service (→ 8005-8006)
- 30807-30808: Users Service (→ 8007-8008)
- 30809-30810: Data Service (→ 8009-8010)
- 30811-30812: Statistics Service (→ 8011-8012)

[ Pipeline Workers (K8s 내부) ]
- RSS Collector
- Google Search
- Translator
- AI Article Generator
- Image Generator
```

#### 표준 Docker Compose 포트 구성 (전체 Docker 모드)
```
- 3000: Console Frontend
- 8000: Console Backend (API Gateway)
- 8001-8002: Images Service
- 8003-8004: OAuth Service
- 8005-8006: Applications Service
- 8007-8008: Users Service
- 8009-8010: Data Service
- 8011-8012: Statistics Service
- 8099: Pipeline Scheduler
- 8100: Pipeline Monitor
- 27017: MongoDB (내부)
- 6379: Redis (내부)
- 9092: Kafka (내부)
- 2181: Zookeeper (내부)
```

## 빠른 시작 (Quick Start)

### 1. 저장소 클론
```bash
# HTTPS
git clone http://gitea.yakenator.io/aimond/site11.git

# 디렉토리 이동
cd site11
```

### 2. 환경 변수 설정
```bash
# .env 파일 생성
cp .env.example .env

# 필수 환경 변수 편집 (실제 API 키로 교체 필요)
vim .env
# 다음 항목들을 추가:
# DEEPL_API_KEY=your-deepl-api-key
# OPENAI_API_KEY=your-openai-api-key
# CLAUDE_API_KEY=your-claude-api-key
# SERP_API_KEY=your-serp-api-key
```

### 3. 전체 시스템 시작
```bash
# 모든 서비스 빌드 및 시작 (백그라운드)
docker-compose up -d --build

# 상태 확인
docker-compose ps

# 로그 확인
docker-compose logs -f
```

### 4. 서비스 확인

#### 하이브리드 배포 확인 (현재 구성)
```bash
# Console Frontend 접속 (kubectl port-forward)
open http://localhost:8080

# Console API 헬스 체크 (kubectl port-forward)
curl http://localhost:8000/health
curl http://localhost:8000/api/health

# Port forwarding 시작 (필요시)
kubectl -n site11-pipeline port-forward service/console-frontend 8080:3000 &
kubectl -n site11-pipeline port-forward service/console-backend 8000:8000 &

# Pipeline 모니터 확인 (Docker)
curl http://localhost:8100/health

# MongoDB 연결 확인 (Docker)
docker exec -it site11_mongodb mongosh --eval "db.serverStatus()"

# K8s Pod 상태 확인
kubectl -n site11-pipeline get pods
kubectl -n site11-pipeline get services
```

#### 표준 Docker 확인
```bash
# Console Frontend 접속
open http://localhost:3000

# Console API 헬스 체크
curl http://localhost:8000/health

# MongoDB 연결 확인
docker exec -it site11_mongodb mongosh --eval "db.serverStatus()"

# Pipeline 모니터 확인
curl http://localhost:8100/health
```

## 상세 설치 가이드 (Detailed Installation)

### 단계별 서비스 시작

#### 1단계: 핵심 인프라
```bash
# MongoDB, Redis, Kafka 시작
docker-compose up -d mongodb redis zookeeper kafka

# 인프라 준비 대기 (약 30초)
sleep 30

# 상태 확인
docker-compose ps mongodb redis kafka
```

#### 2단계: 핵심 백엔드 서비스
```bash
# 핵심 서비스 시작
docker-compose up -d console-backend users-backend \
  oauth-backend images-backend files-backend \
  statistics-backend search-backend

# 서비스 상태 확인
docker-compose ps | grep backend
```

#### 3단계: Pipeline 서비스
```bash
# Pipeline 서비스 시작
docker-compose up -d pipeline-scheduler pipeline-monitor \
  pipeline-rss-collector pipeline-google-search \
  pipeline-ai-article-generator pipeline-translator \
  pipeline-image-generator pipeline-language-sync

# Pipeline 모니터 확인
curl http://localhost:8100/health
```

#### 4단계: 뉴스 생성 서비스
```bash
# 뉴스 관련 서비스
docker-compose up -d news-aggregator-backend \
  ai-writer-backend ai-writer-worker \
  google-search-backend rss-feed-backend

# AI Writer 상태 확인
curl http://localhost:8019/health
```

#### 5단계: 프론트엔드 서비스
```bash
# Console 프론트엔드
docker-compose up -d console-frontend

# 웹 UI 접속
# http://localhost:3000
```

## 서비스 구조 (Service Architecture)

### 핵심 인프라
- **MongoDB**: 데이터 저장소
- **Redis**: 캐시 및 작업 큐
- **Kafka**: 이벤트 스트리밍
- **MinIO**: 이미지/파일 저장소
- **Solr**: 검색 엔진

### Pipeline 서비스
```
pipeline-scheduler (8099)
  ├── pipeline-rss-collector     # RSS 피드 수집
  ├── pipeline-google-search     # Google 검색 수집
  ├── pipeline-ai-generator      # AI 콘텐츠 생성
  ├── pipeline-translator        # 다국어 번역
  └── pipeline-image-generator   # 이미지 생성

pipeline-monitor (8100)          # 실시간 모니터링
```

### 콘텐츠 서비스
- **Console** (8011/3000): 관리 콘솔
- **AI Writer** (8019): AI 콘텐츠 생성
- **News Aggregator** (8018): 뉴스 수집
- **Google Search** (8016): 검색 서비스
- **RSS Feed** (8017): RSS 피드 수집

## 서비스 관리 (Service Management)

### 개별 서비스 관리
```bash
# 특정 서비스만 시작
docker-compose up -d [service-name]

# 특정 서비스 재시작
docker-compose restart [service-name]

# 특정 서비스 중지
docker-compose stop [service-name]

# 서비스 로그 확인
docker-compose logs -f [service-name]

# 서비스 재빌드
docker-compose build [service-name]
docker-compose up -d [service-name]
```

### 데이터베이스 관리
```bash
# MongoDB 접속
docker exec -it site11_mongodb mongosh

# 데이터베이스 목록
show dbs

# AI Writer DB 사용
use ai_writer_db

# 컬렉션 확인
show collections

# 기사 수 확인
db.articles_ko.countDocuments()
```

### Redis 관리
```bash
# Redis CLI 접속
docker exec -it site11_redis redis-cli

# 모든 키 확인
KEYS *

# 큐 상태 확인
LLEN queue:google_search
LLEN queue:ai_generation
LLEN queue:translation
```

## 환경 설정 (Configuration)

### 필수 API 키 설정
```bash
# .env 파일 편집
vim .env

# 필수 설정
DEEPL_API_KEY=your-deepl-api-key        # 번역 API
OPENAI_API_KEY=your-openai-api-key      # 이미지 생성
CLAUDE_API_KEY=your-claude-api-key      # AI 콘텐츠 생성
SERP_API_KEY=your-serp-api-key          # Google 검색
```

### Pipeline 설정
```bash
# services/pipeline/.env 파일 생성
cat > services/pipeline/.env << EOF
DEEPL_API_KEY=your-deepl-api-key
OPENAI_API_KEY=your-openai-api-key
CLAUDE_API_KEY=your-claude-api-key
SERP_API_KEY=your-serp-api-key
WORKER_COUNT=3
BATCH_SIZE=10
TRANSLATION_DELAY=1.0
EOF
```

## 개발 가이드 (Development Guide)

### 새 서비스 추가
```bash
# 서비스 디렉토리 구조
services/
  └── new-service/
      ├── backend/
      │   ├── Dockerfile
      │   ├── requirements.txt
      │   └── main.py
      └── frontend/
          ├── Dockerfile
          ├── package.json
          └── src/
```

### 로컬 개발 환경
```bash
# 백엔드 개발 (Python)
cd services/[service-name]/backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python main.py

# 프론트엔드 개발 (React)
cd services/[service-name]/frontend
npm install
npm run dev
```

### 테스트 실행
```bash
# 통합 테스트
python test_integration.py

# Pipeline 테스트
python services/pipeline/test_pipeline.py

# 특정 서비스 테스트
docker exec -it site11_[service-name] pytest
```

## 문제 해결 (Troubleshooting)

### 서비스가 시작되지 않을 때
```bash
# 포트 충돌 확인
lsof -i :8000

# 컨테이너 상태 확인
docker ps -a | grep site11

# 오류 로그 확인
docker-compose logs [service-name] | tail -100
```

### MongoDB 연결 문제
```bash
# MongoDB 상태 확인
docker exec -it site11_mongodb mongosh --eval "db.serverStatus()"

# 연결 테스트
docker run --rm -it --network site11_network mongo:7.0 mongosh mongodb://mongodb:27017
```

### 메모리 부족 문제
```bash
# Docker 리소스 정리
docker system prune -a

# 불필요한 이미지 삭제
docker image prune -a

# 컨테이너 로그 정리
docker-compose logs --tail=0 --follow
```

### Pipeline 작업 막힘
```bash
# Redis 큐 확인
docker exec -it site11_redis redis-cli
> LLEN queue:translation
> LPOP queue:translation  # 막힌 작업 제거

# Pipeline 재시작
docker-compose restart pipeline-scheduler pipeline-translator
```

## Git 저장소 관리 (Repository Management)

### .gitignore 설정
```
# 대용량 파일 제외
backups/
*.archive
*.log
data/

# 이미지 파일 제외
*.png
*.jpg
*.jpeg

# Node modules 제외
node_modules/
**/node_modules/

# 환경 파일
.env
*.env.local
```

### 저장소 정리
```bash
# Git 히스토리 정리
git gc --aggressive --prune=now

# 대용량 파일 찾기
find . -size +100M -type f

# 캐시 정리
git rm -r --cached [file/folder]
```

## 모니터링 (Monitoring)

### Pipeline 모니터링
- URL: http://localhost:8100
- 실시간 큐 상태 확인
- 처리 통계 확인

### 로그 모니터링
```bash
# 전체 로그 스트림
docker-compose logs -f

# 특정 서비스 로그
docker-compose logs -f pipeline-scheduler

# 에러만 필터링
docker-compose logs -f 2>&1 | grep ERROR
```

### 성능 모니터링
```bash
# 컨테이너 리소스 사용량
docker stats

# MongoDB 성능
docker exec -it site11_mongodb mongosh --eval "db.serverStatus().opcounters"
```

## 백업 및 복구 (Backup & Recovery)

### MongoDB 백업
```bash
# 백업 스크립트 실행
./scripts/backup-mongodb.sh

# 수동 백업
docker exec -it site11_mongodb mongodump --archive=/data/backup.archive
docker cp site11_mongodb:/data/backup.archive ./backups/
```

### 전체 시스템 백업
```bash
# 데이터 디렉토리 백업
tar -czf backup-$(date +%Y%m%d).tar.gz data/

# 설정 백업
tar -czf config-backup.tar.gz .env docker-compose.yml services/
```

## 문의 및 지원 (Support)

- **이슈 트래커**: http://gitea.yakenator.io/aimond/site11/issues
- **문서**: `/docs` 디렉토리 참조
  - `PLAN.md`: 구현 계획
  - `PROGRESS.md`: 진행 상황
  - `ARCHITECTURE.md`: 시스템 구조
  - `PIPELINE_SCHEDULER_GUIDE.md`: Pipeline 가이드

## 하이브리드 배포 (Hybrid Deployment with K8s)

Site11은 Docker Compose와 Kubernetes를 함께 사용하는 하이브리드 배포를 지원합니다.

### 배포 아키텍처

#### Docker Compose (인프라 서비스)
- **인프라**: MongoDB, Redis, Kafka, Zookeeper
- **중앙 제어**: Pipeline Scheduler, Pipeline Monitor, Language Sync
- **레지스트리**: Docker Registry (port 5555)

#### Kubernetes (애플리케이션 및 파이프라인)
- **관리 콘솔**: Console Backend/Frontend
- **마이크로서비스**: Images, OAuth, Applications, Users, Data, Statistics
- **데이터 수집**: RSS Collector, Google Search
- **처리 워커**: Translator, AI Article Generator, Image Generator
- **자동 스케일링**: HPA(Horizontal Pod Autoscaler) 적용

### 하이브리드 배포 시작

#### 1. Docker 인프라 시작
```bash
# 하이브리드 용 docker-compose 사용
docker-compose -f docker-compose-hybrid.yml up -d

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

# 로그 확인
docker-compose -f docker-compose-hybrid.yml logs -f pipeline-scheduler
```

#### 2. Docker Hub를 사용한 K8s 배포 (권장)
```bash
# Docker Hub에 이미지 푸시
./deploy-dockerhub.sh

# K8s 네임스페이스 및 설정 생성
kubectl create namespace site11-pipeline
kubectl -n site11-pipeline apply -f k8s/pipeline/configmap.yaml
kubectl -n site11-pipeline apply -f k8s/pipeline/secrets.yaml

# Docker Hub 이미지로 배포
cd k8s/pipeline
for service in console-backend console-frontend \
  ai-article-generator translator image-generator \
  rss-collector google-search; do
  kubectl apply -f ${service}-dockerhub.yaml
done

# 배포 상태 확인
kubectl -n site11-pipeline get pods
kubectl -n site11-pipeline get services
kubectl -n site11-pipeline get hpa
```

#### 3. 로컬 레지스트리를 사용한 K8s 배포 (대안)
```bash
# 로컬 레지스트리 시작 (Docker Compose)
docker-compose -f docker-compose-hybrid.yml up -d registry

# 이미지 빌드 및 푸시
./deploy-local.sh

# K8s 배포
cd k8s/pipeline
./deploy.sh

# 배포 상태 확인
kubectl -n site11-pipeline get pods
kubectl -n site11-pipeline get hpa
```

### K8s 자동 스케일링 설정

#### HPA (Horizontal Pod Autoscaler) 구성
| 서비스 | 최소 Pod | 최대 Pod | CPU 임계값 | 메모리 임계값 |
|--------|---------|---------|------------|-------------|
| RSS Collector | 1 | 5 | 70% | 80% |
| Google Search | 1 | 5 | 70% | 80% |
| Translator | 2 | 10 | 70% | 80% |
| AI Generator | 1 | 8 | 70% | 80% |
| Image Generator | 1 | 6 | 70% | 80% |

#### 스케일링 모니터링
```bash
# HPA 상태 실시간 모니터링
kubectl -n site11-pipeline get hpa -w

# Pod 수 확인
kubectl -n site11-pipeline get pods -o wide

# 메트릭 상세 정보
kubectl -n site11-pipeline describe hpa pipeline-translator-hpa

# 수동 스케일링 (필요시)
kubectl -n site11-pipeline scale deployment pipeline-translator --replicas=5
```

### K8s 워커 관리

#### 로그 확인
```bash
# 특정 디플로이먼트 로그
kubectl -n site11-pipeline logs -f deployment/pipeline-translator

# 모든 Pod 로그
kubectl -n site11-pipeline logs -f -l component=processor

# 에러만 필터링
kubectl -n site11-pipeline logs -f deployment/pipeline-translator | grep ERROR
```

#### 업데이트 및 롤백
```bash
# 이미지 업데이트
kubectl -n site11-pipeline set image deployment/pipeline-translator \
  translator=site11/pipeline-translator:v2

# 롤아웃 상태 확인
kubectl -n site11-pipeline rollout status deployment/pipeline-translator

# 롤백 (필요시)
kubectl -n site11-pipeline rollout undo deployment/pipeline-translator
```

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

# Node 리소스 사용량
kubectl top nodes

# 상세 리소스 정보
kubectl -n site11-pipeline describe pod <pod-name>
```

### 문제 해결 (K8s)

#### Pod가 시작되지 않을 때
```bash
# Pod 상태 확인
kubectl -n site11-pipeline describe pod <pod-name>

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

# 이미지 풀 문제 확인
kubectl -n site11-pipeline get pods -o jsonpath='{.items[*].spec.containers[*].image}'
```

#### Redis/MongoDB 연결 실패
```bash
# Docker 호스트 네트워크 확인
# K8s Pod는 host.docker.internal 사용
kubectl -n site11-pipeline exec -it <pod-name> -- ping host.docker.internal

# 연결 테스트
kubectl -n site11-pipeline exec -it <pod-name> -- redis-cli -h host.docker.internal ping
```

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

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

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

## 라이선스 (License)

Copyright (c) 2024 Site11 Project. All rights reserved.