使用 Azure DevOps 和 kmpkg 测试自定义注册表端口

当你搭建好自定义 kmpkg 端口注册表后，可能需要添加持续集成（CI） 功能，以验证所有依赖项能否成功构建。

kmpkg 官方主注册表 kumose/kmpkg 由 kmpkg 团队通过 Azure DevOps 的 CI 流水线进行测试，确保新增或更新包不会影响使用者。

本文将演示如何为你自己的注册表设置 CI 环境，用于测试其中的 kmpkg 端口。

通过本文，你将学会：

为 Azure DevOps 流水线配置二进制缓存和资产缓存

搭建测试注册表端口的流水线

前提条件

拥有 Azure DevOps 账号
已创建自己的 kmpkg Git 注册表
已完成二进制缓存和资产缓存教程
具备 Azure DevOps 流水线相关知识

为 Azure DevOps 流水线配置二进制缓存和资产缓存

构建大量端口会消耗大量时间和计算资源。因此，在为端口配置 CI 之前，强烈建议为 Azure DevOps 流水线设置二进制缓存和资产缓存：

二进制缓存：CI 场景中收益最大，可确保未修改的包不会在每次 CI 运行时重复构建；
资产缓存：会镜像构建过程中下载的包制品，并在后续运行中复用缓存的制品，还能缓解上游仓库不可靠的问题（例如下载 URL 失效）。

如需详细的缓存配置步骤，请参考：

示例：在 Azure DevOps 流水线中启用资产缓存和二进制缓存

steps: 
- task: NuGetAuthenticate@1  # NuGet 认证任务（用于访问私有 NuGet 源）

- script: $(Build.Repository.LocalPath)/kmpkg/kmpkg install --triplet=x64-windows
  displayName: 执行 kmpkg 安装任务
  env:
    # 配置资产缓存：使用 Azure 存储容器作为后端
    X_KMPKG_ASSET_SOURCES: "clear;x-azurl,https://my.domain.com/container,$(KmpkgAssetCache),readwrite"
    # 配置二进制缓存：使用 NuGet 源作为后端
    KMPKG_BINARY_SOURCES: "clear;nuget,https://my.domain.com/kmpkgBinaryCache/nuget/v3/index.json,readwrite"

配置说明：

X_KMPKG_ASSET_SOURCES（资产缓存环境变量）：
- 格式：x-azurl,<存储容器URL>,<SAS令牌>,<权限>
- x-azurl：指定使用 Azure 存储容器作为资产缓存后端；
- https://my.domain.com/container：Azure 存储容器的 URL；
- $(KmpkgAssetCache)：流水线机密变量，存储访问存储容器的 SAS 令牌；
- readwrite：权限设置（支持读写，即缓存制品和复用缓存）。
KMPKG_BINARY_SOURCES（二进制缓存环境变量）：
- 格式：clear;nuget,<NuGet源URL>,<权限>
- clear：清空默认缓存配置，仅使用当前配置；
- nuget：指定使用 NuGet 源作为二进制缓存后端；
- https://my.domain.com/kmpkgBinaryCache/nuget/v3/index.json：私有 NuGet 源的 URL；
- readwrite：权限设置（支持读写，即上传构建产物和下载缓存产物）。
必需前置任务：
- NuGetAuthenticate@1：用于认证 Azure Artifacts 或私有 NuGet 源，必须在所有 kmpkg 任务之前执行；
- 若使用非 Azure 托管的 NuGet 源，请参考 NuGet 认证配置。

更多缓存相关细节，请参考：

搭建测试注册表端口的流水线

完成缓存配置后，下一步是搭建流水线，用于测试注册表中的所有端口。你可以配置流水线触发方式：

定时触发
提交/合并请求触发

注意：kmpkg 官方注册表使用的 kmpkg ci 命令是为官方需求定制的，稳定性和通用性未针对第三方用户优化，不建议用于自定义注册表测试，请遵循本文下方的步骤实现。

步骤 1：使用清单文件管理所有端口

建议通过 清单文件 创建一个依赖于注册表中所有包的构建任务，而非使用 kmpkg ci 命令。

示例 1：创建 `kmpkg.json` 清单文件

在注册表仓库根目录创建 kmpkg.json，列出所有需要测试的端口（替换为你的实际端口名称）：

{
  "dependencies": [
    "beicode",
    "beison"
  ]
}

示例 2：创建 `kmpkg-configuration.json` 配置文件

若你的端口依赖官方注册表或第三方注册表，需在 kmpkg-configuration.json 中显式声明这些注册表（即使依赖官方注册表，也建议显式添加以确保版本可控）。

{
  "default-registry": null,
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/kumose/kmpkg",  // 官方注册表地址
      "baseline": "42bb0d9e8d4cf33485afb9ee2229150f79f61a1f",  // 官方注册表基线提交哈希
      "packages": "*"  // 匹配所有包
    }
  ]
}

可通过 kmpkg x-update-baseline 命令管理注册表基线；
更多配置细节，请参考：

步骤 2：运行 `kmpkg install` 构建端口

关键配置：使用覆盖端口（Overlay Ports）

由于需要测试工作目录中当前版本的端口（而非注册表中已发布的版本），需通过 KMPKG_OVERLAY_PORTS 环境变量将注册表的 ports 目录设置为覆盖端口（覆盖端口优先级高于注册表端口）。

流水线任务配置示例

steps:
- script: $(Build.Repository.LocalPath)/kmpkg/kmpkg install
  env:
    # 资产缓存配置（与前文一致）
    X_KMPKG_ASSET_SOURCES: "clear;x-azurl,https://my.domain.com/container,$(KmpkgAssetCache),readwrite"
    # 二进制缓存配置（与前文一致）
    KMPKG_BINARY_SOURCES: "clear;nuget,https://my.domain.com/demoBinaries/nuget/v3/index.json,readwrite"
    # 配置覆盖端口：指向当前仓库的 ports 目录
    KMPKG_OVERLAY_PORTS: "$(Build.Repository.LocalPath)/ports"

完整流水线 YAML 示例

trigger:
- main  # 触发分支：main（可改为其他分支或PR触发）

pool:
  vmImage: windows-latest  # 构建代理镜像（Windows最新版）

steps:
- checkout: self
  submodules: true  # 启用子模块（若kmpkg作为子模块引入）

- task: NuGetAuthenticate@1  # NuGet 认证（前置必需）

- script: $(Build.Repository.LocalPath)/kmpkg/bootstrap-kmpkg.bat
  displayName: 引导安装 kmpkg（执行kmpkg初始化脚本）

- script: $(Build.Repository.LocalPath)/kmpkg/kmpkg install --triplet=x64-windows
  displayName: 安装所有自定义端口（测试构建）
  env:
    X_KMPKG_ASSET_SOURCES: "clear;x-azurl,https://my.domain.com/container,$(KmpkgAssetCache),readwrite"
    KMPKG_BINARY_SOURCES: "clear;nuget,https://my.domain.com/demoBinaries/nuget/v3/index.json,readwrite"
    KMPKG_OVERLAY_PORTS: "$(Build.Repository.LocalPath)/ports"

补充说明

认证配置：
- 若端口依赖私有 Git 仓库，需参考私有 Git 注册表认证；
- 若使用私有 NuGet 源，需参考 NuGet 凭据配置。
进阶优化：
- 可添加自动生成 kmpkg.json 的步骤（避免新增端口遗漏测试）；
- 可添加端口完整性校验步骤（例如检查新端口是否已添加到清单文件）；
- 可扩展多三元组测试（如 x86-windows、x64-linux 等）。

后续步骤

以下文档可帮助你完善 CI 环境配置：

前提条件​

为 Azure DevOps 流水线配置二进制缓存和资产缓存​

示例：在 Azure DevOps 流水线中启用资产缓存和二进制缓存​

配置说明：​

搭建测试注册表端口的流水线​

步骤 1：使用清单文件管理所有端口​

示例 1：创建 kmpkg.json 清单文件​

示例 2：创建 kmpkg-configuration.json 配置文件​

步骤 2：运行 kmpkg install 构建端口​

关键配置：使用覆盖端口（Overlay Ports）​

流水线任务配置示例​

完整流水线 YAML 示例​

补充说明​

后续步骤​