본문으로 건너뛰기

배치 클립 생성

만료된 영상을 GPU VM에서 사용자별 클립으로 변환하는 MyKok 배치 파이프라인

문서 정보​

  • 작성일: 2026-03-02
  • 최종 업데이트: 2026-03-02
  • 버전: v1.0.0
  • 관련 코드: src/schedulers/my-kok-pipeline/, src/modules/my-kok-pipeline/

개요​

PLUS 회원이 생성한 콕(Kok)은 영상 만료 후 **영구 클립(MyKok)**으로 변환됩니다. 이 변환은 매일 새벽 3:30(KST)에 실행되는 배치 파이프라인에 의해 자동으로 처리됩니다.

만료된 영상 → 배치 수집 → Vultr GPU VM 프로비저닝 → FFmpeg 클립 추출 → R2 업로드 → 원본 삭제

파이프라인 흐름​

파이프라인 단계 상세​

1. 만료 영상 수집​

조건설명
Video.expiresAt < now만료된 영상
MyKok.videoState = ORIGINAL아직 클립이 생성되지 않은 MyKok
gym_media_configs.status = ACTIVE활성 CLOUDFLARE provider

관련 코드: src/schedulers/my-kok-pipeline/strategies/my-kok-generation.strategy.ts

2. 배치 컨텍스트 구성​

체육관별로 그룹핑하고, 각 체육관의 R2 크레덴셜을 gym_media_configs에서 복호화합니다.

정보출처
accountIdgym_media_configs.secretKey (복호화)
r2ApiKeygym_media_configs.providerConfig.r2.apiKey (복호화)
r2ApiSecretgym_media_configs.providerConfig.r2.apiSecret (복호화)

3. 매니페스트 생성​

각 MyKok에 대해 클립 추출 명세를 생성합니다.

항목형식
클립 출력 경로{userUuid}/{myKokUuid}/{cameraCode}.mp4
썸네일 출력 경로{userUuid}/{myKokUuid}/{defaultCameraCode}.webp
클립 오프셋원본 영상 내 시작/종료 시간

관련 코드: src/schedulers/my-kok-pipeline/services/manifest-generator.service.ts

4. VM 할당​

영상을 50GB 단위 청크로 분할하여 VM에 배정합니다. 하나의 영상은 분할되지 않습니다 (원자적 단위).

관련 코드: src/schedulers/my-kok-pipeline/services/vm-allocator.service.ts

5. VM 프로비저닝​

설정값
리전nrt (일본)
플랜vx1-g-2c-8g-120s (GPU)
초기화cloud-init: Docker 설치 + GHCR에서 Worker 이미지 pull

관련 코드: src/modules/my-kok-pipeline/application/services/vm-provisioner.service.ts

VM Worker 생명주기​

Worker 동작​

  1. 부팅: cloud-init으로 Docker 설치, Worker 이미지 pull
  2. 작업 수신: GET /batch-clip-generation/:vmUuid 호출 (PENDING → RUNNING 전환)
  3. 클립 생성: R2에서 원본 다운로드 → FFmpeg → R2 my-koks 버킷 업로드
  4. 파일 완료: 업로드 시 CF Worker가 POST /batch-logs/file-uploaded 호출
  5. 전체 완료: 모든 파일 완료 시 POST /batch-logs/upload-completed 호출
  6. 정리: VM 삭제 (fire-and-forget), 원본 삭제 (5분 지연), Discord 리포트

완료 처리​

completedCount >= totalMyKoks
    → MongoDB: vm_assignment.status = COMPLETED
    → PostgreSQL: MyKok.videoState = CLIPPED, mediaInfo 설정
    → Vultr API: VM 삭제
    → BullMQ: 배치 정리 작업 예약 (5분 후)
    → Discord: 배치 완료 리포트

관련 코드:

  • src/modules/my-kok-pipeline/application/commands/handle-file-uploaded.command.ts
  • src/modules/my-kok-pipeline/application/commands/handle-upload-completed.command.ts

환경변수​

변수설명
VULTR_API_KEYVultr VM 프로비저닝 API
GITHUB_USERNAME / GITHUB_TOKENGHCR 이미지 pull 인증
MYKOK_WORKER_IMAGEDocker Worker 이미지
BATCH_API_SECRET배치 이벤트 엔드포인트 인증
MY_KOK_OUTPUT_BUCKET클립 출력 R2 버킷 (예: my-koks)
MY_KOK_RETENTION_DAYS클립 보관 기간 (기본 14일)

변경 이력​

버전날짜변경 내용
v1.0.12026-04-15MY_KOK_RETENTION_DAYS 기본값 설명을 14일로 갱신
v1.0.02026-03-02초기 문서 작성
- 배치 파이프라인 전체 흐름
- VM 프로비저닝 및 Worker 생명주기
- 매니페스트 생성, VM 할당 상세
- 환경변수 목록