본문으로 건너뛰기

영상 파이프라인

스포클립 서버의 핵심 인프라 - 체육관 영상이 사용자에게 도달하기까지의 전체 흐름

문서 정보​

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

이 문서의 위치​

스포클립 서버의 모든 기능은 이 영상 파이프라인 위에서 동작합니다.

영상 파이프라인 (이 문서)
    ↓
예약 & 영상 → 일정 → 콕 → 마이콕 → 활동 보상 → ...

영상이 올라오지 않으면 예약, 시청, 콕, 보상 등 어떤 기능도 작동하지 않습니다. 이 문서는 그 근간이 되는 파이프라인을 설명합니다.

전체 파이프라인 개요​

파이프라인 4단계​

단계설명상세 문서
1. 업로드체육관 로컬 PC가 카메라 영상을 10분 단위로 R2에 업로드UPLOAD-FLOW.md
2. Webhook 처리R2/Stream 이벤트를 서버가 수신하여 Video 엔티티 생성WEBHOOK-FLOW.md
3. 녹화 예약사용자의 WebSocket 예약과 영상 매칭RECORDING-FLOW.md
4. 배치 클립만료 영상을 GPU VM에서 클립으로 변환 (MyKok)BATCH-FLOW.md

핵심 아키텍처 특성​

체육관별 Cloudflare 계정​

각 체육관은 독립된 Cloudflare 계정을 보유합니다. R2 버킷, Stream, CF Worker가 모두 체육관 단위로 분리되어 있습니다.

[체육관 A CF 계정]  R2 + Stream + Worker → webhook → Spoclip Server
[체육관 B CF 계정]  R2 + Stream + Worker → webhook → Spoclip Server
[체육관 C CF 계정]  R2 + Stream + Worker → webhook → Spoclip Server

체육관별 크레덴셜(CF Account ID, R2 API Key/Secret, Webhook Secret)은 서버 환경변수가 아닌 gym_media_configs 테이블에 암호화되어 저장됩니다.

gym_media_configs:
  - gymId, provider: 'CLOUDFLARE'
  - accessKey: CF API Token (암호화)
  - secretKey: CF Account ID (암호화)
  - providerConfig: { r2: { apiKey, apiSecret }, webhookSecret } (암호화)

Webhook 기반 비동기 처리​

체육관 PC는 서버와 직접 통신하지 않습니다. R2 업로드 완료 시 CF Worker가 webhook을 전송하고, 서버는 이를 비동기로 처리합니다.

체육관 PC → R2 (직접 업로드, 서버 미경유)
                ↓
         CF Worker (R2 Event Notification)
                ↓
         Spoclip Server (webhook 수신)

Passthrough 메타데이터​

모든 영상에는 출처를 식별하는 메타데이터가 포함됩니다.

필드설명예시
gymCode체육관 식별자GYM-001
courtCode코트 식별자COURT-A
cameraCode카메라 식별자CAM-FRONT
date촬영 날짜2026-03-01
hour시간 (0-23)14
timeSlot10분 구간 (0-5)3 (14:30~14:40)

분산 락과 캐싱​

동일 시간대에 여러 카메라가 동시에 영상을 업로드하므로, Redis 분산 락으로 데이터 일관성을 보장합니다. Context 조회 결과는 10분간 캐싱하여 DB 부하를 줄입니다.

영상의 생명주기​

상태Video.metadata 내 상태설명
업로드R2 uploadStatus = UPLOADEDR2에 원본 저장 완료
스트리밍 준비Stream uploadStatus = READYHLS 트랜스코딩 완료, 재생 가능
시청 가능totalPlayableCount > 0사용자가 앱에서 시청 가능
만료expiresAt < nowMyKok 배치 대상
클립 생성MyKok.videoState = CLIPPEDGPU VM에서 클립 추출 완료

관련 시스템​

시스템역할
Cloudflare R2원본 영상 저장소 (체육관별 계정)
Cloudflare StreamHLS 트랜스코딩 (체육관별 계정)
Cloudflare WorkerR2 Event → Spoclip Server webhook 전달
Redis분산 락, Context 캐싱
PostgreSQLVideo, Recording, gym_media_configs 엔티티
VultrMyKok 배치용 GPU VM 프로비저닝
MongoDB배치 작업 상태 (vm_assignments)

관련 문서​

변경 이력​

버전날짜변경 내용
v1.0.02026-03-02초기 문서 작성
- 전체 파이프라인 개요
- 4단계 파이프라인 구조 정의
- 핵심 아키텍처 특성 (체육관별 CF 계정, Webhook 비동기, Passthrough, 분산 락)
- 영상 생명주기 상태 다이어그램