上游源

Azure DevOps Services |Azure DevOps Server 2022 - Azure DevOps Server 2019 |TFS 2018

上游源使你能够使用单个源来存储来自不同源的包:发布的包,以及从源和公共注册表(如 NuGet.org、npmjs.com、Maven Central 和 PyPI)使用的包。 启用上游源后,连接到源的任何用户都可以从上游安装包,副本将保存到源。

注意

仅 npm 包支持自定义上游源。

优势

上游源使你能够在单个源中管理产品的所有依赖项。 将所有包发布到单个源有几个好处:

  • 简单性: 配置文件(如 NuGet.config、.npmrc 或 settings.xml)仅包含一个源,因此不容易出错和 bug。
  • 确定性: 源按顺序解析包请求,因此重新生成代码将更加一致。
  • 来源: 源知道它从上游源保存的包的来源,因此你可以验证你使用的是原始包,而不是副本或恶意包。
  • 安心: 对于从上游源安装的任何包,副本将保存到源中。 因此,如果禁用、删除上游源或正在进行维护,仍可以继续开发和生成,因为源中有该包的副本。

最佳做法 - 包使用者

若要充分利用上游源作为包使用者的优势,请遵循以下最佳做法:

在配置文件中使用单个源

为了使源提供 确定性还原,请务必确保配置文件(如 nuget.config 或 .npmrc)仅引用启用了上游源的一个源。

示例:

  • nuget.config

    <packageSources>
      <clear />
      <add key="FabrikamFiber" value="https://pkgs.dev.azure.com/fabrikam/_packaging/FabrikamFiber/nuget/v3/index.json" />
    </packageSources>
    

    注意

    NuGet 会编写多个 配置文件 ,以确定要使用的完整选项集。 使用 <clear /> 允许我们忽略在更高级别的配置文件中定义的所有其他包源。

  • .npmrc

    registry=https://pkgs.dev.azure.com/fabrikam/_packaging/FabrikamFiber/npm/registry/
    always-auth=true
    

有意订购上游源

如果仅使用公共注册表(如 nuget.org 或 npmjs.com),则上游源的顺序无关紧要。 对源的请求将遵循 搜索顺序

如果使用多个源(例如源和公共注册表的混合),则会按源的配置设置中列出的顺序搜索每个上游。 在这种情况下,我们建议将公共注册表放在上游源列表中。

在极少数情况下,某些组织会选择修改 OSS 包来修复安全问题、添加功能或满足内部从头开始构建包的要求,而不是直接从公共存储库使用。 如果组织遵循此模式,请将包含这些已修改的 OSS 包的上游源置于公共包管理器之前,以确保使用组织的修改版本。

使用建议的默认视图

将远程源添加为上游源时,必须选择其源的视图。 这使上游源能够构造一组可用的包。 有关更多详细信息 ,请参阅完整的包图

最佳做法:源所有者/包发布者

注意

公共源不支持上游源。

若要确保源易于配置为上游源,请考虑应用以下最佳做法:

使用默认视图

@local 视图是所有新创建的源的默认视图。 它包含发布到源或从上游源保存的所有包。

如果要使用视图来发布新的包版本,可以将包提升为等 @release 视图,并使其可供使用者使用。

构造包图

若要构造包图,只需连接到源的默认视图并安装要共享的包。 在默认视图中正确安装包后,想要使用它的用户将能够解析包图并安装所需的包。 来自上游源的包根据相应上游源的配置视图显示。

搜索顺序

对于支持多个源 (NuGet 和 Maven) 的公共包管理器,查询源的顺序有时不明确或不确定。 例如,在 NuGet 中,对配置文件中的所有源进行并行查询,并先行先出 FIFO 处理响应。

上游源使用以下顺序搜索源及其上游源,从而防止这种非确定性行为:

  1. 推送到源的包。

  2. 从上游源保存的包。

  3. 来自上游源的包:按源配置中列出的顺序搜索每个上游

若要充分利用快速查找功能,建议在配置文件中仅包含一个源。

注意

不支持使用 NuGet 包资源管理器在上游中搜索包。

从上游源保存包

为源启用上游源时,从上游源安装的包将自动保存到源中。 这些包可以直接从上游安装,如下所示 npm install express ,也可以作为依赖项解析的一部分进行安装, (安装 express 也会保存依赖项,例如 accepts) 。

保存包可以提高下载性能并节省网络带宽,尤其是对于内部网络中 TFS 服务器而言。

替代来自上游源的包

启用上游源时,必须知道无法发布上游中已存在的包版本。 例如,启用上游 NuGet.org 时,无法发布包 Newtonsoft.Json 10.0.3 ,因为 NuGet.org 已经存在相同的包版本。

如果必须发布某个上游源上已存在的包版本,则必须禁用该上游源,发布包,然后重新启用上游源。

注意

包版本是不可变的。 即使禁用或删除上游源,保存的包仍保留在源中。

运行状况

如果源的上游源发生故障,则无法再为同一协议的包刷新元数据。 若要查看上游源的运行状况,请选择齿轮图标 齿轮图标 以访问 源设置,然后选择“ 上游源”。

显示上游源故障状态的屏幕截图。

如果有任何失败,将显示一条警告消息。 选择失败状态将提供更多详细信息,例如失败的原因以及如何解决故障的说明。

显示同步失败详细信息的屏幕截图。

注意

对于公共注册表(如 NuGet.org),在将包推送到公共注册表和可供下载之间有 3-6 小时的延迟。 此延迟取决于作业计时和数据传播。 当上游源是 Azure Artifacts 源时,延迟通常不超过几分钟。

脱机上游源

上游源是保护使用者和基础结构免受计划外中断的好方法。 从上游源安装包时,该包的副本将保存到源中。 如果上游源已关闭、正在进行维护或不可用,你仍然可以从源访问所需的包。

常见问题解答

问:即使可以在源的上游之一中看到它,我也无法找到我的包?

答:属于上游的包在发布后不久即可在下游使用。 但是,包只有在引入源后才会显示在源的 UI 中,这需要首次在下游源中安装包版本。

问:什么是源视图?

答:通过视图,开发人员只能共享已经过测试和验证的包版本的子集,并排除仍在开发中和/或不符合质量栏的任何包。 有关更多详细信息 ,请参阅什么是源视图

问:找不到要配置为上游源的源?

答:确保源的所有者将视图共享为上游源。

问:具有 读取者 角色的用户是否可以从上游源下载包?

答:否。 在 Azure Artifacts 源中具有 读取者 角色的用户只能下载已保存到源的包。 当 协作者参与者所有者 从上游安装这些包时,包将保存到源中。

问:当用户删除或取消发布从上游源保存的包时,会发生什么情况?

答:包将不能从源下载,版本号将永久保留。 该包也将不再从上游源保存。 包的早期版本和更高版本不受影响。

问:当用户弃用从上游源保存的包时会发生什么情况?

答:每当从源查看或安装包时,都会将警告消息添加到包的元数据中并显示。