dahyeon c8be78de15 Updates FFmpeg handling for platform-aware execution
Switches to platform- and architecture-specific FFmpeg binaries and dynamically resolves executable paths to improve cross-platform compatibility.

Standardizes code style to use consistent double quotes.

Corrects naming inconsistencies and ensures executables have proper permissions on startup.

Enhances maintainability and reliability for image conversion across environments.
2025-11-15 00:00:59 -08:00
2025-11-08 18:27:51 +09:00
2025-11-08 18:27:51 +09:00
2025-11-08 19:32:23 +09:00
2025-11-08 18:27:51 +09:00
2025-11-08 18:35:32 +09:00
2025-11-08 19:43:06 +09:00
2025-11-08 18:27:51 +09:00

Image Derivatives Generation Service

이미지 파생본 자동 생성 마이크로서비스입니다. NATS 메시지 큐를 통해 이미지 변환 요청을 받아 FFmpeg로 다양한 해상도와 포맷의 이미지를 생성하고 MinIO에 저장합니다.

🎯 주요 기능

  • 메시지 기반 처리: NATS를 통해 generate-derivatives 토픽에서 이미지 변환 요청 수신
  • 다중 해상도 생성: 6가지 해상도 지원 (320px, 640px, 960px, 1280px, 1600px, 1920px)
  • 다중 포맷 지원: 3가지 이미지 포맷 (AVIF, WebP, JPEG)
  • 자동 중복 방지: 이미 생성된 파생본은 건너뛰기
  • S3 호환 스토리지: MinIO를 통한 이미지 저장 및 관리

🏗️ 아키텍처

NATS (generate-derivatives) 
    ↓
Image Derivatives Generator
    ↓
MinIO (download original)
    ↓
FFmpeg (convert)
    ↓
MinIO (upload derivatives)

생성되는 파일

원본 이미지: 2024-11-08/example.jpg

생성되는 파생본 (총 18개):

2024-11-08/320.avif
2024-11-08/320.webp
2024-11-08/320.jpeg
2024-11-08/640.avif
2024-11-08/640.webp
2024-11-08/640.jpeg
...
2024-11-08/1920.avif
2024-11-08/1920.webp
2024-11-08/1920.jpeg

🛠️ 기술 스택

  • Runtime: Node.js 24
  • Language: TypeScript 5.9
  • Message Queue: NATS 2.29
  • Storage: MinIO (S3 compatible)
  • Image Processing: FFmpeg
  • Secret Management: Infisical SDK

📋 사전 요구사항

시스템 요구사항

  1. FFmpeg 설치(Local Machine에 전역 설치가 필요한 경우)

    이 단계는 넘어갈 수 있습니다. (Git LFS로 임베딩하여 관리됨)

    # Windows (Chocolatey)
    choco install ffmpeg
    
    # Windows (Scoop)
    scoop install ffmpeg
    
    # Linux (Ubuntu/Debian)
    sudo apt-get install ffmpeg
    
    # macOS (Homebrew)
    brew install ffmpeg
    
  2. Node.js 24 이상

환경 변수

Infisical 연동을 위한 환경 변수가 필요합니다:

INFISICAL_CLIENT_SECRET=your_client_secret
INFISICAL_CLIENT_ID=your_client_id
INFISICAL_PROJECT_ID=your_project_id
NODE_ENV=dev|test|prod

환경 변수 로드 우선순위

환경 변수는 다음 순서로 로드되며, 먼저 로드된 값이 우선합니다:

  1. LocalMachine 전역 환경 변수

    • Linux/MacOS: ~/source/global-env-vars.txt
    • Windows: %USERPROFILE%\source\global-env-vars.txt
    • 모든 프로젝트에서 공통으로 사용하는 전역 설정
  2. 프로젝트별 환경 변수 파일 (./env-vars/{NODE_ENV}.env)

    • 프로젝트 특화 설정 (dev.env, test.env, prod.env)
    • LocalMachine 변수의 재지정
  3. 쉘 환경 변수

    • 현재 쉘 세션의 환경 변수

Note

: 동일한 키가 여러 곳에 정의되어 있을 경우, 우선순위가 높은 곳의 값이 사용됩니다.

Infisical Secrets

다음 시크릿이 Infisical에 설정되어 있어야 합니다:

  • MINIO_ENDPOINT: MinIO 서버 엔드포인트
  • MINIO_ACCESS_KEY: MinIO 액세스 키
  • MINIO_SECRET_KEY: MinIO 시크릿 키
  • NATS_ENDPOINT: NATS 서버 엔드포인트
  • NATS_USER: NATS 사용자명
  • NATS_PASS: NATS 비밀번호

인증서

프로젝트 루트에 internal-service-ca.pem 파일이 필요합니다 (NATS TLS 연결용).

🚀 설치 및 실행

개발 환경

# 의존성 설치
npm install

# TypeScript 빌드
npm run build

# 개발 모드로 실행
npm run start:dev

프로덕션 환경

# 테스트 환경
npm run start:test

# 프로덕션 환경
npm run start:prod

🐳 Docker

Docker 이미지 빌드

docker build -t image-derivatives-generation-service .

Docker 실행

docker run -d \
  -e INFISICAL_CLIENT_SECRET=your_secret \
  -e INFISICAL_CLIENT_ID=your_id \
  -e INFISICAL_PROJECT_ID=your_project_id \
  -e NODE_ENV=prod \
  --name image-derivatives-service \
  image-derivatives-generation-service

📁 프로젝트 구조

image-derivatives-generation-service/
├── src/
│   ├── main.ts                          # 애플리케이션 진입점
│   ├── secret-manager.ts                # Infisical 시크릿 관리
│   ├── nats.ts                          # NATS 클라이언트
│   ├── minio.ts                         # MinIO 클라이언트
│   ├── ffmpeg.ts                        # FFmpeg 이미지 변환
│   └── image-derivatives-generator.ts   # 메인 로직
├── dist/                                # 컴파일된 JavaScript
├── Dockerfile                           # Docker 이미지 정의
├── package.json                         # 의존성 관리
├── tsconfig.json                        # TypeScript 설정
└── internal-service-ca.pem              # NATS TLS 인증서

🔧 주요 모듈

1. secret-manager.ts

Infisical을 통해 시크릿을 안전하게 로드합니다.

2. nats.ts

  • NATS 서버 연결
  • TLS 인증
  • 메시지 구독/발행
  • Graceful shutdown

3. minio.ts

  • MinIO 클라이언트 초기화
  • 파일 다운로드/업로드
  • 파일 존재 여부 확인

4. ffmpeg.ts

  • FFmpeg를 통한 이미지 변환
  • 해상도 조정
  • 포맷 변환 (AVIF, WebP, JPEG)
  • 임시 파일 관리

5. image-derivatives-generator.ts

핵심 비즈니스 로직:

  1. NATS에서 s3ObjectKey 메시지 수신
  2. MinIO에서 원본 이미지 다운로드
  3. 6개 해상도 × 3개 포맷 = 18개 파생본 생성
  4. 각 파생본을 MinIO에 업로드
  5. 진행 상황 로깅

📨 메시지 포맷

입력 메시지 (NATS Topic: generate-derivatives)

{
  "s3ObjectKey": "2024-11-08/example.jpg"
}

🔍 로그 예시

🔐 Secrets loaded
✓ NATS connected
✓ Subscribed to generate-derivatives
🚀 Starting Image Derivatives Generator Service
📊 Resolutions: 320, 640, 960, 1280, 1600, 1920
🎨 Formats: avif, webp, jpeg
✅ Service ready

📥 Processing: 2024-11-08/example.jpg
  ✓ Downloaded original (1234.56 KB)
  ✓ Generated 320w avif (45.23 KB)
  ✓ Generated 320w webp (52.34 KB)
  ✓ Generated 320w jpeg (67.89 KB)
  ...

✅ Completed: 18 generated, 0 skipped for 2024-11-08/example.jpg

⚙️ 설정

해상도 커스터마이징

src/image-derivatives-generator.ts:

private readonly resolutions = [320, 640, 960, 1280, 1600, 1920];

포맷 커스터마이징

src/image-derivatives-generator.ts:

private readonly formats: ImageFormat[] = ['avif', 'webp', 'jpeg'];

FFmpeg 품질 설정

src/ffmpeg.ts:

// AVIF
args.push('-c:v', 'libaom-av1', '-crf', '30');

// WebP
args.push('-c:v', 'libwebp', '-quality', '80');

// JPEG
args.push('-q:v', '5');

🔒 보안

  • Infisical을 통한 중앙화된 시크릿 관리
  • TLS를 통한 NATS 연결 암호화
  • 환경별 시크릿 분리 (dev/staging/prod)

📝 라이선스

ISC

👤 Author

Dahyeon


Note: 이 서비스는 MSA 아키텍처의 일부로, 다른 서비스에서 발행한 이미지 업로드 이벤트를 구독하여 자동으로 파생본을 생성합니다.

S
Description
포맷 / 해상도별 이미지 파생본 생성 서비스
Readme
185 MiB
0 Stars 1 Watchers 0 Forks
Languages
TypeScript 81.6%
PowerShell 14.4%
Dockerfile 4%