다크 모드
Media Service (Go) 개요
truloop-media-service는 대용량 미디어 업로드 및 비동기 처리를 전담하는 고성능 서비스입니다. Go 표준 라이브러리 기반으로 최소한의 메모리 사용과 최대 처리량을 달성합니다.
기술 스택
| 항목 | 기술 | 설명 |
|---|---|---|
| 언어 | Go 1.24+ | 성능 최적화 |
| 웹 서버 | net/http | 표준 라이브러리 (프레임워크 없음) |
| 스토리지 | AWS S3 | 미디어 파일 저장 |
| 메시징 | AWS SQS + Redis | SQS: 서비스 간 이벤트, Redis: 내부 Job Queue |
| 캐싱 | Redis (go-redis) | Idempotency key, Job Queue |
| 인증 | JWT | Bearer 토큰 검증 |
| ID 생성 | TSID (go-tsid) | 시간 기반 정렬 가능한 고유 ID |
| 이미지 처리 | disintegration/imaging + chai2010/webp | 리사이즈, WebP 변환 |
| 비디오 처리 | FFmpeg | HEVC (H.265) 기본, H.264 폴백, HDR 보존 |
| 에러 추적 | Sentry | Production 에러 모니터링 |
| 모니터링 | Prometheus | 메트릭 수집 (/media/metrics) |
| 테스트 | Go testing + testify | race detector 포함 |
주요 기능
- 최대 2GB 파일의 스트리밍 업로드
- 파일 크기 기반 업로드 전략: < 100MB는 단일 PutObject, >= 100MB는 S3 Multipart Upload
- 202 Accepted 패턴으로 즉각적인 클라이언트 응답
- 이미지: WebP 변환, optimized/thumbnail 변환 생성
- 비디오: HEVC (H.265) 인코딩 기본, HDR10/HLG 보존, WebP 썸네일 생성
- 비디오 스마트 처리: 이미 HEVC이고 해상도 이내이면 Remux (트랜스코딩 스킵)
- Idempotent 업로드 (Redis 기반 중복 방지)
- 동시 요청 제어
- EXIF 메타데이터 추출 (이미지/비디오)
- 구조화된 JSON 로깅 (
log/slog)
프로젝트 구조
truloop-media-service/
├── cmd/server/ # 애플리케이션 진입점
├── internal/ # 내부 패키지 (비공개)
│ ├── auth/ # JWT 인증 & 컨텍스트
│ ├── bufpool/ # 메모리 최적화 버퍼 풀링
│ ├── config/ # 환경 설정 관리
│ ├── handlers/ # HTTP 요청 핸들러
│ ├── metrics/ # Prometheus 메트릭 정의
│ ├── middleware/ # HTTP 미들웨어
│ ├── models/ # 데이터 구조
│ ├── server/ # HTTP 서버 설정 및 라우팅
│ ├── services/ # 비즈니스 로직
│ │ ├── idempotency/ # Idempotency key 관리
│ │ ├── image/ # 이미지 처리
│ │ ├── queue/ # SQS 큐 서비스
│ │ ├── storage/ # S3 스토리지
│ │ ├── video/ # 비디오 처리 (FFmpeg)
│ │ └── jobqueue/ # Redis 기반 작업 큐
│ ├── workers/ # 백그라운드 처리
│ └── utils/ # 유틸리티
├── Dockerfile # Multi-stage Docker 빌드
└── Makefile # 개발/빌드 명령어API 엔드포인트
| 경로 | 인증 | 설명 |
|---|---|---|
POST /media/api/v1/upload | JWT (Bearer) | 사용자 미디어 업로드 |
POST /media/internal/v1/upload | 없음 (Internal) | 서비스 간 미디어 업로드 |
DELETE /media/internal/v1/idempotency/flush | 없음 (Internal) | Idempotency key 초기화 |
GET /media/health | 없음 | 헬스체크 (S3, Redis, Worker 상태) |
GET /media/metrics | 없음 | Prometheus 메트릭 |
개발 명령어
bash
# 빌드
make build
# 개발 모드 실행
make run
# 테스트 (race detector 포함)
make test
# 유닛 테스트만
make test-unit
# 커버리지 리포트
make test-coverage
# 린트
make lint
# Docker 빌드
make docker-build
# 개발 환경 설정
make dev-setup미들웨어 체인
요청 처리 순서 (바깥쪽 → 안쪽):
Recovery → Sentry → Logging → Metrics → Routes| 미들웨어 | 역할 |
|---|---|
RecoveryMiddleware | 패닉 복구, 에러 메트릭 기록 |
SentryMiddleware | 에러 추적 (Repanic 모드) |
LoggingMiddleware | 구조화된 JSON 로깅 |
MetricsMiddleware | Prometheus HTTP 메트릭 수집 |
withAuth | JWT 검증 (사용자 업로드 엔드포인트만) |
변경 이력
| 날짜 | 내용 |
|---|---|
| 2026-03-10 | 소스 코드 기반 전면 검증: 기술 스택 (SQS+Redis, TSID, chai2010/webp, HEVC, testify), 주요 기능 (업로드 전략, 변환명, HEVC/HDR, Remux), 미들웨어 체인 수정 |