293 lines
7.0 KiB
Markdown
293 lines
7.0 KiB
Markdown
# 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 아키텍처의 일부로, 다른 서비스에서 발행한 이미지 업로드 이벤트를 구독하여 자동으로 파생본을 생성합니다.
|