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-manipulatorJPEG 재인코딩 → EXIF 제거·HEIC 변환):thumb(긴 변 ~400, q70) ·display(긴 변1600, q80) ·90). 파일은 변형 없이 단일 업로드.original(풀 해상도, q - 업로드 경로:
front-apiPOST /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에서.