문제 해결

이 페이지에서는 Cloud Storage 사용 시 발생할 수 있는 일반적인 오류의 문제 해결 방법을 설명합니다.

Cloud Storage와 같이 Google Cloud 서비스에 영향을 주는 리전 또는 전역 이슈에 대한 자세한 내용은 Google Cloud 상태 대시보드를 참조하세요.

원시 요청 로깅

gsutil 또는 Cloud Storage 클라이언트 라이브러리와 같은 도구를 사용하면 대부분의 요청 및 응답 정보가 도구에서 처리됩니다. 하지만 문제 해결에 도움이 되는 세부정보를 확인하는 것이 유용한 경우도 있습니다. 다음 안내를 따라 도구에 대한 요청 및 응답 헤더를 반환합니다.

Console

요청 및 응답 정보를 보는 방법은 Google Cloud Console을 사용하는 데 사용하는 브라우저에 따라 다릅니다. Chrome 브라우저의 경우 다음 안내를 따르세요.

  1. Chrome의 기본 메뉴 버튼()을 클릭합니다.

  2. 도구 더보기를 선택합니다.

  3. 개발자 도구를 클릭합니다.

  4. 나타나는 창에서 네트워크 탭을 클릭합니다.

gsutil

요청에 최상위 -D 플래그를 사용합니다. 예를 들면 다음과 같습니다.

gsutil -D ls gs://my-bucket/my-object

클라이언트 라이브러리

C++

  • 전체 HTTP 트래픽을 가져오려면 환경 변수 CLOUD_STORAGE_ENABLE_TRACING=http를 설정합니다.

  • 환경 변수 CLOUD_STORAGE_ENABLE_CLOG=yes를 설정하여 각 RPC의 로깅을 가져옵니다.

C#

ApplicationContext.RegisterLogger를 통해 로거를 추가하고 HttpClient 메시지 핸들러에서 로깅 옵션을 설정합니다. 자세한 내용은 FAQ 항목을 참조하세요.

Go

GODEBUG=http2debug=1 환경 변수를 설정합니다. 자세한 내용은 Go 패키지 net/http를 참조하세요.

요청 본문도 로깅하려면 커스텀 HTTP 클라이언트를 사용합니다.

자바

  1. 다음 콘텐츠로 'logging.properties'라는 파일을 만듭니다.

    # Properties file which configures the operation of the JDK logging facility.
    # The system will look for this config file to be specified as a system property:
    # -Djava.util.logging.config.file=${project_loc:googleplus-simple-cmdline-sample}/logging.properties
    
    # Set up the console handler (uncomment "level" to show more fine-grained messages)
    handlers = java.util.logging.ConsoleHandler
    java.util.logging.ConsoleHandler.level = CONFIG
    
    # Set up logging of HTTP requests and responses (uncomment "level" to show)
    com.google.api.client.http.level = CONFIG
  2. Maven에 logging.properties 사용

    mvn -Djava.util.logging.config.file=path/to/logging.properties insert_command

자세한 내용은 플러그인 가능한 HTTP 전송을 참조하세요.

Node.js

Node 스크립트를 호출하기 전에 NODE_DEBUG=https 환경 변수를 설정합니다.

PHP

httpHandler를 사용하여 클라이언트에 자체 HTTP 핸들러를 제공하고 요청 및 응답을 로깅하도록 미들웨어를 설정합니다.

Python

로깅 모듈을 사용합니다. 예를 들면 다음과 같습니다.

import logging
import http.client

logging.basicConfig(level=logging.DEBUG)
http.client.HTTPConnection.debuglevel=5

Ruby

require "google/cloud/storage".rb file의 상단에 다음을 추가합니다.

ruby
Google::Apis.logger.level = Logger::DEBUG

오류 코드

다음은 일반적으로 발생할 수 있는 HTTP 상태 코드입니다.

301: 영구 이전

문제: 정적 웹사이트를 설정 중인데 디렉터리 경로에 액세스하면 빈 객체와 301 HTTP 응답 코드가 반환됩니다.

해결 방법: http://www.example.com/dir/과 같은 디렉터리에 액세스할 때 브라우저에서 0바이트 객체가 다운로드되고 301 HTTP 응답 코드가 반환되는 경우 버킷에 해당 이름의 빈 객체가 있을 가능성이 높습니다. 이러한 경우인지 확인하고 문제를 해결하려면 다음 단계를 따릅니다.

  1. Google Cloud Console에서 Cloud Storage 브라우저 페이지로 이동합니다.

    브라우저로 이동

  2. Google Cloud Console 상단의 Cloud Shell 활성화 버튼을 클릭합니다. Cloud Shell 활성화
  3. gsutil ls -R gs://www.example.com/dir/을 실행합니다. 출력에 http://www.example.com/dir/이 포함된 경우 해당 위치에 빈 객체가 있는 것입니다.
  4. gsutil rm gs://www.example.com/dir/ 명령어를 사용하여 빈 객체를 삭제합니다.

이제 http://www.example.com/dir/에 액세스하여 빈 객체 대신 해당 디렉터리의 index.html 파일을 반환할 수 있습니다.

400: 잘못된 요청

문제: 재개 가능한 업로드를 수행하는 동안 이 오류 및 Failed to parse Content-Range header. 메시지가 발생했습니다.

해결 방법: Content-Range 헤더에 사용된 값이 잘못되었습니다. 예를 들어 Content-Range: */*는 유효하지 않으며 대신 Content-Range: bytes */*로 지정해야 합니다. 이 오류가 발생하면 현재 재개 가능한 업로드가 더 이상 활성 상태가 아니므로 재개 가능한 새 업로드를 시작해야 합니다.

401: 승인되지 않음

문제: 직접 또는 Cloud CDN을 통한 공개 버킷에 대한 요청이 HTTP 401: UnauthorizedAuthentication Required 응답으로 실패합니다.

해결 방법: 클라이언트 또는 모든 중간 프록시가 Cloud Storage에 대한 요청에 Authorization 헤더를 추가하지 않는지 확인합니다. Authorization 헤더가 있는 모든 요청은 비어 있더라도 인증 시도인 것처럼 검증됩니다.

403: 계정이 사용 중지됨

문제: 버킷을 만들려 했지만 403 Account Disabled 오류가 발생했습니다.

해결 방법: 이 오류는 관련 프로젝트에서 결제를 사용 설정하지 않은 경우에 발생합니다. 결제 설정 방법은 프로젝트에 대한 결제 설정을 참조하세요.

결제를 사용 설정해도 오류 메시지가 계속 나타나는 경우 프로젝트 ID와 문제에 대한 설명을 제공하여 지원을 받을 수 있습니다.

403: 액세스 거부됨

문제: 내 버킷에 있는 객체를 나열하려 했으나 403 Access Denied 오류가 발생했거나 Anonymous caller does not have storage.objects.list access와 유사한 메시지가 표시되었습니다.

해결 방법: 사용자 인증 정보가 올바른지 확인하세요. 예를 들어 gsutil을 사용하는 경우 .boto 파일에 저장된 사용자 인증 정보가 정확한지 확인합니다. 또한 gsutil version -l 명령어를 사용하고 config path(s) 항목을 확인하여 gsutil이 예상한 .boto 파일을 사용 중인지 확인합니다.

올바른 사용자 인증 정보를 사용 중이라고 가정하고 HTTPS 대신 HTTP를 사용하여 프록시를 통해 요청이 라우팅되는지 확인하세요. 라우팅된다면 프록시가 해당 요청에서 Authorization 헤더를 삭제하도록 구성되어 있는지 확인하세요. 이 경우에 해당하면 요청에 HTTP 대신 HTTPS를 사용하도록 합니다.

403: 금지됨

문제: storage.cloud.google.com에서 공개 콘텐츠를 다운로드하는 중인데 브라우저를 사용하여 공개 객체로 이동하면 403: Forbidden 오류가 발생합니다.

https://storage.cloud.google.com/BUCKET_NAME/OBJECT_NAME

해결 방법: storage.cloud.google.com을 사용하여 객체를 다운로드하는 것을 인증된 브라우저 다운로드라고 하며, allUsers가 객체에 공개적으로 액세스할 수 있어도 항상 쿠키 기반 인증이 사용됩니다. 객체에 대한 액세스를 추적하도록 Cloud 감사 로그의 데이터 액세스 로그를 구성한 경우 이 기능의 제한사항 중 하나는 인증된 브라우저 다운로드를 사용하여 영향을 받은 개체에 액세스할 수 없다는 것입니다. 이러한 작업을 수행하면 403 응답이 발생합니다.

이 문제를 방지하려면 다음 중 한 가지를 따르세요.

  • 인증된 브라우저 다운로드를 사용하는 대신 인증되지 않은 다운로드를 지원하는 직접 API 호출을 사용합니다.
  • 영향을 받은 객체에 대한 액세스를 추적하는 Cloud Storage 데이터 액세스 로그를 사용 중지합니다. 데이터 액세스 로그는 프로젝트 수준 이상에서 설정되며 여러 수준에서 동시에 사용 설정할 수 있습니다.
  • 데이터 액세스 로그 예외를 설정하면 데이터 액세스 로그 추적에서 특정 사용자를 제외하여 해당 사용자가 인증된 브라우저 다운로드를 수행할 수 있습니다.

409: 충돌

문제: 버킷을 만들려고 시도했지만 다음 오류가 발생했습니다.

409 Conflict. Sorry, that name is not available. Please try a different one.

해결 방법: 사용하려 했던 버킷 이름(예: gs://cats 또는 gs://dogs)이 이미 사용 중입니다. Cloud Storage에는 전역 네임스페이스가 있으므로 기존 버킷과 동일한 이름을 사용해서는 안 됩니다. 사용 중이 아닌 이름을 선택하세요.

429: 요청한 횟수가 너무 많음

문제: 429 Too Many Requests 오류와 함께 요청이 거부됩니다.

해결 방법: Cloud Storage가 특정 리소스에 허용하는 요청 수 한도에 도달하고 있습니다. Cloud Storage의 한도에 대한 설명은 Cloud Storage 할당량을 참조하세요. 버킷에 대한 초당 요청 1,000개로 구성된 워크로드의 경우 요청 비율 및 액세스 분배 가이드라인에서 워크로드 점진적으로 늘리고 순차적 파일 이름을 방지하는 방법을 포함한 권장사항을 알아보세요.

Google Cloud Console 오류 진단

문제: Google Cloud Console을 사용하여 작업을 수행하면 일반 오류 메시지가 표시됩니다. 예를 들어 버킷을 삭제하려고 할 때 오류 메시지가 표시되지만 작업이 실패한 이유에 대한 세부정보는 표시되지 않습니다.

해결 방법: Google Cloud Console의 알림을 사용하여 실패한 작업에 대한 자세한 정보를 확인합니다.

  1. Google Cloud Console 헤더에서 알림 버튼을 클릭합니다.

    알림

    Google Cloud Console이 수행한 가장 최근 작업이 드롭다운에 표시됩니다.

  2. 자세히 알아보려는 항목을 클릭합니다.

    페이지가 열리고 작업에 대한 자세한 정보가 표시됩니다.

  3. 각 행을 클릭하여 자세한 오류 정보를 펼칩니다.

    다음은 실패한 버킷 삭제 작업의 오류 정보 예시로, 버킷 보관 정책 때문에 버킷이 삭제되지 않았음을 설명합니다.

    버킷 삭제 오류 세부정보

gsutil 오류

다음은 일반적으로 발생할 수 있는 gsutil 오류입니다.

gsutil stat

문제: gsutil stat 명령어를 사용하여 하위 디렉터리의 객체 상태를 표시하려 했지만 오류가 발생했습니다.

해결 방법: Cloud Storage는 플랫 네임스페이스를 사용하여 객체를 버킷에 저장합니다. 객체 이름에 슬래시('/')를 사용하여 객체가 계층 구조에 있는 것처럼 표시되도록 할 수 있지만, gsutil stat 명령어는 후행 슬래시를 객체 이름의 일부로 취급합니다.

예를 들어 gsutil -q stat gs://my-bucket/my-object/ 명령어를 실행하면 gsutil은 my-bucket/my-object/ 아래에 중첩된 객체가 아닌 my-object/ 객체(후행 슬래시 포함)에 대한 정보를 조회합니다. 실제로 이 이름을 가진 객체가 없으면 작업은 실패합니다.

하위 디렉터리 목록의 경우 gsutil ls를 대신 사용합니다.

gcloud auth

문제: gcloud auth 명령어를 사용하여 gsutil을 인증하려 했으나 여전히 버킷 또는 객체에 액세스할 수 없습니다.

해결 방법: 시스템에 독립형 및 Cloud SDK 버전의 gsutil이 모두 설치되었을 수 있습니다. gsutil version -l 명령어를 실행하고 using cloud sdk 값을 확인합니다. False이면 명령어를 실행할 때 시스템이 독립형 버전의 gsutil을 사용한다는 의미입니다. 이 버전의 gsutil을 시스템에서 삭제하거나 gsutil config 명령어를 사용하여 인증할 수 있습니다.

정적 웹사이트 오류

다음은 정적 웹사이트를 호스팅할 버킷을 설정할 때 일반적으로 발생하는 문제입니다.

HTTPS 제공

문제: 부하 분산기를 사용하지 않고 HTTPS를 통해 콘텐츠를 제공하고 싶습니다.

해결 방법: https://storage.googleapis.com/my-bucket/my-object와 같은 직접 URI를 사용하여 HTTPS를 통해 정적 콘텐츠를 제공할 수 있습니다. SSL을 통해 커스텀 도메인으로 콘텐츠를 제공하는 다른 옵션은 다음과 같습니다.

도메인 확인

문제: 내 도메인을 인증할 수 없습니다.

해결 방법: 일반적으로 Search Console의 확인 프로세스에서는 파일을 도메인에 업로드하도록 지시하지만 도메인 확인을 수행한 후에만 만들 수 있는 관련 버킷이 없어 이 작업을 수행하지 못할 수 있습니다.

이러한 경우 도메인 이름 공급업체 인증 방법을 사용하여 소유권을 인증하세요. 이 작업을 수행하는 방법은 소유권 인증을 참조하세요. 버킷을 만들기 전에 이 인증을 수행할 수 있습니다.

액세스 불가 페이지

문제: 웹사이트에서 제공하는 웹페이지에 Access denied 오류 메시지가 표시됩니다.

해결 방법: 객체가 공개로 공유되는지 확인하세요. 그렇지 않은 경우 데이터 공개 설정을 참조하세요.

이전에 객체를 업로드하고 공유했지만 이후에 새 버전을 업로드하면 객체를 다시 공개적으로 공유해야 합니다. 공개 권한이 새 업로드로 대체되기 때문입니다.

권한을 업데이트하지 못함

문제: 데이터를 공개로 설정하려고 하면 오류가 발생합니다.

해결 방법: 객체 또는 버킷에 대한 setIamPolicy 권한이 있는지 확인하세요. 예를 들어 해당 권한은 Storage Admin 역할에서 부여됩니다. setIamPolicy 권한이 있는데도 오류가 발생하면 버킷에 공개 액세스 방지가 적용되어 allUsers 또는 allAuthenticatedUsers에 대한 액세스가 허용되지 않을 수 있습니다. 공개 액세스 방지는 버킷에 직접 설정되거나 더 높은 수준에서 설정된 조직 정책을 통해 적용될 수 있습니다.

콘텐츠 다운로드

문제: 내 페이지의 콘텐츠를 브라우저에서 보는게 아니라 다운로드하라는 메시지가 표시됩니다.

해결 방법: MainPageSuffix를 웹 콘텐츠 유형이 아닌 객체로 지정하면 페이지를 제공하는 대신 사이트 방문자에게 콘텐츠를 다운로드하라는 메시지가 표시됩니다. 이 문제를 해결하려면 content-type 메타데이터 항목을 적절한 값(예: text/html)으로 업데이트하세요. 이 작업을 수행하는 지침은 객체 메타데이터 수정을 참조하세요.

지연 시간

다음은 일반적으로 발생하는 지연 시간 문제입니다. 또한 Google Cloud 상태 대시보드는 Cloud Storage와 같이 Google Cloud 서비스에 영향을 미치는 리전 또는 전역 이슈에 대한 정보를 제공합니다.

업로드 또는 다운로드 지연 시간

문제: 업로드 또는 다운로드할 때 지연 시간이 길어집니다.

해결 방법: gsutil perfdiag 명령어를 사용하여 영향을 받는 환경에서 성능 진단을 실행합니다. 업로드 및 다운로드 지연 시간의 일반적인 원인은 다음과 같습니다.

  • CPU 또는 메모리 제약조건: 영향을 받는 환경의 운영체제에는 CPU 사용량 및 메모리 사용량과 같은 로컬 리소스 소비를 측정하는 도구가 있어야 합니다.

  • 디스크 IO 제약조건: gsutil perfdiag 명령어의 일부로 rthru_filewthru_file 테스트를 사용하여 로컬 디스크 IO로 인한 성능 영향을 측정합니다.

  • 지리적 거리: 성능은 Cloud Storage 버킷과 영향을 받는 환경의 물리적 분리의 영향을 받을 수 있으며 대륙 간 사례에서 특히 그렇습니다. 영향을 받는 환경과 동일한 리전에 있는 버킷으로 테스트하면 지리적 분리로 인해 지연 시간에 영향을 주는 정도를 파악할 수 있습니다.

    • 해당하는 경우 영향을 받는 환경의 DNS 리졸버는 환경의 요청이 적절한 Google 프런트엔드를 통해 라우팅되도록 EDNS(0) 프로토콜을 사용해야 합니다.

gsutil 또는 클라이언트 라이브러리 지연 시간

문제: gsutil 또는 클라이언트 라이브러리 중 하나로 Cloud Storage에 액세스할 때 지연 시간이 길어집니다.

해결 방법: gsutil 및 클라이언트 라이브러리 모두 유용한 경우 요청을 자동으로 재시도하며, 이 동작은 최종 사용자에게 표시되는 지연 시간을 크게 늘릴 수 있습니다. Cloud Monitoring 측정항목 storage.googleapis.com/api/request_count를 사용하여 Cloud Storage가 429 또는 5xx와 같이 재시도 가능한 응답 코드를 일관되게 제공하는지 확인합니다.

프록시 서버

문제: 프록시 서버를 통해 연결 중입니다. 무엇을 해야 하나요?

해결 방법: 프록시 서버를 통해 Cloud Storage에 액세스하려면 다음 도메인에 대한 액세스를 허용해야 합니다.

  • accounts.google.com: gsutil config를 통해 OAuth2 인증 토큰 생성
  • oauth2.googleapis.com: OAuth2 토큰 교환 수행
  • *.googleapis.com: 저장 요청

프록시 서버 또는 보안 정책이 도메인별 허용 목록을 지원하지 않고 대신 IP 네트워크 블록별 허용 목록이 필요한 경우 모든 Google IP 주소 범위에 대해 프록시 서버를 구성하는 것이 좋습니다. ARIN에서 WHOIS 데이터를 쿼리하여 주소 범위를 찾을 수 있습니다. 프록시 설정이 Google의 IP 주소와 일치하는지 정기적으로 검토하는 것이 좋습니다.

oauth2.googleapis.comstorage.googleapis.com의 일회성 조회를 기반으로 얻은 개별 IP 주소로 프록시를 구성하지 않는 것이 좋습니다. Google 서비스는 시시각각 변하는 매우 많은 IP 주소에 매핑되는 DNS 이름을 통해 노출되기 때문에 한 번의 조회를 기반으로 프록시를 구성하면 Cloud Storage에 연결하지 못할 수 있습니다.

프록시 서버를 통해 요청이 라우팅되는 경우, 네트워크 관리자의 도움을 받아 사용자 인증 정보를 포함한 Authorization 헤더가 프록시에서 삭제되지 않았는지 확인해야 합니다. Authorization 헤더가 없으면 요청이 거부되고 MissingSecurityHeader 오류가 발생합니다.

다음 단계