LivePack V4 설계 문서

개요

기존 LivePack(Java, MediaLive/WeLive)을 대체하는 V4 라이브 스트리밍 플랫폼. WeLive 방식(RTMP 상시 활성, 신호 감지 즉시 방송)을 Node.js로 구현한다.

프로바이더

IVS와 Cloudflare 두 가지를 선택 가능하게 지원한다.

프로바이더 비교

비용 비교 (FHD 1080p, 월 기준)

운영 전략

기술 스택

아키텍처

시스템 구성

[IVS 채널]
  AWS IVS
    └── EventBridge ──→ Lambda (상태 변경 + 녹화 완료) ──→ RDS
    └── 녹화 → S3 자동 저장 (HLS + 썸네일)

[Cloudflare 채널]
  Cloudflare Stream
    ├── Webhook (녹화 완료) ──→ Worker ──→ Lambda (VOD 등록)
    └── Status API ←── Worker (Cron 1분) ──→ Lambda (상태 업데이트) ──→ RDS

[공통]
  LivePack API (Lambda, VPC)
    ├── 채널 CRUD (Provider 추상화 → IVS SDK / CF REST API)
    ├── 상태 업데이트 (EventBridge 또는 Worker에서 호출)
    ├── 녹화/VOD 관리
    └── wecandeo-db → RDS

  CMS (콘솔)
    └── LivePack API 호출 → DB 조회 → 방송 상태 표시

  Admin (Java)
    └── LivePack API 호출 → 채널 관리

전체 플로우

1. 채널 생성

CMS → LivePack API → Provider별 채널 생성
  [IVS]        → aws ivs create-channel → RTMP URL/Key/playbackUrl 발급
  [Cloudflare] → POST /live_inputs → RTMP URL/Key 발급
                → DB 저장 (status: IDLE)
                → CMS에 RTMP URL/Key 반환

2. 방송 시작 (인코더가 RTMP 송출)

인코더 → RTMP 송출
  [IVS]        → EventBridge "Stream Start" → Lambda → DB (IDLE → LIVE) [실시간]
  [Cloudflare] → Worker Cron → connected 감지 → Lambda → DB (IDLE → LIVE) [최대 1분 지연]
                → CMS → DB 조회 → LIVE 표시

3. 방송 시청

시청자 → HLS URL → 영상 재생
  [IVS]        → CloudFront 경유
  [Cloudflare] → Cloudflare CDN (내장)

4. 방송 종료 (인코더 송출 중단)

인코더 송출 중단
  [IVS]        → EventBridge "Stream End" → Lambda → DB (LIVE → IDLE) [실시간]
                  재연결 유예: recordingReconnectWindowSeconds (300초)
  [Cloudflare] → Worker Cron → disconnected 감지 → Lambda → DB (LIVE → IDLE) [최대 1분 지연]
                  재연결 유예: timeoutSeconds (300초)
                  유예 내 재연결 → 같은 녹화 유지 / 초과 → 새 녹화 생성

5. 녹화 완료 (VOD 등록)

  [IVS]        → S3에 자동 저장 (HLS + 썸네일)
               → EventBridge "Recording State Change" → Lambda → DB에 VOD 등록
               → S3 경로: ivs/v1/{account}/{channel}/{날짜}/{recording_id}/media/hls/master.m3u8
  [Cloudflare] → 녹화 처리 완료 (state: ready)
               → Webhook → Worker → Lambda → DB에 VOD 등록
               → playback URL 자동 제공

Provider 추상화

                    ┌──────────────────┐
                    │  LivePack V4 API │
                    └────────┬─────────┘
                             │
                    ┌────────┴─────────┐
                    │  ProviderService  │
                    │  (공통 인터페이스) │
                    └────────┬─────────┘
                   ┌─────────┴──────────┐
                   │                    │
          ┌────────┴────────┐  ┌────────┴──────────┐
          │  IvsProvider    │  │ CloudflareProvider │
          │  (@aws-sdk)     │  │  (REST API)        │
          └─────────────────┘  └────────────────────┘

공통 인터페이스

class LiveProvider {
  async createChannel(params)     // → { channelId, rtmpUrl, streamKey }
  async deleteChannel(channelId)
  async getChannel(channelId)     // → { status, viewers, ... }
  async getPlaybackUrl(channelId) // → HLS URL
  async startRecording(channelId)
  async stopRecording(channelId)
}

프로젝트 구조

livepack-v4/
├── package.json
├── src/
│   ├── app.js
│   ├── config/
│   │   └── index.js              # 환경 설정 (local/test/real)
│   ├── providers/
│   │   ├── LiveProvider.js       # 공통 인터페이스 (base class)
│   │   ├── IvsProvider.js        # AWS IVS 구현
│   │   ├── CloudflareProvider.js # Cloudflare Stream 구현
│   │   └── ProviderFactory.js    # providerType → 인스턴스
│   ├── routes/
│   │   ├── channel.js            # 채널 CRUD
│   │   ├── broadcast.js          # 방송 상태 업데이트 (Worker에서 호출)
│   │   └── recording.js          # 녹화/VOD 관리 (Webhook에서 호출)
│   ├── services/
│   │   ├── ChannelService.js     # 채널 비즈니스 로직
│   │   ├── BroadcastService.js   # 방송 상태 관리
│   │   └── RecordingService.js   # 녹화/VOD 전환
│   └── database/
│       └── wecandeo-db/          # git submodule
├── test/
└── deploy/

방송 상태 관리

핵심 플로우

1. 채널 생성 → RTMP URL + Stream Key 발급 (상시 활성) → DB 저장
2. 방송 시작 → 인코더가 RTMP 송출 → 이벤트 수신 → DB LIVE
3. 방송 종료 → 신호 끊김 → 이벤트 수신 → DB IDLE

상태 머신

IDLE → LIVE → IDLE   (끊김 — 재연결 유예는 Cloudflare timeoutSeconds가 처리)
     ← LIVE          (재송출 시 다시 LIVE)

프로바이더별 이벤트 처리

IVS: EventBridge (실시간)

EventBridge로 모든 상태 변경을 실시간으로 수신한다. Polling 불필요.

EventBridge 이벤트:
  "Session Created"        → RTMP 연결
  "Stream Start"           → 방송 시작 → DB: IDLE → LIVE
  "Session Ended"          → RTMP 연결 종료
  "Stream End"             → 방송 종료 확정 → DB: LIVE → IDLE
  "Recording State Change" → 녹화 시작/완료 → DB: VOD 등록

IVS EventBridge 룰:

{ "source": ["aws.ivs"], "detail-type": ["IVS Stream State Change"] }
{ "source": ["aws.ivs"], "detail-type": ["IVS Recording State Change"] }

Cloudflare: Webhook + Polling

Webhook은 녹화 완료(ready)만 제공. 방송 상태는 Worker Cron Polling으로 감지.

Webhook 페이로드 (녹화 완료):
  uid: "녹화 ID"
  liveInput: "Live Input ID (채널 식별)"
  status: { state: "ready" }
  duration: 14
  playback: { hls: "HLS URL", dash: "DASH URL" }

Worker Cron (1분 주기):
  → Stream API로 전체 채널 상태 조회
  → connected 감지 → Lambda → DB: IDLE → LIVE
  → disconnected 감지 → Lambda → DB: LIVE → IDLE

• DB에 등록된 모든 채널을 Polling (LIVE→IDLE 전환 감지를 위해)
• 비용: 채널 100개 기준 144,000 요청/일 (Worker 유료 $5/월이면 충분)

재연결 유예 (Grace Period)

프로바이더 레벨에서 처리한다. 자체 RECONNECTING 상태 관리 불필요 (PoC 검증 완료).

DB 스키마

채널 테이블

CREATE TABLE live_channel_v4 (
  id              BIGINT AUTO_INCREMENT PRIMARY KEY,
  gid             INT NOT NULL,
  channel_name    VARCHAR(100),
  provider_type   ENUM('IVS', 'CLOUDFLARE') NOT NULL,
  provider_id     VARCHAR(200),
  rtmp_url        VARCHAR(500),
  stream_key      VARCHAR(200),
  playback_url    VARCHAR(500),
  status          ENUM('IDLE', 'LIVE', 'ERROR') DEFAULT 'IDLE',
  quality         ENUM('SD', 'HD', 'FHD') DEFAULT 'FHD',
  recording       TINYINT(1) DEFAULT 0,
  created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at      DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

녹화 테이블

끊김 시 녹화 파일이 분리되므로 broadcast_id로 묶어 하나의 방송으로 관리한다.

CREATE TABLE live_recording_v4 (
  id              BIGINT AUTO_INCREMENT PRIMARY KEY,
  broadcast_id    BIGINT NOT NULL,
  channel_id      BIGINT NOT NULL,
  segment_index   INT DEFAULT 0,
  provider_ref    VARCHAR(500),
  duration_sec    INT,
  created_at      DATETIME DEFAULT CURRENT_TIMESTAMP
);

제약 사항

• Cloudflare Stream 재생 도메인: 커스텀 도메인 CNAME 연결 필요 (예: live.wecandeo.com → customer-yifnzknsk7yuqbxw.cloudflarestream.com)
• IVS는 기본 RTMPS만 지원, RTMP 허용 시 insecureIngest: true 설정 필요 (기존 MediaLive 고객 인코더 호환)
• IVS, Cloudflare 모두 1채널 = 1 RTMP 입력 (이중 입력 미지원)
• Primary/Backup 이중화 필요 시 자체 RTMP Relay 서버(MediaMTX, Nginx-RTMP) 구축 필요
• 현재는 이중화 없이 단일 RTMP로 시작, 필요 시 릴레이 추가
• Cloudflare 녹화는 최대 7일 — 7일 초과 시 첫 7일만 저장, 장기 방송은 녹화 분할 관리 필요
• Cloudflare Stream Key 변경 불가 — 유출 시 Live Input 삭제 후 재생성으로 대응 (IVS는 Key 재발급 가능)
• IVS 녹화 재연결 병합: 최대 20회, 48시간 제한
• IVS 녹화 VOD 재생: S3 private → CloudFront OAC 설정 필요

기술 검증 결과 (PoC)