Project

General

Profile

Feature #1575

closed
길문 길문

Feature #1576: 잡코리아 채용공고 크롤링 시스템 구축 및 스테이징 운영 검증

[T64] 크롤러 스케줄러·실행 관리·장애 복구

Feature #1575: [T64] 크롤러 스케줄러·실행 관리·장애 복구

Added by 길래 문 11 days ago. Updated 9 days ago.

Status:
Closed
Priority:
High
Assignee:
Start date:
11/30/2026
Due date:
12/04/2026
% Done:

100%

Estimated time:

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 및 격리된 로컬 실행 환경에서 다음을 검증한다.

  1. 예약 시각에 따른 정상 실행
  2. 관리자가 실행 시각을 변경한 경우 스케줄 반영
  3. 비활성화된 출처 실행 차단
  4. 관리자 수동 실행 요청
  5. 예약 실행과 수동 실행 동시 요청 시 중복 실행 방지
  6. Worker Timeout 및 강제 종료 후 복구
  7. 실패 건 재시도 및 재처리 횟수 제한
  8. 동일 데이터 재처리 시 중복 0건
  9. 비관리자 API 접근 차단(401/403)
  10. 실행 상태·진행률·오류 로그 및 처리 건수 정합성 검증

실제 외부 수집 없이 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 작업지시서

https://github.com/ai-career-platform/ai-career-platform/blob/main/docs/work-orders/remaining-30/T64.md

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=

Add

Subtasks


Add

Related issues

길문 Updated by 길래 문 10 days ago Actions #1

  • Parent task set to #1576

길문 Updated by 길래 문 10 days ago Actions #2

  • % Done changed from 0 to 90

길문 Updated by 길래 문 9 days ago Actions #3

  • Status changed from New to Closed
  • % Done changed from 90 to 100

Also available in: PDF Atom