2025-11-08 10:58:19 +00:00
2025-11-08 18:27:51 +09: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:27:51 +09:00
2025-11-08 18:27:51 +09:00
2025-11-08 18:35:32 +09:00
2025-11-08 10:58:19 +00: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. Powershell: 이 프로젝트는 파워쉘 스크립트로 실행됩니다.

  1. 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%