site11/docs/QUICK_REFERENCE.md

Site11 빠른 참조 가이드

🚀 빠른 시작

전체 시스템 시작

# 1. 인프라 시작 (Docker)
docker-compose -f docker-compose-hybrid.yml up -d

# 2. 애플리케이션 배포 (Kubernetes)
./deploy-dockerhub.sh

# 3. 포트 포워딩 시작
./scripts/start-k8s-port-forward.sh

# 4. 상태 확인
./scripts/status-check.sh

# 5. 브라우저에서 확인
open http://localhost:8080

📊 주요 엔드포인트

서비스	URL	설명
Console Frontend	http://localhost:8080	관리 대시보드
Console Backend	http://localhost:8000	API Gateway
Health Check	http://localhost:8000/health	백엔드 상태
API Health	http://localhost:8000/api/health	API 상태
Users Health	http://localhost:8000/api/users/health	사용자 서비스 상태
Pipeline Monitor	http://localhost:8100	파이프라인 모니터링
Pipeline Scheduler	http://localhost:8099	스케줄러 상태

🔧 주요 명령어

Docker 관리

# 전체 서비스 상태
docker-compose -f docker-compose-hybrid.yml ps

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

# 서비스 재시작
docker-compose -f docker-compose-hybrid.yml restart mongodb

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

Kubernetes 관리

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

# 서비스 상태 확인
kubectl -n site11-pipeline get services

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

# 특정 Pod 로그
kubectl -n site11-pipeline logs -f deployment/console-backend

# Pod 재시작
kubectl -n site11-pipeline rollout restart deployment/console-backend

시스템 상태 확인

# 전체 상태 체크
./scripts/status-check.sh

# 포트 포워딩 상태
ps aux | grep "kubectl.*port-forward"

# 리소스 사용량
kubectl -n site11-pipeline top pods

🗃️ 데이터베이스 관리

MongoDB

# MongoDB 접속
docker exec -it site11_mongodb mongosh

# 데이터베이스 사용
use ai_writer_db

# 컬렉션 목록
show collections

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

# 언어별 동기화 상태 확인
docker exec site11_mongodb mongosh ai_writer_db --quiet --eval '
var ko_count = db.articles_ko.countDocuments({});
var collections = ["articles_en", "articles_zh_cn", "articles_zh_tw", "articles_ja"];
collections.forEach(function(coll) {
  var count = db[coll].countDocuments({});
  print(coll + ": " + count + " (" + (ko_count - count) + " missing)");
});'

Redis (큐 관리)

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

# 큐 길이 확인
LLEN queue:translation
LLEN queue:ai_generation
LLEN queue:image_generation

# 큐 내용 확인 (첫 번째 항목)
LINDEX queue:translation 0

# 큐 비우기 (주의!)
DEL queue:translation

🔄 파이프라인 관리

언어 동기화

# 수동 동기화 실행
docker exec -it site11_language_sync python language_sync.py sync

# 특정 언어만 동기화
docker exec -it site11_language_sync python language_sync.py sync --target-lang en

# 동기화 상태 확인
docker exec -it site11_language_sync python language_sync.py status

파이프라인 작업 실행

# RSS 수집 작업 추가
docker exec -it site11_pipeline_scheduler python -c "
import redis
r = redis.Redis(host='redis', port=6379)
r.lpush('queue:rss_collection', '{\"url\": \"https://example.com/rss\"}')
"

# 번역 작업 상태 확인
./scripts/status-check.sh | grep -A 10 "Queue Status"

🛠️ 문제 해결

포트 충돌

# 포트 사용 중인 프로세스 확인
lsof -i :8080
lsof -i :8000

# 포트 포워딩 재시작
pkill -f "kubectl.*port-forward"
./scripts/start-k8s-port-forward.sh

Pod 시작 실패

# Pod 상세 정보 확인
kubectl -n site11-pipeline describe pod <pod-name>

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

# 이미지 풀 재시도
kubectl -n site11-pipeline delete pod <pod-name>

서비스 연결 실패

# 네트워크 연결 테스트
kubectl -n site11-pipeline exec -it deployment/console-backend -- bash
> curl host.docker.internal:6379  # Redis
> curl host.docker.internal:27017 # MongoDB

📈 모니터링

실시간 모니터링

# 전체 시스템 상태 실시간 확인
watch -n 5 './scripts/status-check.sh'

# Kubernetes 리소스 모니터링
watch -n 2 'kubectl -n site11-pipeline get pods,hpa'

# 큐 상태 모니터링
watch -n 5 'docker exec site11_redis redis-cli info replication'

로그 모니터링

# 전체 Docker 로그
docker-compose -f docker-compose-hybrid.yml logs -f

# 전체 Kubernetes 로그
kubectl -n site11-pipeline logs -f -l app=console-backend

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

🔐 인증 정보

Console 로그인

• URL: http://localhost:8080
• Admin: admin / admin123
• User: user / user123

Harbor Registry (옵션)

• URL: http://localhost:8880
• Admin: admin / Harbor12345

Nexus Repository (옵션)

• URL: http://localhost:8081
• Admin: admin / (초기 비밀번호는 컨테이너에서 확인)

🏗️ 개발 도구

이미지 빌드

# 개별 서비스 빌드
docker-compose build console-backend

# 전체 빌드
docker-compose build

# 캐시 사용 빌드
./scripts/build-with-cache.sh console-backend

레지스트리 관리

# 레지스트리 캐시 시작
docker-compose -f docker-compose-registry-cache.yml up -d

# 캐시 상태 확인
./scripts/manage-registry.sh status

# 캐시 정리
./scripts/manage-registry.sh clean

📚 유용한 스크립트

스크립트	설명
./scripts/status-check.sh	전체 시스템 상태 확인
./scripts/start-k8s-port-forward.sh	Kubernetes 포트 포워딩 시작
./scripts/setup-registry-cache.sh	Docker 레지스트리 캐시 설정
./scripts/backup-mongodb.sh	MongoDB 백업
./deploy-dockerhub.sh	Docker Hub 배포
./deploy-local.sh	로컬 레지스트리 배포

🔍 디버깅 팁

Console Frontend 연결 문제

# nginx 설정 확인
kubectl -n site11-pipeline exec deployment/console-frontend -- cat /etc/nginx/conf.d/default.conf

# 환경 변수 확인
kubectl -n site11-pipeline exec deployment/console-frontend -- env | grep VITE

Console Backend API 문제

# FastAPI 로그 확인
kubectl -n site11-pipeline logs deployment/console-backend --tail=50

# 헬스 체크 직접 호출
kubectl -n site11-pipeline exec deployment/console-backend -- curl localhost:8000/health

파이프라인 작업 막힘

# 큐 상태 상세 확인
docker exec site11_redis redis-cli info stats

# 워커 프로세스 확인
kubectl -n site11-pipeline top pods | grep pipeline

# 메모리 사용량 확인
kubectl -n site11-pipeline describe pod <pipeline-pod-name>

📞 지원 및 문의

• 문서: /docs 디렉토리
• 이슈 트래커: http://gitea.yakenator.io/aimond/site11/issues
• 로그 위치: docker-compose logs 또는 kubectl logs
• 설정 파일: k8s/pipeline/, docker-compose*.yml