Feature #1575
closedFeature #1576: 잡코리아 채용공고 크롤링 시스템 구축 및 스테이징 운영 검증
[T64] 크롤러 스케줄러·실행 관리·장애 복구
100%
Description
선행 일감 T62, T63, T28
관련 기능 F-024
1. 작업 목표¶
AI Career Platform의 채용공고 크롤러를 매일 새벽 자동 실행하고, 관리자가 웹 대시보드를 통해 실행 주기, 진행 상태, 오류 로그 및 실패 재처리를 관리할 수 있는 운영 시스템을 구축한다.
기본 아키텍처
- Ubuntu
systemd timer: 주기적 실행 대상 확인 - Python Dispatcher: 실행 대상 선정 및 중복 실행 방지
- 독립 Python Batch Worker: T62 크롤러 실행
- PostgreSQL: 스케줄 설정·실행 이력·진행률·오류 기록
- FastAPI 관리자 API: 스케줄 변경·수동 실행·로그 조회·재처리
- React 관리자 대시보드: 별도 관리자 UI 일감과 연계
크롤러는 FastAPI 서버 내부에서 직접 실행하지 않으며, 별도 Batch 프로세스로 실행한다.
24시간 상주하는 크롤러 데몬이나 Celery·Redis는 초기 개발 범위에 포함하지 않는다.
2. 주요 작업 내용¶
① Ubuntu systemd timer 기반 Scheduler 구성
systemd timer및service실행 설정 초안 작성- 예: 5분마다 Dispatcher 실행 대상 확인
- 실제 크롤러 기본 실행 시각: 매일 03:00 KST(초기 제안)
- PostgreSQL에 저장된 스케줄을 기준으로 실제 실행 여부 결정
- 관리자 화면에서 주기를 변경해도 서버 설정 파일을 직접 수정하지 않는 구조
- 자동 실행 활성화·비활성화 기능
- 서버 중단·재시작 시 누락 실행 정책 정의
- 스케줄러 운영 활성화는 별도 PM 승인 후 진행
② Python Dispatcher 및 Batch Worker 실행 관리
- T62의 독립 Python Batch Worker 호출
- 실행 요청별 고유
run_id생성 - 출처별 실행 가능 여부 및 승인 상태 확인
- 중복 실행 방지(DB Lock 또는 동등한 방식)
- 수동 실행과 예약 실행의 충돌 처리
- Batch 실행 상태 및 종료 코드 관리
- Worker 비정상 종료 및 Timeout 감지
- Heartbeat 및 비정상 실행 상태 정리
③ PostgreSQL 스케줄·실행 이력 관리
다음 정보를 저장하고 조회할 수 있도록 논리 데이터 계약을 정의한다.
스케줄 설정:
- 출처 ID 및 활성화 상태
- 실행 주기·시각·타임존
- 다음 실행 예정 시각
- 마지막 실행 시각
- 설정 변경자 및 변경 이력
실행 이력:
run_id,source_id- 실행 유형: 예약 / 수동 / 재시도
- 실행 상태: PENDING / RUNNING / SUCCEEDED / PARTIAL / FAILED / CANCELLED
- 시작·종료 시각 및 실행 시간
- 수집·신규 등록·수정·중복·오류 건수
- 실패 원인 및 재처리 횟수
기존 data_sources, ingestion_runs, audit_events 테이블을 우선 검토하고, 신규 테이블이 필요한 경우 별도 DB 계약 및 Migration 승인을 받는다.
④ FastAPI 관리자 API 구현 및 계약 정의
관리자 인증·권한 검사가 적용되는 API를 설계한다.
주요 기능:
- 크롤러 스케줄 조회 및 변경
- 출처별 수집 활성화·비활성화
- 수동 실행 요청
- 실행 목록 및 상세 조회
- 진행 상태 및 오류 로그 조회
- 실패 작업 재처리 요청
관리자 API는 실행 요청을 등록하고 빠르게 응답하며, 크롤링 처리는 별도 Worker가 수행한다.
비관리자 사용자의 실행·설정 변경·재처리 요청은 차단한다.
실제 API 경로 및 권한 정책은 T06 API 계약과 관리자 기능 담당자 협의 후 확정한다.
⑤ 관리자 대시보드 연동 요구사항
React 관리자 화면에서 다음 기능을 제공할 수 있도록 API 및 데이터 계약을 준비한다.
- 출처별 자동 수집 ON/OFF
- 일별 실행 주기 및 시각 변경
- 수동 실행 요청
- 현재 진행 단계 및 처리 건수 표시
- 최근 실행 내역 조회
- 실패 원인 및 오류 로그 조회
- 실패 작업 재처리
- 마지막 성공 시각 및 다음 실행 예정 시각 표시
관리자 UI 자체의 구현은 기존 Frontend 관리자 일감과 연계하여 중복 개발하지 않는다.
⑥ 오류 처리 및 장애 복구
- HTTP 429, Timeout, 외부 사이트 장애 처리
- 제한된 재시도 및 백오프 정책
- 일부 출처 실패 시 다른 출처의 독립 실행 보장
- Batch 실행 중단 후 재시작 시 복구
- 장시간 RUNNING 상태의 비정상 작업 탐지
- 재처리 시 T63 중복 방지 정책 적용
- 동일 데이터 재실행 시 신규 중복 0건 보장
- 오류 발생 시 관리자가 출처별 수집을 중단할 수 있도록 구성
외부 사이트 구조 변경으로 Adapter 수정이 필요한 경우 T62 코드를 수정하고 pytest·CI 검증 및 PR 승인 후 배포한다.
관리자 화면에서 Python 소스코드를 직접 수정하거나 임의 실행하는 기능은 제공하지 않는다.
⑦ 테스트 자동화 및 검증
pytest 및 격리된 로컬 실행 환경에서 다음을 검증한다.
- 예약 시각에 따른 정상 실행
- 관리자가 실행 시각을 변경한 경우 스케줄 반영
- 비활성화된 출처 실행 차단
- 관리자 수동 실행 요청
- 예약 실행과 수동 실행 동시 요청 시 중복 실행 방지
- Worker Timeout 및 강제 종료 후 복구
- 실패 건 재시도 및 재처리 횟수 제한
- 동일 데이터 재처리 시 중복 0건
- 비관리자 API 접근 차단(401/403)
- 실행 상태·진행률·오류 로그 및 처리 건수 정합성 검증
실제 외부 수집 없이 Mock Adapter 및 합성 Fixture로 먼저 검증한다.
3. 주요 산출물¶
systemd timer/service설정 초안- Python Dispatcher 및 Batch 실행 관리 모듈
- 스케줄·실행 이력 논리 데이터 계약
- FastAPI 관리자 API 및 OpenAPI 계약
- 실행 상태·진행률·로그 조회 기능
- 실패 재처리 및 장애 복구 로직
- pytest 자동 테스트 및 Fixture
- 테스트 실행 로그와 JUnit XML
- 운영 Runbook 및 장애 복구 절차서
- 관리자 대시보드 연동 명세
- GitHub PR 및 CI 검증 결과
4. 완료 조건 (Definition of Done)¶
- 독립 Batch Worker가 스케줄러를 통해 정상 실행됨
- 관리자 설정 변경이 실제 스케줄에 반영됨
- 수동 실행 요청 기능 정상 동작
- 수동·예약 중복 실행 방지 PASS
- 출처별 실행 상태 및 처리 건수 조회 PASS
- 실패 원인과 구조화 로그 조회 PASS
- Timeout·비정상 종료·재시도 복구 PASS
- 동일 데이터 재처리 시 신규 중복 0건
- 비관리자 실행 및 설정 변경 차단 PASS
- pytest·격리 테스트 실행 결과 및 증빙 제출
- 운영 Runbook과 관리자 UI 연동 계약 작성
- GitHub PR 리뷰 및 병합 완료
실제 Staging 운영 활성화는 별도 PM 승인 이후 진행한다.
5. 선행조건 및 주의사항¶
- 선행 일감: T62, T63, T28
- T61 승인된 출처 정책 준수
- T09 DB Migration 계약 및 운영 반영 승인 확인
- T06 API 계약 및 관리자 인증·인가 정책 확인
- 공유 Staging DB의 무단 DDL/DML/Seed 변경 금지
- 승인 없는 외부 사이트 수집 금지
- 운영 systemd timer 자동 실행은 별도 승인 필요
- 관리자 계정 비밀번호·API Key·개인정보를 로그에 기록하지 않음
- 기존 데이터 및 운영 배포 설정에 영향을 주지 않도록 격리 환경에서 검증
6. GitHub 작업지시서¶
7. 결과 보고 기준¶
- TASK=T64
- STATUS=NOT_STARTED / IN_PROGRESS / PASS / PARTIAL / HOLD
- BRANCH=
- PR_URL=
- CI_RUN_URL=
- TEST_EVIDENCE=
- SCHEDULER_TEST=
- WORKER_TEST=
- ADMIN_API_TEST=
- RETRY_TEST=
- BLOCKER=
Subtasks
Related issues