跳到主要内容

资产缓存问题排查

资产缓存通过将下载的包（资产）存储在本地或网络中，加速包的获取过程，减少对外部源的依赖。本指南帮助用户解决资产缓存设置或运行过程中遇到的问题。

如需初始设置说明，请参考 资产缓存文档。

诊断资产缓存错误​

kmpkg 在从互联网下载制品前，会先检查可用的资产缓存。默认情况下，若缓存中未找到资产，会自动回退到外部源下载，过程无提示。

x-block-origin 选项可将资产恢复失败转化为明确的构建错误，防止意外的外部下载。使用该选项可增强安全性，并使缓存未命中的情况更易被发现。

检测资产恢复问题​

资产恢复问题默认无提示，可通过验证制品的下载 URL 来检测：

Downloading 7zip...
https://www.7-zip.org/a/7z2301-extra.7z -> C:\kmpkg\downloads\7z2301-extra.7z

或启用 x-block-origin 选项后，会出现明确错误：

error: Failed to download from mirror set

检测资产上传问题​

若资产源配置正确，当资产无法上传到缓存时，kmpkg 会输出警告：

warning: failed to store back to mirror

资产未从我的资产缓存上传或恢复​

kmpkg 提供的 x-azurl 资产缓存后端设计用于 Azure 存储容器，也可与其他支持“带简单令牌认证的 PUT 请求”的存储服务配合使用。

配置格式如下：

x-azurl,<url>,<sas>[,<rw>]

  • <url>: 容器的基础 URL
  • <sas>: 若使用 Azure 存储容器，为共享访问签名（SAS）令牌；若使用其他提供商，为认证请求参数
  • <rw>: （可选）读写权限配置（read/write/readwrite）
信息

x-azurl 后端虽设计用于 Azure 存储容器，但也可用于支持 <url>?<sas> 格式请求的存储服务。

示例：x-azurl,https://contoso.com,token=TOKEN_VALUE,readwrite 会生成请求 https://contoso.com?token=TOKEN_VALUE。

若资产缓存提供商无需授权，<sas> 参数可留空，例如：x-azurl,https://contoso.com,,readwrite。

原因 1：URL 格式不正确​

设置资产缓存时，确保 URL 包含 https:// 协议前缀。

解决步骤：

  1. 验证配置的 URL 是否正确。

原因 2：授权令牌格式不正确​

kmpkg 使用 <sas> 参数向资产缓存提供商认证，授权失败可能有多种原因：

  • 若使用 Azure 存储容器：

    • <sas> 参数应仅包含 SAS 令牌，无需其他请求参数格式。示例： x-azurl,https://mystorageaccount.blob.core.windows.net/mystoragecontainer,sasvaluehere,readwrite
    • 参考 SAS 令牌生成文档，确保令牌的读写权限与实际需求匹配。

  • 若使用其他提供商：

    • 可能需要正确格式化请求参数，例如在令牌值前添加参数名： x-azurl,https://contoso.com,authorization=tokenvaluehere,readwrite

解决步骤：

  1. 验证授权令牌是否已过期；
  2. 验证授权令牌对容器拥有正确的权限；
  3. 验证授权令牌的值是否正确；
  4. 验证授权令牌的格式是否符合提供商的要求。

出现“无法从镜像集下载”错误​

该错误在资产缓存配置中包含 x-block-origin 时出现。

x-block-origin 会将所有配置缓存的资产恢复失败转化为包构建失败，防止可能不需要的外部源访问。

解决步骤：

  1. 验证网络是否能访问资产源；
  2. 验证请求的资产是否存在于至少一个配置的资产缓存中。若不存在，有两种解决方法：
    • 临时禁用 x-block-origin，允许 kmpkg 下载资产并上传到配置的缓存中；
    • 手动将资产上传到其中一个配置的资产缓存中；
  3. 验证资产缓存配置是否正确，可参考 资产未从我的资产缓存上传或恢复 中的步骤。

问题未列出？​

若你的问题未在本文中列出，请访问 我们的仓库 创建新问题。