aimond/site11
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1ff9afe6f43712b65f9321b19198af8228fd33ac
site11/README.md
jungwoo choi 1ff9afe6f4 fix: Correct README with actual service names and configurations 
- 실제 docker-compose.yml 서비스 이름으로 수정
- 정확한 포트 매핑 정보 업데이트
- 환경 변수 설정 방법 구체화
- Pipeline 설정 파일 생성 방법 추가
- 존재하지 않는 서비스 제거 (korea-backend, usa-backend 등)
2025-09-28 20:48:59 +09:00

10 KiB
Raw Blame History

Site11 - Multi-Language News Platform with Microservices Architecture

📋 목차 (Table of Contents)

개요 (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

포트 사용

- 3000: Console Frontend
- 8011: Console Backend (API Gateway)
- 8012: Users Backend
- 8013: Notifications Backend
- 8014: OAuth Backend
- 8015: Images Backend
- 8016: Google Search Backend
- 8017: RSS Feed Backend
- 8018: News Aggregator Backend
- 8019: AI Writer Backend
- 8100: Pipeline Monitor
- 8983: Solr Search Engine
- 9000: MinIO Object Storage
- 9001: MinIO Console
- 27017: MongoDB (내부)
- 6379: Redis (내부)
- 9092: Kafka (내부)
- 2181: Zookeeper (내부)

빠른 시작 (Quick Start)

1. 저장소 클론

# HTTPS
git clone http://gitea.yakenator.io/aimond/site11.git

# 디렉토리 이동
cd site11

2. 환경 변수 설정

# .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. 전체 시스템 시작

# 모든 서비스 빌드 및 시작 (백그라운드)
docker-compose up -d --build

# 상태 확인
docker-compose ps

# 로그 확인
docker-compose logs -f

4. 서비스 확인

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

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

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

# Console UI 접속
open http://localhost:3000

상세 설치 가이드 (Detailed Installation)

단계별 서비스 시작

1단계: 핵심 인프라

# MongoDB, Redis, Kafka 시작
docker-compose up -d mongodb redis zookeeper kafka

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

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

2단계: 핵심 백엔드 서비스

# 핵심 서비스 시작
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 서비스

# 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단계: 뉴스 생성 서비스

# 뉴스 관련 서비스
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단계: 프론트엔드 서비스

# 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)

개별 서비스 관리

# 특정 서비스만 시작
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]

데이터베이스 관리

# MongoDB 접속
docker exec -it site11_mongodb mongosh

# 데이터베이스 목록
show dbs

# AI Writer DB 사용
use ai_writer_db

# 컬렉션 확인
show collections

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

Redis 관리

# Redis CLI 접속
docker exec -it site11_redis redis-cli

# 모든 키 확인
KEYS *

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

환경 설정 (Configuration)

필수 API 키 설정

# .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 설정

# 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)

새 서비스 추가

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

로컬 개발 환경

# 백엔드 개발 (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

테스트 실행

# 통합 테스트
python test_integration.py

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

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

문제 해결 (Troubleshooting)

서비스가 시작되지 않을 때

# 포트 충돌 확인
lsof -i :8000

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

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

MongoDB 연결 문제

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

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

메모리 부족 문제

# Docker 리소스 정리
docker system prune -a

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

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

Pipeline 작업 막힘

# 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

저장소 정리

# Git 히스토리 정리
git gc --aggressive --prune=now

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

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

모니터링 (Monitoring)

Pipeline 모니터링

로그 모니터링

# 전체 로그 스트림
docker-compose logs -f

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

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

성능 모니터링

# 컨테이너 리소스 사용량
docker stats

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

백업 및 복구 (Backup & Recovery)

MongoDB 백업

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

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

전체 시스템 백업

# 데이터 디렉토리 백업
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.