# 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로 임베딩하여 관리됨) ```bash # 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 연동을 위한 환경 변수가 필요합니다: ```bash 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 연결용). ## 🚀 설치 및 실행 ### 개발 환경 ```bash # 의존성 설치 npm install # TypeScript 빌드 npm run build # 개발 모드로 실행 npm run start:dev ``` ### 프로덕션 환경 ```bash # 테스트 환경 npm run start:test # 프로덕션 환경 npm run start:prod ``` ## 🐳 Docker ### Docker 이미지 빌드 ```bash docker build -t image-derivatives-generation-service . ``` ### Docker 실행 ```bash 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`) ```json { "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`: ```typescript private readonly resolutions = [320, 640, 960, 1280, 1600, 1920]; ``` ### 포맷 커스터마이징 `src/image-derivatives-generator.ts`: ```typescript private readonly formats: ImageFormat[] = ['avif', 'webp', 'jpeg']; ``` ### FFmpeg 품질 설정 `src/ffmpeg.ts`: ```typescript // 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 아키텍처의 일부로, 다른 서비스에서 발행한 이미지 업로드 이벤트를 구독하여 자동으로 파생본을 생성합니다.