c8be78de15e89fad3fb6a5ef07f753857f2ca401
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.
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
📋 사전 요구사항
시스템 요구사항
-
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 -
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
환경 변수 로드 우선순위
환경 변수는 다음 순서로 로드되며, 먼저 로드된 값이 우선합니다:
-
LocalMachine 전역 환경 변수
- Linux/MacOS:
~/source/global-env-vars.txt - Windows:
%USERPROFILE%\source\global-env-vars.txt - 모든 프로젝트에서 공통으로 사용하는 전역 설정
- Linux/MacOS:
-
프로젝트별 환경 변수 파일 (
./env-vars/{NODE_ENV}.env)- 프로젝트 특화 설정 (dev.env, test.env, prod.env)
- LocalMachine 변수의 재지정
-
쉘 환경 변수
- 현재 쉘 세션의 환경 변수
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
핵심 비즈니스 로직:
- NATS에서
s3ObjectKey메시지 수신 - MinIO에서 원본 이미지 다운로드
- 6개 해상도 × 3개 포맷 = 18개 파생본 생성
- 각 파생본을 MinIO에 업로드
- 진행 상황 로깅
📨 메시지 포맷
입력 메시지 (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 아키텍처의 일부로, 다른 서비스에서 발행한 이미지 업로드 이벤트를 구독하여 자동으로 파생본을 생성합니다.
Languages
TypeScript
81.6%
PowerShell
14.4%
Dockerfile
4%