truloop Wiki

다크 모드

S3 구조 및 CDN ​

truloop-media-service의 S3 키 구조, 파일 변환 체계, CloudFront CDN 통합을 설명합니다.

S3 키 구조 ​

모든 미디어 파일은 사용자 EID와 업로드 날짜 기반의 계층적 경로에 저장됩니다. Internal API를 통해 user_eid 없이 업로드된 파일은 system 경로에 저장됩니다.

키 패턴 ​

users/{userEID}/{YYYY/MM/DD}/{UUID}.{ext}

이미지 파일 ​

변환S3 키 패턴예시
Originalusers/{userEID}/{YYYY/MM/DD}/{UUID}.{ext}users/ABC123/2026/03/09/550e8400.jpg
Optimizedusers/{userEID}/{YYYY/MM/DD}/{UUID}_optimized.webpusers/ABC123/2026/03/09/550e8400_optimized.webp
Thumbnailusers/{userEID}/{YYYY/MM/DD}/{UUID}_thumbnail.webpusers/ABC123/2026/03/09/550e8400_thumbnail.webp

비디오 파일 ​

변환S3 키 패턴예시
Originalusers/{userEID}/{YYYY/MM/DD}/{UUID}_original.{ext}users/ABC123/2026/03/09/550e8400_original.mov
Optimizedusers/{userEID}/{YYYY/MM/DD}/{UUID}_optimized.mp4users/ABC123/2026/03/09/550e8400_optimized.mp4
Thumbnailusers/{userEID}/{YYYY/MM/DD}/{UUID}_thumbnail.webpusers/ABC123/2026/03/09/550e8400_thumbnail.webp

키 구조 다이어그램 ​

S3 Bucket
└── users/
    └── {userEID}/
        └── {YYYY}/
            └── {MM}/
                └── {DD}/
                    ├── {UUID}.jpg                  # 이미지 원본
                    ├── {UUID}_optimized.webp        # 이미지 Optimized
                    ├── {UUID}_thumbnail.webp        # 이미지 Thumbnail
                    ├── {UUID}_original.mov          # 비디오 원본
                    ├── {UUID}_optimized.mp4         # 비디오 Optimized (HEVC)
                    └── {UUID}_thumbnail.webp        # 비디오 Thumbnail

파일 변환 체계 ​

이미지 변환 ​

  • 원본은 업로드 시 그대로 보관
  • Optimized와 Thumbnail은 백그라운드에서 비동기 생성
  • 모든 변환은 WebP 포맷

비디오 변환 ​

  • 원본은 _original 접미사로 보관
  • Optimized 변환은 FFmpeg HEVC로 비동기 생성 (HDR 보존)
  • WebP 썸네일도 비동기 생성
  • 최종 출력은 항상 MP4 (HEVC/H.265)

CDN 통합 ​

CloudFront 설정 ​

항목설명
환경변수CLOUDFRONT_DOMAIN
캐싱CloudFront 기본 정책 적용
원본S3 버킷

URL 생성 ​

CDN 도메인이 설정된 경우, 응답 URL은 CloudFront 도메인을 사용합니다:

# CloudFront 도메인 설정 시
https://cdn.truloop.app/users/ABC123/2026/03/09/550e8400_optimized.webp

# CloudFront 미설정 시 (S3 URI 형식)
s3://bucket-name/users/ABC123/2026/03/09/550e8400_optimized.webp

접근 제어 ​

접근 방식대상
Public ReadCloudFront를 통한 미디어 파일 조회
Authenticated WriteJWT 인증된 사용자의 업로드
Internal Write서비스 간 업로드 (ai-server → media-service)
IAMS3 GetObject, PutObject 권한 필요

데이터 보관 정책 ​

파일 유형보관 정책
원본영구 보관
Optimized/Thumbnail영구 보관 (원본과 동일 수명)
Optimized 비디오영구 보관

정보

현재 별도의 Lifecycle Policy는 적용되지 않으며, 모든 파일은 영구 보관됩니다. 향후 비용 최적화를 위해 Glacier 전환 정책을 검토할 수 있습니다.

변경 이력 ​

날짜내용
2026-03-10소스 코드 기반 전면 검증: 변환명 통일 (Public→Optimized), 비디오 썸네일 추가, 비디오 다이어그램 (HEVC), CDN 폴백 URI 형식, Internal API system 경로 설명 추가