通过

ACR 传输故障排除

本文提供有关 ACR 传输常见问题的故障排除指南。 如果尚未完成先决条件，请参阅 ACR 传输先决条件。

重要

ACR 传输由于技术限制支持层大小高达 8 GB 的工件。 如果传输失败，请验证所有工件层是否在这个大小限制的范围内。

模板部署故障或错误

  • 如果管道运行失败，请查看运行资源的 pipelineRunErrorMessage 属性。
  • 有关常见模板部署错误，请参阅 ARM 模板部署疑难解答。

访问Key Vault时出现问题

注释

Key Vault访问问题仅在使用 SAS 令牌存储访问模式时适用。 如果使用 Managed Identity 存储访问模式，则存储帐户访问不需要Key Vault。

  • 如果 PipelineRun 部署在访问Azure Key Vault时失败，并出现 403 Forbidden 错误，请验证管道托管标识是否具有足够的权限。
  • PipelineRun 使用 ExportPipeline 或 ImportPipeline 托管标识从 Key Vault 中提取 SAS 令牌的机密。 ExportPipelines 和 ImportPipelines 可以通过系统分配的托管标识或用户分配的托管标识来进行预配。 若要读取 SAS 令牌机密，此托管标识需要对 Key Vault 拥有 secret get 权限。 确保已将托管标识的访问策略添加到Key Vault。 有关详细信息，请参阅 授予导出管道标识的 Key Vault 策略访问 和 授予导入管道标识的 Key Vault 策略访问。

访问存储时遇到的问题

SAS 令牌存储访问模式

  • 如果存储中显示 403 Forbidden 错误，则 SAS 令牌可能存在问题。
  • SAS 令牌当前可能无效。 SAS 令牌可能已到期，或者创建 SAS 令牌后存储帐户密钥可能已更改。 通过尝试使用 SAS 令牌对对存储帐户容器的访问进行身份验证，验证 SAS 令牌是否有效。 例如，在新的 Microsoft Edge InPrivate 窗口的地址栏中放置一个现有 Blob 终结点，然后使用 az storage blob upload 将 BLOB 上传到具有 SAS 令牌的容器。
  • SAS 令牌可能没有足够的被允许的资源类型。 验证 SAS 令牌是否有权访问允许的资源类型（SAS 令牌中的 srt=sco）下的服务、容器和对象。
  • SAS 令牌可能没有足够的权限。 对于导出管道，所需的 SAS 令牌权限为读取、写入、列出和添加。 对于导入管道，所需的 SAS 令牌权限为读取、删除和列出。 （仅在导入管道启用了 DeleteSourceBlobOnSuccess 选项时才需要“删除”权限。）
  • SAS 令牌可能未配置为仅使用 HTTPS。 验证 SAS 令牌是否配置为仅使用 HTTPS（SAS 令牌中的 spr=https）。

托管身份存储访问模式

  • 如果在使用托管身份模式时出现 403 Forbidden 存储错误，请核实管道的托管身份是否在存储帐户上被分配了适当的 RBAC 角色（例如 Storage Blob Data Contributor）。
  • 如果使用 系统分配的 托管标识，请确保在管道资源上启用标识，并为管道的系统分配标识主体 ID 创建 RBAC 角色分配。
  • 如果使用 用户分配的 托管标识，请确保在创建管道期间提供正确的标识资源 ID，并为用户分配的标识创建 RBAC 角色分配。
  • 验证你使用的是 API 版本 2025-06-01-preview 或更高版本。 托管标识存储访问模式在早期 API 版本中不可用。
  • 使用托管标识模式时，keyVaultUri 管道响应中的字段可能显示为 null 或为空字符串，这是预期行为，而不是错误。
  • 使用用户分配的托管标识时，管道标识响应的顶级 principalId 和 tenantId 可能会显示为 null。 实际的标识详细信息位于 userAssignedIdentities 部分内。 这是预期的行为。

导出或导入存储 blob 时出现问题

  • SAS 令牌可能无效，或者可能没有足够的权限来运行指定的导出或导入。 请参阅访问存储时遇到的问题。
  • 如果使用 托管标识 存储访问模式，请验证托管标识对存储帐户具有足够的 RBAC 权限（例如 Storage Blob Data Contributor）。
  • 在多次导出操作期间，来源存储帐户中的已有存储 blob 可能不会被覆盖。 确认在导出运行中设置了 OverwriteBlobs 选项，并且 SAS 令牌（或托管标识）具有足够的权限。
  • 导入成功后，目标存储帐户中的存储 blob 可能不会被删除。 确认在导入运行中设置了 DeleteSourceBlobOnSuccess 选项，并且 SAS 令牌（或托管标识）具有足够的权限。
  • 未创建或删除存储 blob。 请确认在导出或导入运行中指明的容器是否存在，或者用于手动导入运行的存储 blob 是否存在。

与源触发器导入有关的问题

  • 使用 SAS 令牌 存储访问模式时，SAS 令牌必须具有源触发器导入的“列表”权限才能正常工作。 使用 托管标识 模式时，托管标识必须在允许列出 Blob 的存储帐户上具有适当的 RBAC 角色。
  • 只有当存储 Blob 的上次修改时间在最近 60 天内，才会触发源触发器导入。
  • 存储 Blob 必须具有有效的 ContentMD5 属性，才能通过源触发器功能导入。
  • 存储 Blob 必须具有 "category":"acr-transfer-blob" blob 元数据才能由源触发器功能导入。 此元数据在导出管道运行期间自动添加，但在存储帐户之间移动时可能会被剥离，具体取决于复制方法。

AzCopy问题

工件传递问题

  • 并未传输所有项目或者根本未传输任何项目。 确认导出运行中的构件拼写，以及导出和导入运行中的 blob 名称。 确认最多传输 50 个项目。
  • 管道的运行可能尚未完成。 导出或导入运行可能需要一些时间。
  • 对于其他管道问题，请向 Azure 容器注册表团队提供导出或导入运行的部署 correlation ID。
  • 若要创建 ACR 传输资源（如 ExportPipelines、ImportPipelines 和 PipelineRuns），用户必须至少 Container Registry Transfer Pipeline Contributor 对 ACR 订阅具有访问权限。 否则，他们将看到执行传输的授权被拒绝或范围无效错误。

在物理隔离环境中拉取镜像时遇到的问题

  • 如果在尝试在物理隔离的环境中拉取映像时看到有关外部层的错误或尝试解析 mcr.microsoft.com，那么映像清单可能具有不可分发的层。 由于物理隔离环境的性质，这些映像通常无法下载。 可以通过检查映像清单中是否存在对外部注册表的任何引用，来确认是这种情况。 如果是这样，您需要在为该映像部署导出管道运行任务之前，将不可分发层推送到公有云 ACR。 有关如何执行此作的指导，请参阅 如何将非可归因层推送到注册表？。

存储访问模式警告

  • 如果看到有关参数的 --storage-access-mode CLI 警告消息，请显式指定 --storage-access-mode SasToken 使用 SAS 令牌身份验证，或使用 --storage-access-mode ManagedIdentity 托管标识身份验证进行存储访问。 创建管道时始终指定此参数。
  • CLI 扩展的重大变更遵循 5 月和 11 月 时间表。 从技术上讲，扩展可以在此计划之外引入重大变更，但 ACR 传输团队遵循 5 月/11 月的计划。
  • Last updated on