다크 모드
아키텍처
truloop-media-service의 전체 아키텍처, Handler/Service/Worker 패턴, 미들웨어 체인을 설명합니다.
아키텍처 다이어그램
Handler / Service / Worker 패턴
Handler Layer
HTTP 요청을 수신하고 Service를 호출합니다.
| Handler | 역할 |
|---|---|
UploadHandler | JWT 인증된 사용자 업로드 처리 |
InternalUploadHandler | 서비스 간 업로드 (Internal API 인증) |
InternalIdempotencyHandler | Idempotency key flush (관리용) |
HealthHandler | S3/Redis/Worker 상태 확인 |
Service Layer
비즈니스 로직을 캡슐화합니다.
| Service | 역할 |
|---|---|
storage.Storage | S3 업로드 (단일/Multipart), 다운로드, 삭제 |
queue.Queue | SQS 메시지 발행 |
idempotency.Service | Redis 기반 중복 업로드 방지 (CheckAndReserve/SetResult) |
image.Processor | 이미지 리사이즈, WebP 변환, EXIF 추출 |
video.Processor | FFmpeg 기반 HEVC/H.264 인코딩, HDR 보존, 썸네일 추출 |
jobqueue.JobQueue | Redis 기반 작업 큐 (Push/Pop) |
Worker Layer
백그라운드에서 미디어 변환을 수행합니다.
| 컴포넌트 | 역할 |
|---|---|
DynamicPool | CPU 코어 기반 동적 Worker Pool 관리 (S3 업로드용) |
MediaWorker | Redis Job Queue 폴링, 이미지/비디오 변환 실행 |
요청 처리 흐름
설정 (환경변수)
Server 설정
| 환경변수 | 기본값 | 설명 |
|---|---|---|
SERVER_ADDR | :8080 | 서버 주소 |
SERVER_READ_TIMEOUT | 30m | 읽기 타임아웃 |
SERVER_WRITE_TIMEOUT | 30m | 쓰기 타임아웃 |
API_BASE_PATH | /media | API 기본 경로 |
AWS 설정
| 환경변수 | 기본값 | 설명 |
|---|---|---|
AWS_REGION | ap-northeast-2 | AWS 리전 |
AWS_ACCESS_KEY_ID | - | AWS Access Key (미지정 시 IAM 역할 사용) |
AWS_SECRET_ACCESS_KEY | - | AWS Secret Key |
S3_BUCKET_NAME | - (필수) | S3 버킷 이름 |
S3_UPLOAD_PART_SIZE | 5242880 (5MB) | Multipart 청크 크기 |
MEDIA_UPLOAD_QUEUE_URL | - (필수) | 업로드 이벤트 SQS URL |
MEDIA_READY_QUEUE_URL | - | 처리 완료 SQS URL |
JWT 설정
| 환경변수 | 기본값 | 설명 |
|---|---|---|
JWT_SECRET_KEY | - | 토큰 검증 비밀 키 |
JWT_ISSUER | truloop-core | 예상 토큰 발급자 |
JWT_AUDIENCE | truloop-clients | 예상 토큰 대상 |
Redis 설정
| 환경변수 | 기본값 | 설명 |
|---|---|---|
REDIS_ADDR | localhost:6379 | Redis 서버 주소 (필수) |
REDIS_PASSWORD | - | Redis 비밀번호 |
REDIS_DB | 0 | Redis DB 번호 (0-15) |
REDIS_TLS | false | TLS 활성화 |
Worker 설정
| 환경변수 | 기본값 | 설명 |
|---|---|---|
ENABLE_MEDIA_WORKER | true | 백그라운드 처리 활성화 |
MAX_MEDIA_PROCESSING_WORKERS | 2 | 변환 생성 동시 처리 수 |
MAX_S3_UPLOAD_WORKERS | 0 (auto) | S3 업로드 동시 처리 수 |
MAX_VIDEO_PROCESSING_WORKERS | 0 (auto) | FFmpeg 동시 처리 수 |
모니터링 설정
| 환경변수 | 기본값 | 설명 |
|---|---|---|
SENTRY_DSN | - | Sentry 에러 추적 URL |
SENTRY_SAMPLE_RATE | 1.0 | 에러 샘플링 비율 |
SENTRY_TRACES_SAMPLE_RATE | 0.1 | 트랜잭션 샘플링 비율 |
ENVIRONMENT | - | 환경 이름 |
Docker 빌드
Multi-stage 빌드로 ARM64 (Graviton) 플랫폼 대상의 최소 프로덕션 이미지를 생성합니다:
| 스테이지 | 역할 |
|---|---|
| Builder | golang:1.25-alpine 기반, Go 바이너리 컴파일 (CGO 활성화, WebP 지원) |
| Final | Alpine 기반, 런타임 의존성만 포함 (FFmpeg, exiftool, libwebp, zimg, ca-certificates) |
정적 바이너리 링킹 (-linkmode external -extldflags "-static")으로 Linux 배포판 간 호환성을 보장합니다. Non-root 유저 (appuser:appgroup)로 실행됩니다. Docker HEALTHCHECK가 /media/health 엔드포인트를 30초 간격으로 확인합니다.
CI/CD에서 docker buildx를 사용하여 linux/arm64 플랫폼으로 빌드합니다. ECS Fargate에서 ARM64 아키텍처(runtimePlatform: ARM64/LINUX)로 실행되며, Graviton 프로세서를 활용하여 비용을 절감합니다.
변경 이력
| 날짜 | 내용 |
|---|---|
| 2026-03-11 | Docker 빌드 ARM64 (Graviton) 전환 반영: buildx linux/arm64 빌드, ECS Fargate ARM64 런타임 |
| 2026-03-10 | 소스 코드 기반 전면 검증: 아키텍처 다이어그램 (Redis 폴링, JobQueue 서비스, HEVC), Service/Worker 레이어 테이블, 시퀀스 다이어그램 (크기 기반 업로드, Redis 큐), JWT/Redis 설정 섹션, Docker 빌드 정보 수정 |