Skip to Content
DecisionsADR-0021: 채팅 첨부를 R2에 저장하고 이미지 변형을 클라이언트가 업로드 시 생성한다

ADR-0021: 채팅 첨부를 R2에 저장하고 이미지 변형을 클라이언트가 업로드 시 생성한다

  • Status: Accepted (Amended 2026-10-19 — 레거시 소스 source 판별 추가, 아래 Amendment)
  • Date: 2026-10-15
  • 관련: HMH-9972 (이번 작업 티켓) · 에픽 HMH-9765 (Sendbird 탈출) · ADR-0018(통합 채팅 데이터 모델) · HMH-10053(Amendment)

Context

통합 Supabase 채팅으로 이관하면서 채팅 첨부(이미지·파일) 저장을 정리해야 한다. 기존은 이미지=Cloudinary(front-api /api/cloudinary/signature 서명 → 클라 직접 업로드, URL 파라미터로 즉석 리사이즈·f_auto·q_auto), 파일=메인 백엔드(ChatAPI.uploadChatFileAttachment)로 이원화돼 있었다.

제약·사실:

  • 비용/소유권 정리를 위해 첨부 저장을 Cloudflare R2로 통일하려 한다(R2→Cloudflare egress 무료).
  • R2는 순수 오브젝트 스토리지라 Cloudinary 같은 즉석 변환이 없다. 썸네일·뷰어·포맷 변환을 누군가는 해야 한다.
  • 엣지 온디맨드 변환(Cloudflare Images / Image Resizing)은 서빙 호스트가 Cloudflare 존이어야 하는데, 본 도메인 DNS가 Route53에서 관리되고 Cloudflare 서브도메인-존 추가는 Enterprise 전용이라, 커스텀 도메인·Transformations 경로가 당장 막혔다(본 도메인 전체 이전은 팀 영향이 큰 별도 결정).
  • 첨부는 로그인 후에만 일어난다(기존 Cloudinary 서명도 verifyMe 로 인증 — HMH-9826).

검토한 대안

대안채택 안 한 이유
Cloudinary 유지저장/소유권 통일 목표에 어긋남. 변환 편의는 좋지만 비용·벤더 종속.
R2 + 엣지 온디맨드 변환(Cloudflare Images / Image Resizing)서빙이 Cloudflare 존 커스텀 도메인을 요구. 본 도메인은 Route53이고 서브도메인 존은 Enterprise 전용 → 당장 불가. 본 도메인 전체 이전은 과도.
R2 + 서버(Worker/Lambda+sharp) 변환추가 인프라·운영 부담. 현 단계엔 과함.
R2 + 클라이언트 업로드-시 변형 생성 (채택)CF 존·커스텀 도메인 불필요(아무 공개 URL로 서빙). expo-image-manipulator 재인코딩이 HEIC→JPEG·EXIF(GPS) 제거까지 공짜로 해결.

Decision

채팅 첨부는 R2에 저장하고, 이미지 변형은 클라이언트가 업로드 시 3종 생성해 각각 올린다.

  • 변형 3종(클라, expo-image-manipulator JPEG 재인코딩 → EXIF 제거·HEIC 변환): thumb(긴 변 ~400, q70) · display(긴 변 1600, q80) · original(풀 해상도, q90). 파일은 변형 없이 단일 업로드.
  • 업로드 경로: front-api POST /api/community/media/presign(apps/api/src/app/api/community/media/presign/route.ts, 헬퍼 apps/api/src/features/communityMediaR2.ts)가 verifyMe(Bearer) 인증 후 S3 호환 presigned PUT URL을 발급(@aws-sdk/client-s3 + s3-request-presigner). 클라가 R2에 직접 PUT.
  • 키 스킴(버킷이 커뮤니티 전용이라 type 프리픽스로 분류): 이미지 images/{channelId}/{uuid}/{purpose}.{ext}, 파일 files/{channelId}/{uuid}/file.{ext}. uuid 가 한 이미지의 3변형을 묶고, channelId 그룹핑은 디버그·채널 삭제 시 프리픽스 일괄 삭제·메트릭에 유리(messageId 는 presign 시점에 없어 uuid 로 그룹, HMH-9974). contentType 화이트리스트(이미지 jpeg/png/webp, 파일=기존 채팅 허용 타입).
  • 참조 저장: message.attachments(jsonb)에 키만 저장(packages/chat-core/types.ts 의 MessageAttachment). 서빙 URL은 COMMUNITY_MEDIA_R2_PUBLIC_BASE_URL + key 로 유도 → 서빙 도메인 교체(지금 r2.dev → 나중 커스텀 도메인) 시 데이터 마이그레이션 불필요.
  • env: COMMUNITY_MEDIA_R2_{ACCOUNT_ID,ACCESS_KEY_ID,SECRET_ACCESS_KEY,BUCKET,ENDPOINT,PUBLIC_BASE_URL}(front-api).

Consequences

좋아지는 것

  • Cloudflare 존·커스텀 도메인·엣지 변환 설정 없이 바로 진행(Route53 제약 우회).
  • 재인코딩으로 EXIF/GPS 제거·HEIC 정규화가 자동 — 프라이버시·호환성 이득.
  • R2 단일 저장소로 이미지·파일 통일, Cloudflare egress 무료.
  • 키만 저장 → 서빙 도메인 교체가 무중단(데이터 불변).

감수하는 것

  • 변형이 업로드 시 고정 생성이라 사이즈가 고정이고(온디맨드 유연성 없음), 업로드 횟수·클라 CPU가 늘어난다.
  • 서빙이 당장은 r2.dev(레이트리밋·prod 부적합) — prod 전환 시 커스텀 도메인(무료 egress·CDN) 필요(비블로킹 후속).
  • orphan: 업로드했지만 전송 안 한 오브젝트(permanent 키)가 남는다 — 정리는 후속(재조정 잡 또는 취소 정리).
  • presigned PUT은 크기 상한을 서버에서 강제하기 어려워(POST policy 아님) 크기 검증은 클라 + contentType 화이트리스트에 의존.

이 결정을 다시 열어야 할 때

  • 본 도메인을 Cloudflare로 옮기거나 미디어 전용 CF 존이 생기면 → 엣지 온디맨드 변환(원본만 저장)으로 전환해 변형 고정·업로드 횟수 문제를 없앨 수 있다.
  • 변형 요구가 다양해지거나(여러 뷰 사이즈) 서버 처리가 필요해지면 → 서버/엣지 변환 재검토.

Amendment (2026-10-19, HMH-10053) — 레거시 소스 표현

본 ADR은 신규 첨부를 R2 키로 저장하는 결정이다. 그런데 Sendbird→Supabase 이관(WS6) 으로 들어오는 과거 메시지의 첨부는 R2에 없다 — 저장소가 시기·종류별로 다르다(코드 실측 2026-10-19):

  • 이미지: 2023-01(Cloudinary 도입, commit 552d21da9) 이후 = Cloudinary(cloudinaryPublicId) / 이전 = Sendbird 스토리지(종료 시 소멸).
  • 파일: 백엔드 S3(CHAT_MESSAGE_FILE_CDN, ChatUploadFile) — Sendbird 무관하게 생존.

Cloudinary·S3는 앱 전반 존속 인프라(카페·설문·상담·프로필)라 채팅만 R2로 옮길 이득이 없다 → 참조 유지하고, R2 일원화는 미래 글로벌 Cloudinary·S3→R2 마이그레이션에 위임한다. 옛 Sendbird-호스팅 이미지만 소멸하므로 “만료” placeholder.

결정(타입 확장): MessageAttachment 에 source 판별 추가(없으면 r2 — 하위호환):

  • 이미지: r2(키 3변형) | cloudinary(publicId·w·h) | expired
  • 파일: r2(키) | s3(url) | expired

URL 해석은 chat-core resolveImageAttachment/resolveFileAttachment(media.ts) 한 곳에서 흡수 — 소비자(native·web·dashboard 렌더)는 source 를 모른다. 플랫폼 env(R2 base·Cloudinary 빌더)는 configureChatMedia 로 주입(중립 유지). DB 변경 없음(jsonb).

미래 호환: cloudinary는 publicId, s3는 url 을 보유 → 글로벌 마이그 툴이 에셋을 이동하고 source를 r2로 일괄 재작성, resolver가 투명 흡수(렌더 무변경). source 판별은 file.url 호스트로 한다: *.sendbird.com→expired(옛 Sendbird-호스팅, 종료 시 소멸) / Cloudinary 호스트→cloudinary / 백엔드 S3 CDN(CHAT_MESSAGE_FILE_CDN)→s3.

video(kind:'video')는 현 union에 없어 이번 Amendment 범위 밖 — 레거시 비디오 처리는 WS3-f3에서.

Last updated on