通过

排查 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）令牌，请确保以下语句为 true：

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

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

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

Azure RBAC

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

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

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 此类主机”），这意味着环境未配置为使用正确的代理，或者使用 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 反馈社区。