Skip to content

refactor: 파일 저장소를 MinIO에서 Cloudflare R2로 교체 - #157

Merged
tnals0924 merged 1 commit into
developfrom
refactor/r2-storage
Nov 11, 2026
Merged

tnals0924 merged 1 commit into
developfrom
refactor/r2-storage

Conversation

@tnals0924

Copy link
Copy Markdown
Member

#️⃣연관된 이슈

  • 없음

🎯 해결하려는 문제가 무엇인가요?

이미지 저장소(물품 이미지, 디스플레이 포스터)가 MinIO SDK에 묶여 있습니다. 파일 저장소를 Cloudflare R2로 옮기기 위해 FileStorageService 구현체를 R2 기준으로 교체합니다.

❓ 왜 해결해야 하나요?

저장소를 R2로 이전하기로 했고, 애플리케이션이 R2에 업로드·삭제하려면 클라이언트와 URL 규칙이 R2에 맞아야 합니다. FileStorageService 인터페이스가 이미 분리돼 있어 구현체만 바꾸면 되므로, 호출하는 쪽(ItemService, DisplayPosterFacade)은 그대로 둡니다.

⭐ 어떻게 해결했나요?

  • global/external/minio/ 삭제, global/external/r2/ 추가 (R2Config, R2Service)
  • 의존성 io.minio:minio:8.5.7 → software.amazon.awssdk:s3:2.54.15 (Cloudflare 문서가 안내하는 AWS SDK v2 방식)
  • S3Client 설정
    • endpointOverride(R2_ENDPOINT), region("auto"), forcePathStyle(true)
    • requestChecksumCalculation / responseChecksumValidation = WHEN_REQUIRED — 최신 AWS SDK는 모든 요청에 체크섬을 붙이는데 R2가 이를 다 지원하지 않아서 필요할 때만 계산하도록 제한
  • 반환 URL 규칙 변경: {base-url}/{bucket}/{key} → {public-url}/{key}
    • R2 공개 URL(r2.dev 또는 커스텀 도메인)은 버킷에 직접 연결되므로 경로에 버킷명이 들어가지 않습니다
    • public-url 끝의 /는 정리해 //가 생기지 않도록 처리
  • 설정 키 minio.* → r2.* (dev/prod yml)
    • R2_ENDPOINT, R2_ACCESS_KEY, R2_SECRET_KEY, R2_BUCKET, R2_PUBLIC_URL
  • CLAUDE.md, README.md의 스택·의존성·환경변수 설명 갱신

🧩 이 PR의 한계 & 트레이드오프

  • 기존 데이터 이전은 범위 밖 — MinIO에 있는 이미지 파일 복사와 DB의 image_url 치환은 코드가 아니라 수동 작업이라 포함하지 않았습니다.
  • 실제 R2로는 검증하지 않음 — 로컬 가짜 S3 서버로 업로드 → HEAD → DELETE → 없는 파일 삭제(404) 흐름과 요청 경로(/{bucket}/{key})·Content-Type 전달만 확인했습니다. 실제 R2 연결은 dev 배포에서 확인이 필요합니다.

⛓️ 기존 기능에 미치는 영향

  • FileStorageService 시그니처 변화 없음 → 호출부 코드 변경 없음
  • 아래 환경변수가 없으면 애플리케이션이 시작되지 않습니다 → 머지·배포 전 Coolify(dev/prod)에 등록 필수
    • 추가: R2_ENDPOINT(https://<ACCOUNT_ID>.r2.cloudflarestorage.com), R2_ACCESS_KEY, R2_SECRET_KEY, R2_BUCKET, R2_PUBLIC_URL
    • 정리(검증 후): MINIO_* 5종
  • 로컬 실행 시 application-local.yml에 r2: 설정 추가 필요 (gitignore 대상이라 이 PR에 포함되지 않음)

🔀 Edge Case & 실패 시나리오

  • 기존 MinIO URL을 그대로 두면 물품 삭제가 실패합니다 — https://minio-api.billilge.site/prod/items/...는 R2_PUBLIC_URL 접두사와 맞지 않아 key 추출이 안 되고, HEAD 404 → IMAGE_NOT_FOUND가 나서 deleteItem 트랜잭션이 롤백됩니다. 파일을 items/..., posters/... 경로 그대로 R2에 복사(MinIO의 버킷 prefix prod/는 제거)한 뒤 DB URL을 치환해야 합니다.
    UPDATE item SET image_url = REPLACE(image_url, 'https://minio-api.billilge.site/prod/', '<R2_PUBLIC_URL>/');
    -- display_poster도 동일하게 처리
  • 업로드 중 IOException 또는 SDK 오류 → IMAGE_UPLOAD_FAILED
  • 삭제 시 HEAD 404 → IMAGE_NOT_FOUND, 그 외 오류 → IMAGE_DELETE_FAILED (기존 MinIO 구현은 오류 종류와 상관없이 모두 IMAGE_NOT_FOUND로 처리했습니다)

📋 검토한 대안과 선택 이유

  • MinIO SDK를 그대로 두고 엔드포인트만 R2로 변경: S3 호환이라 동작은 하지만, Cloudflare가 공식으로 안내하는 방식은 AWS SDK이고 R2 전용 설정(체크섬 등)도 AWS SDK 쪽이 명확해서 교체를 택했습니다.
  • account-id만 받아 엔드포인트를 코드에서 조합: 관할 구역(EU 등) 전용 엔드포인트를 쓸 수 없어서, 엔드포인트 전체를 환경변수로 받도록 했습니다.

💬 리뷰 포인트

  • [r] 머지·배포 전 Coolify dev/prod에 R2_* 환경변수 5종 등록, 그리고 기존 이미지 복사와 DB URL 치환 순서 확인. MinIO는 검증이 끝날 때까지 삭제하지 말 것(롤백 경로)
  • [c] dev → prod 순으로 물품 이미지 업로드·수정·삭제를 검증
  • [a] R2 버킷의 공개 접근(r2.dev 또는 커스텀 도메인)이 켜져 있어야 이미지 URL이 열립니다

🤖 Generated with Claude Code

- MinIO SDK를 AWS SDK v2(S3 호환)로 교체하고 R2Config/R2Service 구현
- R2 공개 URL은 버킷에 직접 연결되므로 이미지 URL에서 버킷명 제거
- R2 비호환 기본 체크섬 계산을 WHEN_REQUIRED로 제한
- 설정 키를 minio.* 에서 r2.* 로 변경 (R2_ENDPOINT, R2_ACCESS_KEY, R2_SECRET_KEY, R2_BUCKET, R2_PUBLIC_URL)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@tnals0924 tnals0924 added the refactoring 코드 리팩터링 label Nov 11, 2026
@tnals0924 tnals0924 self-assigned this Nov 11, 2026
@tnals0924
tnals0924 merged commit d98240d into develop Nov 11, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

refactoring 코드 리팩터링

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant