docs: Add comprehensive README with detailed build and deployment instructions
- 시스템 요구사항 및 포트 사용 정보 - 단계별 설치 가이드 (Quick Start & Detailed) - 서비스 아키텍처 설명 - 개별 서비스 관리 방법 - 환경 설정 (API 키 등) - 개발 가이드 및 테스트 - 상세한 문제 해결 가이드 - Git 저장소 관리 방법 - 모니터링 및 백업 가이드
This commit is contained in:
jungwoo choi
443
README.md
443
README.md
@ -1,29 +1,430 @@
|
||||
# Site11 - Microservices Architecture
|
||||
# Site11 - Multi-Language News Platform with Microservices Architecture
|
||||
|
||||
## Overview
|
||||
Microservices platform with Console as API Gateway orchestrating multiple domain services.
|
||||
## 📋 목차 (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)
|
||||
|
||||
## Quick Start
|
||||
## 개요 (Overview)
|
||||
|
||||
### Start Services
|
||||
```bash
|
||||
# Start console service
|
||||
docker-compose up -d console-backend
|
||||
Site11은 다국어 뉴스 콘텐츠를 자동으로 수집, 번역, 생성하는 마이크로서비스 기반 플랫폼입니다.
|
||||
|
||||
# Check status
|
||||
curl http://localhost:8011/health
|
||||
### 주요 기능
|
||||
- 🌐 8개 언어 자동 번역 (한국어, 영어, 중국어, 일본어, 프랑스어, 독일어, 스페인어, 이탈리아어)
|
||||
- 📰 실시간 뉴스 수집 및 AI 기반 콘텐츠 생성
|
||||
- 🎨 자동 이미지 생성 및 최적화
|
||||
- 🔄 비동기 작업 처리 파이프라인
|
||||
- 📊 실시간 모니터링 및 통계
|
||||
|
||||
## 시스템 요구사항 (System Requirements)
|
||||
|
||||
### 필수 요구사항
|
||||
- **Docker**: 20.10.0 이상
|
||||
- **Docker Compose**: 2.0.0 이상
|
||||
- **메모리**: 최소 8GB RAM (16GB 권장)
|
||||
- **디스크**: 최소 50GB 여유 공간
|
||||
- **OS**: Linux, macOS, Windows with WSL2
|
||||
|
||||
### 포트 사용
|
||||
```
|
||||
- 80: Nginx (Reverse Proxy)
|
||||
- 8000-8100: 마이크로서비스 백엔드
|
||||
- 3000-3100: 프론트엔드 서비스
|
||||
- 27017: MongoDB
|
||||
- 6379: Redis
|
||||
- 9092: Kafka
|
||||
- 2181: Zookeeper
|
||||
- 9000: MinIO
|
||||
- 8983: Solr
|
||||
```
|
||||
|
||||
### Available Endpoints
|
||||
- `http://localhost:8011/` - Root endpoint
|
||||
- `http://localhost:8011/health` - Health check
|
||||
- `http://localhost:8011/api/status` - System status
|
||||
## 빠른 시작 (Quick Start)
|
||||
|
||||
## Architecture
|
||||
- **Console**: API Gateway and orchestrator
|
||||
- **Services**: Domain-specific microservices (users, oauth, images, etc.)
|
||||
- **Database**: MongoDB for persistence
|
||||
- **Cache**: Redis for caching and pub/sub
|
||||
### 1. 저장소 클론
|
||||
```bash
|
||||
# HTTPS
|
||||
git clone http://gitea.yakenator.io/aimond/site11.git
|
||||
|
||||
## Development
|
||||
See `docs/PLAN.md` for implementation roadmap and `docs/PROGRESS.md` for current status.
|
||||
# 디렉토리 이동
|
||||
cd site11
|
||||
```
|
||||
|
||||
### 2. 환경 변수 설정
|
||||
```bash
|
||||
# .env 파일 생성
|
||||
cp .env.example .env
|
||||
|
||||
# 필수 환경 변수 설정
|
||||
echo "COMPOSE_PROJECT_NAME=site11" >> .env
|
||||
echo "DEEPL_API_KEY=your-deepl-api-key" >> .env
|
||||
echo "OPENAI_API_KEY=your-openai-api-key" >> .env
|
||||
```
|
||||
|
||||
### 3. 전체 시스템 시작
|
||||
```bash
|
||||
# 모든 서비스 빌드 및 시작 (백그라운드)
|
||||
docker-compose up -d --build
|
||||
|
||||
# 상태 확인
|
||||
docker-compose ps
|
||||
|
||||
# 로그 확인
|
||||
docker-compose logs -f
|
||||
```
|
||||
|
||||
### 4. 서비스 확인
|
||||
```bash
|
||||
# 헬스 체크
|
||||
curl http://localhost:8000/health
|
||||
|
||||
# MongoDB 연결 확인
|
||||
docker exec -it site11_mongodb mongosh --eval "db.serverStatus()"
|
||||
```
|
||||
|
||||
## 상세 설치 가이드 (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단계: Pipeline 서비스
|
||||
```bash
|
||||
# Pipeline 서비스 시작
|
||||
docker-compose up -d pipeline-scheduler pipeline-monitor \
|
||||
pipeline-rss-collector pipeline-google-search \
|
||||
pipeline-ai-generator pipeline-translator \
|
||||
pipeline-image-generator
|
||||
|
||||
# Pipeline 모니터 확인
|
||||
curl http://localhost:8100/status
|
||||
```
|
||||
|
||||
#### 3단계: 뉴스 서비스
|
||||
```bash
|
||||
# 국가별 뉴스 서비스
|
||||
docker-compose up -d korea-backend korea-frontend \
|
||||
usa-backend usa-frontend \
|
||||
japan-backend japan-frontend \
|
||||
china-backend china-frontend
|
||||
|
||||
# 기업 뉴스 서비스
|
||||
docker-compose up -d samsung-backend samsung-frontend \
|
||||
apple-backend apple-frontend \
|
||||
google-backend google-frontend
|
||||
```
|
||||
|
||||
#### 4단계: 아티스트 서비스
|
||||
```bash
|
||||
# K-POP 아티스트 서비스
|
||||
docker-compose up -d k-culture-backend \
|
||||
blackpink-backend blackpink-frontend \
|
||||
ive-backend ive-frontend \
|
||||
twice-backend twice-frontend
|
||||
```
|
||||
|
||||
## 서비스 구조 (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) # 실시간 모니터링
|
||||
```
|
||||
|
||||
### 콘텐츠 서비스
|
||||
- **Media Empire** (8200/3200): 통합 다국어 뉴스 포털
|
||||
- **국가별 서비스**: Korea, USA, Japan, China
|
||||
- **기업 서비스**: Samsung, Apple, Google, LG, Musk, WSJ
|
||||
- **아티스트 서비스**: K-Culture, Blackpink, IVE, Twice 등
|
||||
|
||||
## 서비스 관리 (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
|
||||
WORKER_COUNT=3 # 워커 프로세스 수
|
||||
BATCH_SIZE=10 # 배치 처리 크기
|
||||
TRANSLATION_DELAY=1.0 # 번역 지연 시간
|
||||
```
|
||||
|
||||
## 개발 가이드 (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 가이드
|
||||
|
||||
## 라이선스 (License)
|
||||
|
||||
Copyright (c) 2024 Site11 Project. All rights reserved.
|
||||
Reference in New Issue
Block a user