site11/docs/PIPELINE_SCHEDULER_GUIDE.md

Pipeline Scheduler Guide

개요

Pipeline Scheduler는 등록된 키워드를 주기적으로 실행하여 자동으로 뉴스를 수집하고 AI 기사를 생성하는 시스템입니다.

아키텍처

1. 구성 요소

1.1 Multi-Thread Scheduler (pipeline-scheduler)

• 역할: 키워드별 스레드 관리 및 주기적 실행
• 특징:
  • 단일 Docker 컨테이너에서 여러 스레드 동시 실행
  • 각 키워드당 하나의 독립 스레드
  • 30초마다 새 키워드 체크 및 스레드 관리
• 위치: services/pipeline/scheduler/multi_thread_scheduler.py

1.2 Keyword Manager API (keyword-manager)

• 역할: 키워드 CRUD 및 스레드 모니터링
• 포트: 8100
• 주요 엔드포인트:
  • GET /threads/status - 모든 스레드 상태 조회
  • GET /keywords - 모든 키워드 목록
  • POST /keywords - 새 키워드 추가
  • PUT /keywords/{keyword} - 키워드 수정
  • DELETE /keywords/{keyword} - 키워드 삭제
  • POST /keywords/{keyword}/activate - 키워드 활성화
  • POST /keywords/{keyword}/deactivate - 키워드 비활성화
  • POST /keywords/{keyword}/trigger - 즉시 실행
• 위치: services/pipeline/scheduler/keyword_manager.py

2. 데이터 모델

class Keyword:
    keyword_id: str           # UUID
    keyword: str              # 검색 키워드
    interval_minutes: int     # 실행 주기 (분)
    is_active: bool          # 활성 상태
    priority: int            # 우선순위 (높을수록 우선)
    rss_feeds: List[str]     # RSS 피드 URL 목록
    max_articles_per_run: int # 실행당 최대 기사 수
    last_run: datetime       # 마지막 실행 시간
    next_run: datetime       # 다음 실행 예정 시간

사용 방법

1. 서비스 시작

# 스케줄러와 매니저 시작
docker-compose up -d pipeline-scheduler keyword-manager

# 로그 확인
docker-compose logs -f pipeline-scheduler

2. 키워드 관리

2.1 키워드 추가

curl -X POST http://localhost:8100/keywords \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "딥러닝",
    "interval_minutes": 60,
    "priority": 1,
    "rss_feeds": [],
    "max_articles_per_run": 100,
    "is_active": true
  }'

2.2 키워드 수정

curl -X PUT http://localhost:8100/keywords/딥러닝 \
  -H "Content-Type: application/json" \
  -d '{
    "interval_minutes": 30,
    "priority": 2
  }'

2.3 키워드 활성화/비활성화

# 활성화
curl -X POST http://localhost:8100/keywords/딥러닝/activate

# 비활성화
curl -X POST http://localhost:8100/keywords/딥러닝/deactivate

2.4 즉시 실행

curl -X POST http://localhost:8100/keywords/딥러닝/trigger

2.5 키워드 삭제

curl -X DELETE http://localhost:8100/keywords/딥러닝

3. 모니터링

3.1 스레드 상태 확인

curl http://localhost:8100/threads/status | python3 -m json.tool

응답 예시:

{
  "total_threads": 4,
  "active_threads": 4,
  "threads": [
    {
      "keyword": "블록체인",
      "keyword_id": "5c7ac9a9-c56f-4878-94ec-adb13f105c8a",
      "is_active": true,
      "interval_minutes": 30,
      "priority": 2,
      "last_run": "2025-09-15T08:05:58.807000",
      "next_run": "2025-09-15T08:35:58.807000",
      "thread_status": "active",
      "minutes_until_next_run": 25.3
    }
  ]
}

3.2 키워드 목록 조회

curl http://localhost:8100/keywords | python3 -m json.tool

작동 방식

1. 실행 흐름

1. 키워드 스레드 시작

   • 스케줄러 시작 시 활성 키워드 로드
   • 각 키워드별 독립 스레드 생성

2. 주기적 실행

   • 각 스레드는 설정된 주기마다 실행
   • 실행 시 PipelineJob 생성 후 Redis 큐에 추가
   • RSS 수집 → Google 검색 → AI 기사 생성 → 번역 파이프라인 자동 진행

3. 동적 스레드 관리

   • 30초마다 새 키워드 확인
   • 새 키워드 추가 시 자동으로 스레드 생성
   • 비활성화/삭제 시 스레드 자동 중지

2. 우선순위 처리

• 높은 우선순위(priority) 키워드가 먼저 처리
• Redis 큐에서 우선순위별 정렬

3. 오류 처리

• 각 스레드는 독립적으로 오류 처리
• 오류 발생 시 1분 대기 후 재시도
• 스레드별 error_count, last_error 추적

현재 설정된 키워드

키워드	실행 주기	우선순위	상태
블록체인	30분	2	활성
AI	60분	1	활성
테크놀로지	60분	1	활성
경제	60분	0	활성

주의사항

1. 스레드 관리

   • 키워드 추가/삭제는 30초 이내 자동 반영
   • 스레드 상태는 keyword-manager API로 실시간 확인 가능

2. 실행 주기

   • 최소 실행 주기: 제한 없음 (권장: 30분 이상)
   • interval_minutes 변경 시 다음 실행 시간 자동 재계산

3. 중복 방지

   • 동일 키워드 중복 등록 불가
   • RSS 수집 시 중복 URL 자동 필터링

트러블슈팅

스레드가 시작되지 않을 때

# 스케줄러 재시작
docker-compose restart pipeline-scheduler

# 로그 확인
docker-compose logs --tail=50 pipeline-scheduler

키워드가 실행되지 않을 때

# 키워드 상태 확인
curl http://localhost:8100/keywords/키워드명 | python3 -m json.tool

# 즉시 실행 트리거
curl -X POST http://localhost:8100/keywords/키워드명/trigger

MongoDB 연결 오류

# MongoDB 상태 확인
docker-compose ps mongodb

# MongoDB 재시작
docker-compose restart mongodb

파일 구조

services/pipeline/scheduler/
├── multi_thread_scheduler.py  # 멀티스레드 스케줄러
├── keyword_manager.py         # 키워드 관리 API
├── single_keyword_scheduler.py # (deprecated) 단일 키워드 스케줄러
├── requirements.txt           # Python 의존성
└── Dockerfile                # Docker 이미지 정의

services/pipeline/shared/
└── models.py                 # Keyword, PipelineJob 모델 정의

향후 개선사항

1. 웹 대시보드: 실시간 모니터링 UI
2. 알림 시스템: 오류 발생 시 이메일/Slack 알림
3. 통계 기능: 키워드별 수집 통계 및 분석
4. 스케줄 템플릿: 자주 사용하는 설정 저장/불러오기
5. 백업/복구: 키워드 설정 백업 및 복구 기능