다음을 통해 공유

AzCopy v10의 문제 해결

  • 아티클

이 문서에서는 AzCopy를 사용할 때 발생할 수 있는 일반적인 문제에 대해 설명합니다. 또한 이 문서는 문제의 원인을 파악하는 데 도움이 되며 문제를 해결하는 방법을 제안합니다.

문제 식별

종료 코드를 보고 작업의 성공 여부를 확인할 수 있습니다.

종료 코드인 0-success경우 작업이 성공적으로 완료되었습니다.

종료 코드인 1-error경우 로그 파일을 검사합니다. 정확한 오류 메시지를 이해한 후에는 올바른 키워드를 더 쉽게 검색하고 솔루션을 확인할 수 있습니다. 자세한 내용은 AzCopy에서 로그 및 계획 파일을 사용하여 오류 찾기 및 작업 다시 시작를 참조하세요.

종료 코드인 2-panic경우 로그 파일이 있는지 확인합니다. 파일이 없으면 버그를 신고하거나 지원팀에 문의합니다.

다른 0이 아닌 종료 코드(예: OOMKilled)는 시스템에서 생성될 수 있습니다. 운영 체제 설명서에서 특별한 종료 코드를 확인합니다.

"403" 오류

"403" 오류는 일반적입니다. 때로는 양성이며 실패한 전송을 일으키지 않습니다. 예를 들어 AzCopy 로그에서 요청이 "403" 오류를 수신한 것을 HEAD 볼 수 있습니다. 이러한 오류는 AzCopy가 리소스가 공용인지 확인할 때 나타납니다. 대부분의 경우 이러한 인스턴스를 무시할 수 있습니다.

경우에 따라 "403" 오류로 인해 전송에 실패할 수 있습니다. 이 문제가 발생하면 문제를 해결할 때까지 파일을 전송하려는 다른 시도가 실패할 수 있습니다. "403" 오류는 인증 및 권한 부여 문제로 인해 발생할 수 있습니다. 스토리지 계정 방화벽 구성에 의해 요청이 차단되는 경우에도 발생할 수 있습니다.

인증 및 권한 부여 문제

SAS 토큰, Azure RBAC(역할 기반 액세스 제어) 역할 및 ACL(액세스 제어 목록) 구성과 관련된 문제로 인해 데이터 전송을 방지하는 "403" 오류가 발생합니다.

SAS 토큰

SAS(공유 액세스 서명) 토큰을 사용하는 경우 다음 문이 true인지 확인합니다.

  • SAS 토큰의 만료 및 시작 시간이 적절합니다.

  • 토큰에 필요한 모든 권한을 선택했습니다.

  • 공식 SDK 또는 도구를 사용하여 토큰을 생성했습니다. 아직 시도하지 않은 경우 Storage Explorer를 사용해 보세요.

Azure RBAC

명령을 통해 azcopy login Azure RBAC 역할을 사용하는 경우 ID에 할당된 적절한 Azure 역할(예: Storage Blob 데이터 기여자 역할)이 있는지 확인합니다.

Azure 역할에 대한 자세한 내용은 BLOB 데이터 액세스를 위한 Azure 역할 할당을 참조하세요.

ACL

ACL(액세스 제어 목록)을 사용하는 경우 액세스하려는 각 파일 또는 디렉터리에 대한 ACL 항목에 ID가 표시되는지 확인합니다. 또한 각 ACL 항목이 적절한 권한 수준을 반영하는지 확인합니다.

ACL 및 ACL 항목에 대한 자세한 내용은 Azure Data Lake Storage Gen2의 ACL(액세스 제어 목록)을 참조하세요.

Azure 역할과 ACL을 통합하는 방법 및 시스템에서 권한 부여 결정을 내리기 위해 이를 평가하는 방법에 대해 자세히 알아보려면 Azure Data Lake Storage Gen2의 액세스 제어 모델을 참조하세요.

방화벽 및 프라이빗 엔드포인트 문제

스토리지 방화벽 구성에서 AzCopy가 실행 중인 호스팅 구성 요소의 액세스를 허용하지 않는 경우 AzCopy 작업은 HTTP "403" 오류 코드를 반환합니다.

참고 항목

이 문서에서 호스팅 구성 요소라는 용어는 물리적 컴퓨터, VM(가상 머신) 또는 컨테이너를 나타냅니다.

복사 작업에 대해 허용된 범위

AllowedCopyScope 스토리지 계정의 속성은 대상 계정에 데이터를 복사할 수 있는 환경을 지정하는 데 사용됩니다. 이 속성은 복사 작업(미리 보기) 구성 설정의 허용 범위로 Azure Portal에 표시됩니다. 기본적으로 속성에는 값이 제공되지 않습니다. 속성은 명시적으로 설정할 때까지 값을 반환하지 않습니다. 속성 AllowedCopyScope 에는 다음 표와 같이 세 가지 가능한 값이 있습니다.

값 설명
(null) (기본값) 스토리지 계정에서 대상 계정으로 복사할 수 있습니다.
Microsoft Entra ID 대상 계정과 동일한 Microsoft Entra 테넌트 내에 있는 계정에서만 복사할 수 있습니다.
PrivateLink 대상 계정과 동일한 가상 네트워크에 대한 프라이빗 링크가 있는 스토리지 계정에서만 복사할 수 있습니다.

이 속성 및 관련 구성 설정에 대한 자세한 내용은 스토리지 계정으로 복사 작업의 원본 제한(Restrict of Copy Operations)을 참조 하세요.

로컬 호스팅 구성 요소에서 또는 로컬 호스팅 구성 요소로 데이터 전송

스토리지 계정과 온-프레미스 호스팅 구성 요소 간에 데이터를 업로드하거나 다운로드하는 경우 AzCopy를 실행하는 호스팅 구성 요소가 원본 또는 대상 스토리지 계정에 액세스할 수 있는지 확인합니다. 호스팅 구성 요소의 공용 IP 주소에서 액세스를 허용하려면 원본 또는 대상 계정의 방화벽 설정에서 IP 네트워크 규칙을 사용해야 할 수 있습니다.

스토리지 계정 간에 데이터 전송

"403" 권한 부여 오류로 인해 AzCopy가 실행 중인 클라이언트 호스팅 구성 요소를 사용하여 계정 간에 데이터를 전송하지 못할 수 있습니다.

스토리지 계정 간에 데이터를 복사하는 경우 AzCopy를 실행하는 호스팅 구성 요소가 원본 계정과 대상 계정 모두에 액세스할 수 있는지 확인합니다. 호스팅 구성 요소의 공용 IP 주소에서 액세스를 허용하려면 원본 및 대상 계정의 방화벽 설정에서 IP 네트워크 규칙을 사용해야 할 수 있습니다. 이 서비스는 AzCopy 클라이언트 호스팅 구성 요소의 IP 주소를 사용하여 원본에서 대상 트래픽에 권한을 부여합니다. 스토리지 계정의 방화벽 설정에 공용 IP 주소를 추가하는 방법을 알아보려면 인터넷 IP 범위에서 액세스 권한 부여를 참조하세요.

VM에 공용 IP 주소가 없거나 가질 수 없는 경우 프라이빗 엔드포인트를 사용하는 것이 좋습니다. Azure Storage에 프라이빗 엔드포인트 사용을 참조하세요.

Private Link 는 가상 네트워크/서브넷 수준에 있습니다. AzCopy 요청이 Private Link를 통과하도록 하려면 AzCopy가 해당 가상 네트워크/서브넷에서 실행되는 VM에서 해당 요청을 수행해야 합니다. 예를 들어 VNet1/Subnet1에서 Private Link를 구성하지만 AzCopy가 실행되는 VM은 VNet1/Subnet2에 있다고 가정합니다. 이 시나리오에서 AzCopy 요청은 Private Link를 사용하지 않으며 요청은 실패할 것으로 예상됩니다.

"dial tcp: lookup proxy.x.x: no such host"와 같은 TCP 오류가 발생하면 환경이 올바른 프록시를 사용하도록 구성되지 않았거나 AzCopy에서 인식하지 못하는 고급 프록시를 사용한다는 의미입니다.

올바른 구성을 반영하도록 프록시 설정을 업데이트해야 합니다. 프록시 설정 구성을 참조하세요.

환경 변수 NO_PROXY="*"를 설정하여 프록시를 무시할 수도 있습니다.

AzCopy에 필요한 엔드포인트는 다음과 같습니다.

로그인 엔드포인트 Azure Storage 엔드포인트
login.microsoftonline.com(글로벌 Azure) (blob | file | dfs).core.windows.net(글로벌 Azure)
login.chinacloudapi.cn (Azure 중국) (blob | file | dfs).core.chinacloudapi.cn (Azure 중국)
login.microsoftonline.de(Azure 독일) (blob | file | dfs).core.cloudapi.de(Azure 독일)
login.microsoftonline.us(Azure 미국 정부) (blob | file | dfs).core.usgovcloudapi.net(Azure 미국 정부)

x509: 알 수 없는 기관에서 서명한 인증서

이 오류는 종종 운영 체제에서 신뢰할 수 없는 SSL(Secure Sockets Layer) 인증서를 사용하는 프록시 사용과 관련이 있습니다. 설정을 확인하고 인증서가 운영 체제 수준에서 신뢰할 수 있는지 확인합니다.

신뢰할 수 있는 기관이 유지되는 위치이므로 호스팅 구성 요소의 루트 인증서 저장소에 인증서를 추가하는 것이 좋습니다.

인식할 수 없는 매개 변수

매개 변수가 인식되지 않는다는 오류 메시지가 표시되는 경우 올바른 버전의 AzCopy를 사용하고 있는지 확인합니다. AzCopy v8 및 이전 버전은 더 이상 사용되지 않습니다. AzCopy v10 은 현재 버전이며 이전 버전과 구문을 공유하지 않는 완전한 다시 쓰기입니다. v8에서 v10으로의 AzCopy 마이그레이션 가이드를 참조하세요.

또한 스위치를 명령과 함께 사용하여 기본 제공 도움말 메시지를 사용해야 -h 합니다(예 azcopy copy -h: ). 명령 도움말 보기를 참조하세요. 동일한 정보를 온라인으로 보려면 azcopy copy를 참조하세요.

명령을 이해하는 데 도움이 되도록 AzCopy 명령 가이드에 있는 교육 도구를 제공합니다. 이 도구는 가장 많이 사용되는 명령 플래그와 함께 가장 많이 사용되는 AzCopy 명령을 보여 줍니다. 예제 명령을 찾으려면 데이터 전송을 참조 하세요. 질문이 있는 경우 먼저 기존 GitHub 문제를 검색하여 이미 응답되었는지 확인합니다.

조건부 액세스 정책 오류

명령을 호출할 때 다음 오류가 표시될 수 있습니다.azcopy login

로그인 명령을 수행하지 못했습니다. tenantID "common", Azure 디렉터리 엔드포인트 "https://login.microsoftonline.com", autorest/adal/devicetoken: -REDACTED- AADSTS50005: 사용자가 조건부 액세스 정책을 통해 현재 지원되지 않는 플랫폼(알 수 없음)에서 디바이스에 로그인하려고 했습니다. 지원되는 디바이스 플랫폼은 iOS, Android, Mac 및 Windows 버전입니다. 추적 ID: -REDACTED- 상관 관계 ID: -REDACTED- 타임스탬프: 2021-01-05 01:58:28Z

이 오류는 관리자가 로그인할 수 있는 디바이스 종류를 지정하는 조건부 액세스 정책을 구성했음을 의미합니다. AzCopy는 디바이스 코드 흐름을 사용합니다. 디바이스 코드 흐름은 AzCopy 도구를 사용하는 호스팅 구성 요소가 로그인하는 위치임을 보장할 수 없습니다.

디바이스가 지원되는 플랫폼 목록 중 하나이면 Storage Explorer를 사용할 수 있습니다. Storage Explorer는 모든 데이터 전송에 대해 AzCopy를 통합하지만(비밀 저장소를 통해 AzCopy에 토큰을 전달) 디바이스 정보 전달을 지원하는 로그인 워크플로를 제공합니다. AzCopy 자체는 로그인 대안으로 관리 ID 및 서비스 주체도 지원합니다.

디바이스가 지원되는 플랫폼 목록에 없는 경우 관리자에게 도움을 요청하세요.

서버 사용 중, 네트워크 오류 또는 시간 제한

"503 서버 사용 중" 상태가 있는 많은 수의 실패한 요청이 표시되면 스토리지 서비스가 요청을 제한합니다. 네트워크 오류 또는 시간 초과가 표시되는 경우 인프라에서 처리할 너무 많은 데이터를 푸시하려고 할 수 있습니다. 모든 경우에 해결 방법은 비슷합니다.

매번 특정 청크가 실패하기 때문에 큰 파일이 반복적으로 복사되지 않는 경우 특정 사례에 따라 동시 네트워크 연결 또는 처리량 제한을 제한해 보세요. 처음에는 성능을 크게 낮추고, 이 작업이 초기 문제를 해결했는지 여부를 관찰한 다음, 전반적인 균형을 달성할 때까지 성능을 다시 높이는 것이 좋습니다.

자세한 내용은 Azure Storage로 AzCopy 성능 최적화를 참조하세요.

AzCopy를 사용하여 계정 간에 데이터를 복사하는 경우 AzCopy를 실행하는 네트워크의 품질과 안정성이 전체 성능에 영향을 줄 수 있습니다. 서버에서 서버로 데이터가 전송되더라도 AzCopy는 서비스 엔드포인트 간에 복사할 각 파일에 대한 호출을 시작합니다.

AzCopy의 알려진 제약 조건

  • 정부 클라우드에서 상용 클라우드로 데이터 복사는 지원되지 않습니다. 그러나 상용 클라우드에서 정부 클라우드로 데이터 복사는 지원됩니다.

  • 비동기 서비스 쪽 복사는 지원되지 않습니다. AzCopy는 동기 복사만 수행합니다. 즉, 작업이 완료될 때까지 데이터가 이동되었습니다.

  • Azure 파일 공유에 복사할 때 플래그를 지정 --preserve-smb-permissions 하는 것을 잊고 데이터를 다시 전송하지 않으려면 Robocopy를 사용하여 사용 권한을 가져오는 것이 좋습니다.

  • Azure Functions에는 MSI 인증을 위한 다른 엔드포인트가 있습니다. AzCopy는 아직 MSI 인증을 지원하지 않습니다.

참고 항목

도움을 요청하십시오.

질문이 있거나 도움이 필요한 경우 지원 요청을 생성하거나Azure 커뮤니티 지원에 문의하세요. Azure 피드백 커뮤니티에 제품 피드백을 제출할 수도 있습니다.