본문으로 바로가기 본문 바로가기
WIKI 기술 지식 베이스

문제 해결 (Troubleshooting)

원문 보기 위키 갱신

CORS 오류, 403 응답, 캐시 동작 등 흔한 R2 문제들을 해결하는 방법을 알려드려요.

출처: 문서

본문

R2의 403 / CORS 문제 해결하기 (Troubleshooting 403 / CORS issues with R2)

모든 것을 올바르게 설정했는데도 CORS 오류가 발생한다면, 이 문제 해결 가이드를 따라가 보세요.

브라우저 콘솔에서 CORS 오류 위에 401/403 오류가 보인다면, 그건 CORS와 무관한 다른 문제예요.

정말 CORS 문제라면 CORS 문제 해결을 참고하세요.

커스텀 도메인을 사용하는 경우

  1. 브라우저에서 개발자 도구(developer tools)를 여세요.
  2. Network 탭으로 이동해 실패한 요청을 찾으세요. 요청은 개발자 도구를 연 후에만 로깅되므로 페이지를 새로고침해야 할 수도 있어요.
  3. 응답 헤더에서 다음 두 헤더를 확인하세요:
  • cf-cache-status
  • cf-mitigated
cf-mitigated 헤더가 있는 경우

요청이 WAF 규칙 중 하나에 의해 차단된 거예요. 차단 원인을 파악하려면 Security Events를 확인하세요.

cf-cache-status 헤더가 없는 경우

요청이 Hotlink Protection에 의해 차단된 거예요.

Configuration Rule을 사용해 Hotlink Protection 설정을 수정하거나, 완전히 비활성화하세요.

S3 API를 사용하는 경우

요청이 잘못 서명(signed)되었을 수 있어요. 요청을 curl로 시도하면 더 나은 오류 메시지를 얻을 수 있어요.

Examples 페이지의 동작하는 S3 서명 예시를 참고하세요.

정말 CORS 문제인 경우

CORS 구성에서 흔히 발생하는 문제들:

  • ExposeHeaders에 ETag 같은 헤더가 빠져 있음
  • AllowedHeaders에 Authorization 또는 Content-Type 같은 헤더가 빠져 있음
  • AllowedMethods에 POST/PUT 같은 메서드가 빠져 있음

객체 수준 API 토큰이 REST API에서 실패하는 경우 (Object-level API tokens fail against the REST API)

Object Read & Write 또는 Object Read only 권한으로 만든 R2 API 토큰을 Cloudflare REST API(api.cloudflare.com)에 사용하면, 객체 요청이 인증에 실패하고 다음 중 하나를 반환해요:

  • 토큰이 모든 버킷에 적용되는 경우: {"code":10002,"message":"Unauthorized"} (HTTP 401).
  • 토큰이 특정 버킷으로 범위가 제한된 경우: {"code":10000,"message":"Authentication error"} (HTTP 403).

객체 수준 토큰은 AWS Signature Version 4(SigV4)로 인증하는 S3 호환 API에서만 지원돼요.

이 문제를 해결하려면:

  • 객체 수준 토큰을 계속 사용하려면, 요청을 REST API 대신 S3 호환 API로 보내세요. S3 호환 API는 객체 작업에도 더 적합해요. REST API에는 속도 제한이 있거든요.
  • REST API를 사용하려면 Admin Read & Write 또는 Admin Read only 토큰으로 인증하세요. Admin 토큰은 버킷 범위가 아닌 계정 전체 접근 권한을 부여해요.

HTTP 5XX 오류와 Cloudflare R2의 용량 제한 (HTTP 5XX Errors and capacity limitations)

HTTP 5XX 오류가 발생하면, 보통 R2 버킷이 너무 많은 동시 요청으로 압도당했음을 나타내는 신호예요. 이런 오류는 버킷 전체 읽기·쓰기 잠금을 트리거해 진행 중인 모든 작업의 성능에 영향을 줄 수 있어요.

이런 중단을 피하려면 요청 볼륨을 관리하는 전략을 구현하는 것이 중요해요.

다음과 같은 완화 조치를 취할 수 있어요:

동시 요청 모니터링 (Monitor concurrent requests)

버킷에 대한 동시 요청 수를 추적하세요. 클라이언트가 5XX 오류를 만나면, 작업을 재시도하고 다른 클라이언트와 통신하도록 하세요. 클라이언트들이 조정(coordinate)하면 집단적으로 속도를 늦춰 요청 비율을 낮추고 성공적인 작업의 흐름을 더 안정적으로 유지할 수 있어요.

사용자가 버킷에 직접 업로드하는 경우(예: S3 또는 Workers API 사용), 동시성 제한을 모니터링하거나 강제하지 못할 수도 있어요. 그런 경우에는 버킷 샤딩(bucket sharding)을 권장해요.

버킷 샤딩 (Bucket sharding)

복잡성이 추가되는 대신 더 높은 용량이 필요하다면 버킷 샤딩을 고려하세요. 이 접근 방식은 읽기와 쓰기를 여러 버킷에 분산해 단일 버킷의 부하를 줄여요. 샤딩은 단일 hot 객체가 용량을 소진하는 것을 막을 수는 없지만, 전반적인 영향을 완화하고 시스템 복원력을 개선할 수 있어요.

This object is unnamed(이 객체는 이름이 없습니다)라는 객체 (Objects named This object is unnamed)

Cloudflare 대시보드에서 View prefixes as directories를 선택하면 이름에 /가 있는 객체를 폴더로 볼 수 있어요.

예를 들어 example/object라는 객체는 아래처럼 표시돼요.

  • example
    • object

이름이 /로 끝나는 객체는 Cloudflare 대시보드가 그 객체를 폴더로 렌더링하게 하고, 그 안에 이름 없는 객체를 표시해요.

예를 들어 example/라는 객체를 R2 버킷에 업로드하면 아래처럼 표시돼요.

  • example
    • This object is unnamed

더 알아보기 (Learn more)