로컬 업로드 (Local uploads)

원문 보기 위키 갱신 2026.10.07

버킷에서 로컬 업로드(Local Uploads) 를 활성화하면, 클라이언트가 버킷과 다른 지역에서 데이터를 업로드할 때 업로드 요청 성능을 개선할 수 있어요. 로컬 업로드는 객체 데이터를 가까운 위치에 먼저 쓴 뒤, 버킷으로 비동기적으로 복사해요. 데이터는 즉시 사용할 수 있고 강력한 일관성(strongly consistent)을 유지해요.

출처: 문서

본문

작동 방식 (How it works)

다음 섹션에서는 로컬 업로드를 활성화했을 때와 그렇지 않을 때 R2가 업로드 요청을 처리하는 방식을 설명해요.

로컬 업로드 없이 (Without Local Uploads)

클라이언트가 R2 버킷에 객체를 업로드하면, 객체 데이터는 클라이언트에서 버킷의 스토리지 인프라까지 이동해야 해요. 클라이언트가 버킷과 다른 지역에 있다면 이 동작은 더 높은 지연 시간과 낮은 안정성을 초래할 수 있어요. 자세한 내용은 R2의 작동 방식을 참고해요.

로컬 업로드 사용 시 (With Local Uploads)

로컬 업로드가 활성화된 버킷에 업로드 요청(즉 PutObject와 UploadPart)을 보내면 다음 두 가지 경우가 처리돼요.

클라이언트와 버킷이 같은 지역: R2는 일반 업로드 흐름을 따르며, 객체 데이터는 클라이언트에서 버킷의 스토리지 인프라로 업로드돼요.
클라이언트와 버킷이 다른 지역: 객체 데이터는 클라이언트 근처의 스토리지에 먼저 쓰인 뒤 버킷으로 비동기적으로 복제돼요. 객체는 즉시 접근할 수 있으며 그 과정에서도 내구성(durability)을 유지해요.

로컬 업로드를 사용하는 경우 (When to use local uploads)

로컬 업로드는 버킷이 위치한 지역과 다른 여러 지역에서 발생하는 대량의 업로드를 받는 워크로드를 위해 설계됐어요. 이 기능은 다음 상황에 적합해요.

사용자가 전 세계에 분산되어 있을 때
업로드 성능과 안정성이 애플리케이션에 중요한 경우
버킷의 기본 위치를 바꾸지 않고 쓰기 성능을 최적화하고 싶을 때

읽기와 쓰기 요청이 어느 지역에서 시작되는지 파악하려면:

Cloudflare 대시보드에 로그인하고 R2 개요(Overview)로 이동해요. 개요(Overview)로 이동 ↗
버킷을 선택해요.
메트릭(Metrics) 을 선택하고 요청 분포(Request Distribution) 차트를 확인해요.

읽기 지연 시간 고려 사항 (Read latency considerations)

로컬 업로드가 활성화되면 업로드된 데이터는 복제가 완료되기 전까지 일시적으로 클라이언트 근처에 머물 수 있어요.

쓰기 후 즉시 읽기가 필요한 워크로드라면, 읽기 요청이 시작되는 위치를 고려해 보세요. 업로더 지역에서의 읽기는 빠르지만, 버킷 지역 근처에서의 읽기는 복제가 완료될 때까지 크로스 리전 지연 시간을 겪을 수 있어요.

리전(jurisdiction) 제한 (Jurisdiction restriction)

로컬 업로드는 리전 제한(jurisdictional restrictions)이 있는 버킷에서는 지원되지 않아요. 데이터를 버킷 지역 외부의 위치로 일시적으로 라우팅해야 하기 때문이에요.

로컬 업로드 활성화 (Enable local uploads)

로컬 업로드를 활성화해도 기존 업로드는 예상대로 완료되며 트래픽이 중단되지 않아요.

Cloudflare 대시보드에 로그인하고 R2 개요(Overview)로 이동해요. 개요(Overview)로 이동 ↗
버킷을 선택해요.
설정(Settings) 을 선택해요.
로컬 업로드(Local Uploads) 아래에서 활성화(Enable) 를 선택해요.

다음 명령을 실행해도 돼요.

npx wrangler r2 bucket local-uploads enable <BUCKET_NAME>

로컬 업로드 비활성화 (Disable local uploads)

로컬 업로드는 언제든지 비활성화할 수 있어요. 로컬 업로드로 이루어진 기존 요청은 트래픽 중단 없이 복제를 완료해요.

Cloudflare 대시보드에 로그인하고 R2 개요(Overview)로 이동해요. 개요(Overview)로 이동 ↗
버킷을 선택해요.
설정(Settings) 을 선택해요.
로컬 업로드(Local Uploads) 아래에서 비활성화(Disable) 를 선택해요.