Cloudflare R2 Direct Upload & Presigned URLs: 백엔드 서버 릴레이 없는 $0 대용량 파일 업로드 가이드

백엔드 릴레이 업로드의 비극: 메모리 타임아웃과 대역폭 과금

대용량 이미지, 고해상도 비디오, 대용량 PDF 문서를 처리하는 웹/모바일 애플리케이션에서 개발자들이 가장 흔히 범하는 아키텍처 실수는 “클라이언트 -> 백엔드 API 서버 -> 오브젝트 스토리지(S3/R2)” 경로로 전달되는 릴레이(Relay) 업로드 방식이다.

[비효율적인 백엔드 릴레이 업로드 방식]
[Client] --- (100MB 파일 업로드) ---> [Node.js / Lambda Server] --- (100MB 다시 전송) ---> [Storage]
                                     * 서버 RAM 메모리 버퍼링 폭발
                                     * CPU execution time 및 타임아웃 갱신
                                     * 이중 대역폭 및 Egress 과금 발생

이 릴레이 방식은 다음과 같은 치명적인 클라우드 병목을 유발한다:

1. 서버 컴퓨팅 타임과 메모리 폭탄: 100MB~1GB 단위의 대용량 파일이 백엔드 서버 메모리에 버퍼링되면서 RAM 부족(OOM Error)이 발생하거나, HTTP 통신이 30초 이상 유지되어 AWS Lambda나 Cloudflare Worker가 타임아웃 종료된다.
2. 이중 대역폭 비용: 대용량 데이터를 클라이언트에서 서버로 한 번 수신하고, 서버에서 다시 S3 스토리지로 보송하느라 네트워크 인바운드/아웃바운드 수수료가 2배로 발생한다.
3. 병목 현상: 서버 인프라 스케일링이 파일 업로드 대역폭에 묶여 전체 서비스 속도가 저하된다.

Cloudflare R2 Presigned URLs (사전 서명된 URL) 및 Direct Upload 아키텍처는 이 문제를 완벽하게 해결한다.

백엔드 서버(Cloudflare Worker)는 오직 1ms 만에 보안 암호화 서명된 Presigned PUT URL만 발행해주고, 클라이언트(Web / Flutter)는 이 URL을 통해 Cloudflare R2 스토리지 버킷으로 파일을 직접(Direct) 1:1 전송한다.

이 방식은 백엔드 서버의 컴퓨팅 소모를 99% 절감할 뿐만 아니라, Cloudflare R2 특유의 “아웃바운드 Egress 수수료 $0” 혜택과 결합하여 완벽한 $0 대용량 파일 업로드 파이프라인을 선사한다.

이 글에서는 Presigned URL의 동작 원리부터 단일 파일 직렬 업로드, 100MB~5GB 파일 멀티파트 업로드(Multipart Upload), CORS 보안 설정, 그리고 실전 벤치마크까지 상세히 다룬다.

R2 Direct Upload 아키텍처 비교

R2 Direct Upload 동작 원리: Presigned PUT URL 암호화

Cloudflare Workers에는 AWS S3 API 표준 암호화 라이브러리(@aws-sdk/client-s3) 및 @aws-sdk/s3-request-presigner를 사용할 수 있다.

+-----------------------------------------------------------------------------------+
| Cloudflare R2 Presigned Direct Upload 파이프라인                                   |
+-----------------------------------------------------------------------------------+

[Client (Web / Flutter)]         [Cloudflare Worker (1ms)]        [Cloudflare R2 Bucket]
           |                                 |                                |
           |--- 1. 업로드 요청 (파일명/크기) ->|                                |
           |                                 |--- 2. HMAC 서명 URL 생성 ---->| (Presigned PUT URL)
           |<-- 3. Presigned URL 반환 -------|                                |
           |                                                                  |
           |----------------------- 4. Direct HTTP PUT (바이너리 전송) -------->|
           |<---------------------- 5. 200 OK (업로드 완료) -------------------|

1. 서명 요청: 클라이언트는 업로드할 파일명(video.mp4), mimeType(video/mp4), 용량을 Worker로 전송한다.
2. Presigned PUT URL 생성: Worker는 AWS S3 HMAC-SHA256 알고리즘을 사용해 5분간만 유효한 암호화 서명 URL을 1ms 만에 발급한다.
3. Direct HTTP PUT 전송: 클라이언트는 획득한 Presigned URL로 직접 HTTP PUT 요청을 보내 데이터를 R2로 무인 전송한다.

1단계: R2 버킷 생성 및 CORS 보안 설정

클라이언트 브라우저가 Cloudflare R2 도메인으로 직접 HTTP PUT 요청을 보내려면 R2 버킷에 CORS (Cross-Origin Resource Sharing) 규칙을 지정해야 한다.

wrangler.jsonc R2 버킷 바인딩

// wrangler.jsonc
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "edge-r2-direct-upload",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-01",
  "compatibility_flags": ["nodejs_compat"],

  // Cloudflare R2 버킷 바인딩
  "r2_buckets": [
    {
      "binding": "MY_BUCKET",
      "bucket_name": "effidev-media-uploads"
    }
  ]
}

R2 버킷 CORS 정책 설정 (cors.json)

wrangler r2 bucket cors set 명령어를 통해 허용된 원본 도메인(Origin)과 PUT 메서드를 지정한다.

[
  {
    "AllowedOrigins": ["https://effidev.dev", "http://localhost:3000"],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
    "AllowedHeaders": ["Content-Type", "x-amz-*"],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3600
  }
]

npx wrangler r2 bucket cors set effidev-media-uploads --file=cors.json

2단계: 에지 서버리스 Presigned URL 발급 API 구현 (Hono.js)

AWS S3 SDK를 Cloudflare Workers 호환 파이프라인으로 구성하여 Presigned PUT URL을 발급하는 Hono.js 서버다.

패키지 설치

npm install hono @aws-sdk/client-s3 @aws-sdk/s3-request-presigner

Presigned URL 발급 핸들러 (src/index.ts)

// src/index.ts
import { Hono } from "hono";
import { cors } from "hono/cors";
import {
  S3Client,
  PutObjectCommand,
  CreateMultipartUploadCommand,
  UploadPartCommand,
  CompleteMultipartUploadCommand,
} from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

type Env = {
  Bindings: {
    MY_BUCKET: R2Bucket;
    R2_ACCOUNT_ID: string;
    R2_ACCESS_KEY_ID: string;
    R2_SECRET_ACCESS_KEY: string;
    R2_BUCKET_NAME: string;
  };
};

const app = new Hono<Env>();
app.use("*", cors());

// Cloudflare R2 S3 호환 클라이언트 팩토리
function getR2S3Client(env: Env["Bindings"]) {
  return new S3Client({
    region: "auto",
    endpoint: `https://${env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
    credentials: {
      accessKeyId: env.R2_ACCESS_KEY_ID,
      secretAccessKey: env.R2_SECRET_ACCESS_KEY,
    },
  });
}

// -------------------------------------------------------------------
// 1. 단일 파일 (100MB 이하) Presigned PUT URL 발급 API
// -------------------------------------------------------------------
app.post("/api/upload/presigned-url", async (c) => {
  const { fileName, contentType, fileSize } = await c.req.json();

  // 보안 유효성 검증: 최대 100MB 제한
  if (fileSize > 100 * 1024 * 1024) {
    return c.json({ error: "File size exceeds 100MB limit. Use multipart upload." }, 400);
  }

  const s3Client = getR2S3Client(c.env);
  const fileKey = `uploads/${Date.now()}_${crypto.randomUUID().slice(0, 8)}_${fileName}`;

  const command = new PutObjectCommand({
    Bucket: c.env.R2_BUCKET_NAME || "effidev-media-uploads",
    Key: fileKey,
    ContentType: contentType,
  });

  // 5분(300초) 유효기간의 Presigned PUT URL 서명 생성 (1ms 소요)
  const presignedUrl = await getSignedUrl(s3Client, command, { expiresIn: 300 });

  return c.json({
    success: true,
    fileKey,
    uploadUrl: presignedUrl,
    expiresIn: 300,
  });
});

3단계: 대용량 파일 (100MB ~ 5GB) 멀티파트 업로드 API

비디오나 대용량 바이너리 데이터는 청크(Chunk) 단위로 분할하여 병렬 업로드하고 합치는 Multipart Upload 방식을 적용한다.

// -------------------------------------------------------------------
// 2. 대용량 멀티파트 업로드 - Step 1: 멀티파트 세션 시작
// -------------------------------------------------------------------
app.post("/api/upload/multipart/initiate", async (c) => {
  const { fileName, contentType } = await c.req.json();
  const s3Client = getR2S3Client(c.env);
  const fileKey = `videos/${Date.now()}_${fileName}`;

  const command = new CreateMultipartUploadCommand({
    Bucket: c.env.R2_BUCKET_NAME,
    Key: fileKey,
    ContentType: contentType,
  });

  const response = await s3Client.send(command);

  return c.json({
    uploadId: response.UploadId,
    fileKey: fileKey,
  });
});

// -------------------------------------------------------------------
// 3. 대용량 멀티파트 업로드 - Step 2: 각 청크(Part)별 Presigned URL 발급
// -------------------------------------------------------------------
app.post("/api/upload/multipart/presigned-part", async (c) => {
  const { fileKey, uploadId, partNumber } = await c.req.json();
  const s3Client = getR2S3Client(c.env);

  const command = new UploadPartCommand({
    Bucket: c.env.R2_BUCKET_NAME,
    Key: fileKey,
    UploadId: uploadId,
    PartNumber: partNumber,
  });

  const uploadUrl = await getSignedUrl(s3Client, command, { expiresIn: 600 });
  return c.json({ partNumber, uploadUrl });
});

// -------------------------------------------------------------------
// 4. 대용량 멀티파트 업로드 - Step 3: 업로드 완료 조립 (Complete)
// -------------------------------------------------------------------
app.post("/api/upload/multipart/complete", async (c) => {
  const { fileKey, uploadId, parts } = await c.req.json();
  // parts 예시: [{ PartNumber: 1, ETag: '"e123..."' }, { PartNumber: 2, ETag: '"f456..."' }]
  const s3Client = getR2S3Client(c.env);

  const command = new CompleteMultipartUploadCommand({
    Bucket: c.env.R2_BUCKET_NAME,
    Key: fileKey,
    UploadId: uploadId,
    MultipartUpload: { Parts: parts },
  });

  await s3Client.send(command);

  return c.json({
    success: true,
    fileUrl: `https://pub-effidev-media.r2.dev/${fileKey}`,
  });
});

export default app;

4단계: 클라이언트 (Web / Flutter) Direct Upload 연동

웹(Web 브라우저) JavaScript 연동 예시

클라이언트는 백엔드에서 uploadUrl만 받아온 뒤 fetch(uploadUrl, { method: 'PUT', body: file })로 직접 전송한다.

// 프론트엔드 단일 파일 Direct Upload 함수
async function uploadFileDirectToR2(file) {
  // 1. Worker에 1ms 서명 URL 요청
  const res = await fetch("/api/upload/presigned-url", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      fileName: file.name,
      contentType: file.type,
      fileSize: file.size,
    }),
  });

  const { uploadUrl, fileKey } = await res.json();

  // 2. Cloudflare R2 버킷으로 직접 HTTP PUT 전송 (백엔드 릴레이 없음!)
  const uploadRes = await fetch(uploadUrl, {
    method: "PUT",
    headers: {
      "Content-Type": file.type,
    },
    body: file, // File / Blob 객체 바이너리 전송
  });

  if (uploadRes.ok) {
    console.log("R2 Direct Upload Success:", fileKey);
    return fileKey;
  } else {
    throw new Error("Direct upload failed to R2 bucket");
  }
}

실무 성능 및 비용 벤치마크

10GB 분량의 대용량 미디어 파일(100MB 100개) 업로드 처리 시, 전통적 백엔드 릴레이 방식과 Cloudflare R2 Presigned Direct Upload의 비교 리포트다.

성능 & 비용 비교표

결론: 서버를 거치지 않는 현대적 파일 아키텍처

더 이상 대용량 파일 데이터를 처리하기 위해 백엔드 서버 메모리를 낭비하고, 타임아웃과 싸우며, 대역폭 Egress 요금 폭탄을 맞을 이유가 없다.

Cloudflare Workers와 R2 Presigned URLs Direct Upload 조합은 다음과 같은 결정적 이점을 선사한다:

1. 서버 인프라 소모 ZERO: 백엔드 Worker는 1ms 만에 서명 URL을 내주고 종료되어 메모리와 CPU 소모가 전혀 없다.
2. Egress 수수료 $0: Cloudflare R2의 혜택으로 대용량 아웃바운드 트래픽 비용이 $0이다.
3. 무제한 확장성 (Scalability): 클라이언트가 R2 에지 버킷으로 직접 1:1 전송하므로 동시 업로드 유저가 수만 명으로 늘어나도 백엔드 서버 부하가 없다.
4. 대용량 멀티파트 지원: 5GB 이상의 초대형 비디오도 에지 파이프라인으로 병렬 처리한다.

지금 바로 백엔드 릴레이 업로드 로직을 R2 Presigned Direct Upload로 전환하고, 99% 비용 절감과 무장애 1초 업로드 UX를 경험해보자.

관련 글: AWS S3에서 Cloudflare R2로 전면 이관: Egress $0 및 이미지 처리 비용 95% 절감 가이드에서 R2 아키텍처 구축 가이드도 함께 확인할 수 있다.