# Site11 빠른 참조 가이드

## 🚀 빠른 시작

### 전체 시스템 시작
```bash
# 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 관리
```bash
# 전체 서비스 상태
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 관리
```bash
# 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
```

### 시스템 상태 확인
```bash
# 전체 상태 체크
./scripts/status-check.sh

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

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

## 🗃️ 데이터베이스 관리

### MongoDB
```bash
# 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 (큐 관리)
```bash
# 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
```

## 🔄 파이프라인 관리

### 언어 동기화
```bash
# 수동 동기화 실행
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
```

### 파이프라인 작업 실행
```bash
# 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"
```

## 🛠️ 문제 해결

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

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

### Pod 시작 실패
```bash
# 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>
```

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

## 📈 모니터링

### 실시간 모니터링
```bash
# 전체 시스템 상태 실시간 확인
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'
```

### 로그 모니터링
```bash
# 전체 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 / (초기 비밀번호는 컨테이너에서 확인)

## 🏗️ 개발 도구

### 이미지 빌드
```bash
# 개별 서비스 빌드
docker-compose build console-backend

# 전체 빌드
docker-compose build

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

### 레지스트리 관리
```bash
# 레지스트리 캐시 시작
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 연결 문제
```bash
# 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 문제
```bash
# FastAPI 로그 확인
kubectl -n site11-pipeline logs deployment/console-backend --tail=50

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

### 파이프라인 작업 막힘
```bash
# 큐 상태 상세 확인
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`