diff --git a/README.md b/README.md new file mode 100644 index 0000000..82edfa0 --- /dev/null +++ b/README.md @@ -0,0 +1,274 @@ +# 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 +``` + +### 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 아키텍처의 일부로, 다른 서비스에서 발행한 이미지 업로드 이벤트를 구독하여 자동으로 파생본을 생성합니다.