通过

排查 AzCopy v10 中的问题

  • 项目

本文介绍使用 AzCopy 时可能会遇到的常见问题。 本文还有助于确定问题的原因，并建议如何解决这些问题。

识别问题

可以通过查看退出代码来确定作业是否成功。

如果退出代码为 0-success，则作业成功完成。

如果退出代码为 1-error，请检查日志文件。 了解确切的错误消息后，可以更轻松地搜索正确的关键字并确定解决方案。 若要了解详细信息，请参阅 使用 AzCopy 中的日志和计划文件查找错误和恢复作业。

如果退出代码为 2-panic，检查日志文件是否存在。 如果文件不存在，请提交 bug 或联系支持人员。

系统可能会生成任何其他非零退出代码 (，例如 OOMKilled) 。 请查看操作系统文档，了解特殊的退出代码。

“403”错误

“403”错误很常见。 有时它们是良性的，不会导致传输失败。 例如，在 AzCopy 日志中，你可能会看到请求 HEAD 收到“403”错误。 当 AzCopy 检查资源是否为公共资源时，会出现这些错误。 在大多数情况下，可以忽略这些实例。

在某些情况下，“403”错误可能会导致传输失败。 如果出现此问题，则在解决问题之前，传输文件的其他尝试可能会失败。 “403”错误可能是由身份验证和授权问题引起的。 如果请求被存储帐户防火墙配置阻止，也可能发生这些事件。

身份验证和授权问题

由于涉及 SAS 令牌、基于角色的访问控制 (Azure RBAC) 角色以及访问控制列表 (ACL) 配置的问题，导致发生阻止数据传输的“403”错误。

SAS 令牌

如果使用共享访问签名 (SAS) 令牌，请确保以下语句正确：

  • SAS 令牌的到期时间和开始时间是合适的。

  • 你为令牌选择了所有必要的权限。

  • 你使用官方 SDK 或工具生成了令牌。 如果尚未存储资源管理器，请尝试。

Azure RBAC

如果通过 azcopy login 命令使用 Azure RBAC 角色，请验证是否已将适当的 Azure 角色分配给标识 (例如存储 Blob 数据参与者角色) 。

若要详细了解 Azure 角色，请参阅 分配 Azure 角色以访问 Blob 数据。

Acl

如果使用访问控制列表 (ACL) ，请验证标识是否显示在要访问的每个文件或目录的 ACL 条目中。 此外，请确保每个 ACL 条目都反映了适当的权限级别。

若要详细了解 ACL 和 ACL 条目，请参阅访问控制列表 (Azure Data Lake Storage Gen2 中的 ACL) 。

若要详细了解如何将 Azure 角色与 ACL 合并在一起，以及系统如何评估这些角色以做出授权决策，请参阅 Azure Data Lake Storage Gen2 中的访问控制模型。

防火墙和专用终结点问题

如果存储防火墙配置不允许从运行 AzCopy 的托管组件进行访问，AzCopy 操作将返回 HTTP“403”错误代码。

注意

在本文中， 术语“承载组件 ”是指物理计算机、虚拟机 (VM) 或容器。

复制操作的允许范围

AllowedCopyScope存储帐户的 属性用于指定可从中将数据复制到目标帐户的环境。 此属性在Azure 门户显示为“允许的复制操作范围” (预览) 配置设置。 默认情况下，不会为 属性提供值。 在显式设置值之前，该属性不会返回值。 属性 AllowedCopyScope 有三个可能的值，如下表所示。

值 说明
(null) (默认值) 允许从任何存储帐户复制到目标帐户。
Microsoft Entra ID 仅允许从与目标帐户位于同一Microsoft Entra租户中的帐户进行复制。
PrivateLink 仅允许从具有与目标帐户相同的虚拟网络的专用链接的存储帐户进行复制。

有关此属性及其关联配置设置的详细信息，请参阅 将复制操作源限制为存储帐户。

将数据从本地托管组件传输或传输到本地托管组件

如果要在存储帐户和本地托管组件之间上传或下载数据，请确保运行 AzCopy 的托管组件可以访问源或目标存储帐户。 可能需要在源或目标帐户的防火墙设置中使用 IP 网络规则，以允许从托管组件的公共 IP 地址进行访问。

在存储帐户之间传输数据

“403”授权错误可能会阻止你通过使用运行 AzCopy 的客户端托管组件在帐户之间传输数据。

如果要在存储帐户之间复制数据，请确保运行 AzCopy 的托管组件可以访问源帐户和目标帐户。 可能需要在源和目标帐户的防火墙设置中使用 IP 网络规则，以允许从托管组件的公共 IP 地址进行访问。 该服务使用 AzCopy 客户端托管组件的 IP 地址来授权源到目标流量。 若要了解如何将公共 IP 地址添加到存储帐户的防火墙设置，请参阅 从 Internet IP 范围授予访问权限。

如果 VM 没有或不能具有公共 IP 地址，请考虑使用专用终结点。 请参阅 将专用终结点用于 Azure 存储。

专用链接位于虚拟网络/子网级别。 如果希望 AzCopy 请求通过专用链接，AzCopy 必须从该虚拟网络/子网中运行的 VM 发出这些请求。 例如，假设在 VNet1/Subnet1 中配置专用链接，但运行 AzCopy 的 VM 位于 VNet1/Subnet2 中。 在此方案中，AzCopy 请求不使用 专用链接，并且请求预期会失败。

如果遇到 TCP 错误，例如“dial tcp： lookup proxy.x.x： no such host”，这意味着你的环境未配置为使用正确的代理，或者你使用的是 AzCopy 无法识别的高级代理。

必须更新代理设置以反映正确的配置。 请参阅 配置代理设置。

还可以通过设置环境变量 NO_PROXY="*"来绕过代理。

下面是 AzCopy 所需的终结点：

登录终结点 Azure 存储终结点
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) 证书的代理的使用有关。 验证设置，并确保证书在操作系统级别受信任。

建议将证书添加到托管组件的根证书存储区，因为这是保存受信任颁发机构的位置。

无法识别的参数

如果收到一条错误消息，指出无法识别参数，请确保使用正确版本的 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 工具的托管组件也是你从中登录的位置。

如果你的设备在受支持的平台列表中，则你可能能够使用存储资源管理器。 存储资源管理器集成 AzCopy 用于所有数据传输， (它通过机密存储) 将令牌传递给 AzCopy，但提供了支持传递设备信息的登录工作流。 AzCopy 本身还支持托管标识和服务主体作为登录替代项。

如果你的设备不在受支持的平台列表中，请联系管理员寻求帮助。

服务器繁忙、网络错误或超时

如果看到大量处于“503 服务器繁忙”状态的失败请求，则存储服务正在限制你的请求。 如果看到网络错误或超时，则可能是尝试推送太多数据供基础结构处理。 在所有情况下，解决方法都类似。

如果看到由于某些区块每次失败而重复出现复制失败的情况，请尝试根据具体情况限制并发网络连接或吞吐量限制。 建议先大幅降低性能，观察此操作是否解决了初始问题，然后再次提高性能，直到达到整体平衡。

有关详细信息，请参阅 使用 Azure 存储优化 AzCopy 的性能。

如果使用 AzCopy 在帐户之间复制数据，则运行 AzCopy 的网络的质量和可靠性可能会影响整体性能。 即使数据从服务器传输到服务器，AzCopy 也会为每个文件发起调用，以便在服务终结点之间复制。

AzCopy 中的已知约束

  • 不支持将数据从政府云复制到商业云。 但是，支持将数据从商业云复制到政府云。

  • 不支持异步服务端复制。 AzCopy 仅执行同步复制。 换句话说，到作业完成时，数据已移动。

  • 复制到 Azure 文件共享时，如果忘记指定 --preserve-smb-permissions 标志，并且不想再次传输数据，请考虑使用 Robocopy 来引入权限。

  • Azure Functions具有用于 MSI 身份验证的不同终结点。 AzCopy 尚不支持 MSI 身份验证。

另请参阅

联系我们寻求帮助

如果你有任何疑问或需要帮助，请创建支持请求或联系 Azure 社区支持。 还可以向 Azure 反馈社区提交产品反馈。