Azure Pipelines agents（Azure Pipelines 代理）

Azure DevOps Services |Azure DevOps Server |Azure DevOps Server 2022

至少需要一个代理才能使用 Azure Pipelines 生成代码或部署软件。随着代码库和团队的增长，需要多个代理。

管道运行时，系统会开始运行一个或多个作业。代理是计算基础结构，带有已安装的代理软件，一次运行一个作业。

Azure Pipelines 提供了多种不同类型的代理。

代理类型	说明	可用性
Microsoft 托管代理	由Microsoft托管和管理的代理。	Azure DevOps Services
自托管代理	你配置和管理的代理，托管在您的虚拟机（VM）上。	Azure DevOps Services、Azure DevOps Server
托管 DevOps 池代理	托管 DevOps 池是一项完全托管的服务。为代理提供支持的虚拟机或容器位于Microsoft Azure 订阅中，而不是在你自己的 Azure 订阅中。	Azure DevOps Services
Azure 虚拟机规模集代理	一种使用 Azure 虚拟机规模集的自承载代理，可自动缩放以满足需求。如果您正在考虑使用可自动缩放的自承载代理池，我们建议您考虑使用“托管 DevOps 池”。有关详细信息，请参阅比较托管 DevOps 池与 Azure 虚拟机规模集代理和托管 DevOps 池概述。	Azure DevOps Services

可以直接在代理的主机或容器中运行作业。

Microsoft 托管代理

如果管道位于 Azure Pipelines 中，则可以使用 Microsoft托管代理方便地运行作业。使用Microsoft托管代理时，会自动进行维护和升级。

始终保持管道中指定的 VM 映像的最新版本。每次运行管道时，都会为管道中的每个作业获取一个全新的虚拟机。虚拟机在执行完一个作业后被丢弃。作业对虚拟机文件系统所做的任何更改（例如签出代码）在下一个作业上都不可用。

Microsoft 托管代理可以直接在 VM 上运行作业，也可以在容器中运行作业。

Azure Pipelines 为 Microsoft 托管代理提供名为 Azure Pipelines 的预定义代理池。

对于许多团队，此过程是运行作业的最简单方法。可以先尝试一下，看看它是否适合您的构建或部署。如果没有，可以使用虚拟机规模集代理或自承载代理。

提示

可以免费试用 Microsoft 托管代理。

详细了解 Microsoft 托管代理。

自托管代理

自托管代理是一个代理，你已设置为运行作业并自行管理。可以在 Azure Pipelines 或 Azure DevOps Server 中使用自承载代理。自托管代理可让你更好地控制安装生成和部署所需的依赖软件。此外，计算机级缓存和配置会在运行中持续存在，这可以提高速度。

虽然可以为每个计算机安装多个代理，但我们强烈建议你仅为每个计算机安装一个代理。安装两个或多个代理时，可能会对性能和管道结果产生不利影响。

提示

在安装自承载代理之前，可能需要查看Microsoft托管代理池是否适合你。在许多情况下，Microsoft托管的代理池是最简单的入门方法。试一试。

可以在 Linux、macOS 和 Windows 计算机上安装代理。还可以在 Docker 容器上安装代理。有关安装自托管代理的详细信息，请参阅：

在 macOS 上，需要清除下载存档上的特殊属性，以防止 macOS Gatekeeper 保护在运行 ./config.sh 时对 TAR 文件中的每个程序集显示安全警告。以下命令用于清除文件上的扩展属性：

xattr -c vsts-agent-osx-x64-V.v.v.tar.gz  ## replace V.v.v with the version in the filename downloaded.
 
# then unpack the gzip tar file normally:

tar xvfz vsts-agent-osx-x64-V.v.v.tar.gz

在计算机上安装代理后，可以在该计算机上安装作业所需的任何其他软件。

注意

代理具有广泛的向后兼容性。只要 Azure DevOps 不需要更高版本的代理，任何代理版本都应与任何 Azure DevOps 版本兼容。

我们仅支持最新版本的代理，因为这是确保所有最新补丁和漏洞修复的唯一版本。

Node.js 运行器版本

代理附带多个版本的 Node.js 库，以支持使用不同 Node.js 处理程序的目标任务。

所有官方 Azure DevOps 任务都使用 Node.js 20 库作为通用处理程序。但是，客户可能仍然会使用停止支持的 Node.js 版本的自定义任务。扩展/自定义任务作者应使用当前 Node.js 版本更新/测试其任务。

有关 Azure Pipelines 中的 Node.js 运行程序生命周期的详细信息，请参阅 Azure Pipelines 代理中的Node.js 运行程序。

Azure 虚拟机规模集代理

Azure 虚拟机规模集代理是一种自承载代理形式，可以自动缩放以满足需求。这种弹性可减少一直运行专用代理的需求。与Microsoft托管的代理不同，您可以灵活控制代理运行的计算机的大小和镜像。

Azure Pipelines 为你自动管理代理的扩展。指定以下因素：

虚拟机规模集
备用代理的数量
规模集中的最大虚拟机数

有关详细信息，请参阅 Azure 虚拟机规模集代理。

托管 DevOps 池代理

托管 DevOps 池使开发团队能够快速轻松地启动专为团队特定需求定制的 Azure DevOps 代理池。

托管 DevOps 池：

实现安全最佳做法。
提供平衡成本和性能的方法。
为最常见的方案提供路径。
显著缩短创建和维护自定义池所需的时间。

托管 DevOps 池是 Azure 虚拟机规模集代理池的一种进化形式。它通过提高自定义池的可伸缩性和可靠性进一步简化了自定义池的创建。托管 DevOps 池是一项完全托管的服务。托管代理的虚拟机或容器位于 Microsoft Azure 订阅中，而不是在您自己的 Azure 订阅中，类似于 Azure 虚拟机规模集代理池。有关详细信息，请参阅托管 DevOps 池文档。

并行作业

并行作业的概念表示可以在组织中同时运行的作业数。如果组织具有单个并行作业，则可以在组织中一次运行单个作业。任何其他并发作业将排队，直到第一个作业完成。要同时运行两个作业，需要有两个并行作业。在 Azure Pipelines 中，可以在 Microsoft 托管的基础结构上运行并行作业，也可以在自己的（自托管）基础结构上运行并行作业。

默认情况下，Microsoft 在每个组织中都提供免费的服务层级，其中至少包含一个并行作业。根据需要运行的并发管道数，可能需要更多并行作业才能同时使用多个 Microsoft 托管代理或自托管代理。有关并行作业和不同的免费服务层级的详细信息，请参阅 Azure Pipelines 中的并行作业。

可能需要更多并行作业才能同时使用多个代理：

Azure DevOps Server 中的并行作业

重要

从 Azure DevOps Server 2019 开始，无需在版本中为自承载并发作业付费。仅受你拥有的代理数的限制。

功能

每个自托管代理都有一组功能，用于指示它可以执行的操作。能力是名称/值对，可以是：

代理软件发现的功能，称为 系统功能。
定义的功能，称为 用户功能。

代理软件会自动确定各种系统功能。这些功能包括计算机的名称、作系统类型以及计算机上安装的某些软件的版本。此外，计算机中定义的环境变量会自动显示在系统功能列表中。

将环境变量存储为功能时，存储的功能值用于在代理运行时设置环境变量。此外，在代理运行时对环境变量进行任何更改时，不会由任何任务选取和使用它们。如果不希望更改的敏感环境变量存储为功能，则可以指示代理忽略它们。设置 VSO_AGENT_IGNORE 环境变量，并使用逗号分隔的变量列表来忽略。例如，PATH 是一个关键变量，在安装软件时可能需要忽略。

当你创作管道时，需要指定代理的某些需求。系统仅将作业发送到具有与管道中指定的需求匹配功能的代理。因此，通过代理功能可以将作业定向到特定代理。

需求和功能设计用于自托管代理，以便作业可与满足作业要求的代理匹配。使用 Microsoft 托管代理时，需要选择一个与作业要求相符的代理镜像。虽然可以将功能添加到Microsoft托管的代理中，但不需要在Microsoft托管代理中使用这些功能。

要向 YAML 生成管道添加需求，请将 demands: 行添加到 pool 部分。

pool:
  name: Default
  demands: SpecialSoftware # exists check for SpecialSoftware

可以检查功能是否存在或与功能值进行比较。有关详细信息，请参阅 YAML 架构 - 需求。

名称	条件	“值”
`SpecialSoftware`	Exists	n/a
`Agent.OS`	等于	Linux

配置代理功能

Azure Pipelines UI
Azure DevOps CLI

可以查看代理详细信息，包括版本和系统功能，以及管理其用户功能。转到 代理池 ，然后选择所需代理的 “功能 ”选项卡。

在 Web 浏览器中，转到 代理池：
1. (https://dev.azure.com/{yourorganization}) 登录到组织。
2. 选择 Azure DevOps>组织设置。
3. 选择 代理池。
1. 登录到项目集合 (http://your-server/DefaultCollection)。
2. 选择 Azure DevOps>集合设置。
3. 选择 代理池。
转到“ 功能 ”选项卡：
1. 从代理池选项卡中，选择所需的代理池。
2. 选择代理，然后选择所需的代理。
3. 选择功能选项卡。
  
  注意
  
  Microsoft 托管的代理不显示系统功能。有关 Microsoft 托管代理上安装的软件的列表，请参阅使用 Microsoft 托管代理。
1. 从代理池选项卡中，选择所需的池。
2. 选择代理，然后选择所需的代理。
3. 选择功能选项卡。
若要向代理注册新功能，请选择 “添加新功能”。

可以查看代理详细信息，包括版本和功能。使用以下 az pipelines agent Azure CLI 方法。

列出代理 | 显示代理详细信息

注意

如果这是你第一次使用 az pipelines 命令，请参阅 Azure DevOps CLI 入门。

列出代理

可以通过使用az pipelines agent list命令来列出您的代理。

az pipelines agent list --pool-id
                        [--agent-name]
                        [--demands]
                        [--detect {false, true}]
                        [--include-assigned-request {false, true}]
                        [--include-capabilities {false, true}]
                        [--include-last-completed-request {false, true}]
                        [--org]
                        [--subscription]

参数

pool-id：（必需）包含代理的代理池。
agent-name：根据代理名称进行筛选。
demands：根据代理能够满足的需求进行筛选。逗号分隔的列表。
detect：自动检测组织。接受的值是 false 和 true。
include-assigned-request：确定是否包括有关代理当前工作的详细信息。接受的值是 false 和 true。
include-capabilities：确定是否在响应中包含代理的功能。接受的值是 false 和 true。
include-last-completed-request：确定是否包括有关代理最近完成工作的详细信息。接受的值是 false 和 true。
org 或 organization：Azure DevOps 组织 URL。可以使用 az devops configure -d organization=ORG_URL 配置默认组织。如果未将该参数配置为默认值或通过 git 配置获取，该参数是必需的。示例：https://dev.azure.com/MyOrganizationName/.
subscription：订阅的名称或 ID。可以使用 az account set -s NAME_OR_ID配置默认订阅。

示例

以下示例以表格式列出池 ID: 4 中的所有代理。若要检索池的 ID，请使用 az pipelines pool list。此示例使用以下默认配置：az devops configure --defaults organization=https://dev.azure.com/fabrikam-tailspin project=FabrikamFiber。

az pipelines agent list --pool-id 4 --output table

ID    Name          Is Enabled    Status    Version
----  ------------  ------------  --------  ---------
3     Hosted Agent  True          offline   2.155.1

显示代理详细信息

可以使用命令检索代理详细信息 az pipelines agent show 。

az pipelines agent show --agent-id
                        --pool-id
                        [--detect {false, true}]
                        [--include-assigned-request {false, true}]
                        [--include-capabilities {false, true}]
                        [--include-last-completed-request {false, true}]
                        [--org]
                        [--subscription]

参数

agent-id 或 id：（必需）要获取相关信息的代理 ID。
pool-id：（必需）包含代理的代理池。
detect：自动检测组织。接受的值是 false 和 true。
include-assigned-request：确定是否包括有关代理当前工作的详细信息。接受的值是 false 和 true。
include-capabilities：确定是否在响应中包含代理的功能。接受的值是 false 和 true。
include-last-completed-request：确定是否包括有关代理最近完成工作的详细信息。接受的值是 false 和 true。

可以使用 Windows 身份验证来运行任务来访问外部服务。当代理与代理交换时，代理必须在管道或变量组中有权访问该服务的帐户下运行。

代理与 Azure Pipelines 之间交换的消息的有效负载通过使用非对称加密进行保护。每个代理都有一个公钥/私钥对，公钥在注册期间与服务器交换。服务器在将作业发送到代理之前，使用公钥对作业的有效负载进行加密。代理使用其私钥解密作业内容。 gentCloudRequest": null,


  <Some properties omitted for space>

  "status": "offline",
  "statusChangedOn": null,
  "systemCapabilities": {
    "ANDROID_HOME": "",
    "ANDROID_NDK_HOME": "",
    "Agent.Name": "Hosted Agent",
    "Agent.Version": "2.160.1",

    <Some capabilities omitted for space>

    "sh": "",
    "subversion": "",
    "svn": "",
    "To run tasks using Windows authentication to access an external service, the agent must run under an account with access to that service.

如果您运行像 Selenium 一样需要浏览器的 UI 测试或编码 UI 测试，浏览器将在代理帐户的上下文中打开。

在 Windows 上，建议使用网络服务或本地服务等服务帐户。这些帐户具有未过期的受限权限和密码。此过程可减少一段时间内代理管理的需求。

这些凭据不同于将代理注册到 Azure Pipelines 或 Azure DevOps Server 时使用的凭据。

Azure DevOps Server 不支持 Azure DevOps CLI 命令。

提示

在自托管代理上安装新软件后，必须重启代理才能显示新功能。有关详细信息，请参阅重启 Windows 代理、重启 Linux 代理和重启 Mac 代理。

通信

与 Azure Pipelines 的通信

与 Azure DevOps Server 通信

代理与 Azure Pipelines 或 Azure DevOps Server 通信。它确定需要运行的作业，并报告日志和作业状态。这种通信总是由代理发起。

从代理到 Azure Pipelines 或 Azure DevOps Server 的所有消息都通过 HTTP 或 HTTPS 发送，具体取决于代理的配置方式。此拉取模型允许将代理配置为不同的拓扑，如以下示例所示。

下面是代理与 Azure Pipelines 或 Azure DevOps Server 之间的常见通信模式：

用户通过将代理添加到代理池来向 Azure Pipelines 或 Azure DevOps Server 注册代理。若要在该代理池中注册代理，需要具有代理池管理员角色。注册时仅需要 代理池管理员 角色，并且该角色不会在代理上保留。在代理与 Azure Pipelines 或 Azure DevOps 服务器之间的任何进一步通信中都不会使用它。

注册完成后，代理会下载 listener OAuth token 并使用它来侦听作业队列。
代理使用 HTTP 长轮询监听是否有新的作业请求在 Azure Pipelines 或 Azure DevOps Server 的作业队列中发布。当作业可用时，代理将下载该作业及相关文件 job-specific OAuth token。 Azure Pipelines 或 Azure DevOps Server 为管道中指定的范围限定的身份生成生存期较短的令牌。

代理使用该令牌访问或修改该作业中的 Azure Pipelines 或 Azure DevOps Server 上的资源。例如，它使用令牌访问源代码或上传测试结果。
代理在作业完成后删除特定于作业的OAuth令牌，然后使用监听器的OAuth令牌检查是否存在新的作业请求。

代理与 Azure Pipelines 或 Azure DevOps Server 之间交换的消息的有效负载通过使用非对称加密进行保护。

每个代理都有一个公钥/私钥对，公钥在注册期间与服务器交换。服务器在将作业发送到代理之前，使用公钥对作业的有效负载进行加密。代理使用其私钥解密作业内容。

在与代理交换时，这种方法可确保存储在管道或变量组中的机密安全。

注意

该代理支持 UTF-8 客户端编码输出。但是，如果系统不使用 UTF-8 编码，则日志输出可能会遇到一些问题。例如，日志可能包含系统编码无法识别的字符，因此它们可能显示为乱码或缺少符号。

部署到目标服务器的通信

使用代理将项目部署到一组服务器时，它必须与这些服务器建立“视线”连接。默认情况下，Microsoft托管的代理池与 Azure 中运行的 Azure 网站和服务器建立连接。

如果 Azure 资源在 Azure 虚拟网络中运行，则可以获取 Microsoft 托管代理的代理 IP 范围。然后，可以为 Azure 虚拟网络配置防火墙规则，以允许代理访问。

如果本地环境无法连接到 Microsoft 托管的代理池（通常是由于中间防火墙造成的），则需要在内部部署计算机上手动配置自托管代理。代理必须连接到目标本地环境，并有权访问 Internet 以连接到 Azure Pipelines 或 Azure DevOps Server。此过程在以下示意图中进行了演示：

身份验证

要注册代理，你需要是代理池中管理员角色的成员。代理池管理员的身份仅在注册时需要，不会在代理上持久存在。在代理与 Azure Pipelines 或 Azure DevOps 服务器之间的任何后续通信中都不会使用它。若要配置代理，还必须是服务器上的本地管理员。

注册代理时，请从以下身份验证类型中进行选择。代理设置过程会提示输入每种身份验证类型所需的特定附加信息。有关详细信息，请参阅自托管代理身份验证选项。

个人访问令牌。
备用：使用基本身份验证连接到 Azure DevOps Server。选择 “备用”时，系统会提示输入凭据。

此外，Windows 代理在 Azure DevOps Server 上还有以下两个身份验证选项。

协商：通过 Windows 身份验证方案（例如，新技术 LAN 管理器（NTLM）或 Kerberos，以非登录用户以外的用户身份连接到 Azure DevOps Server。选择 “协商”后，系统会提示输入凭据。
集成：（默认）通过 Windows 身份验证方案（例如 NTLM 或 Kerberos）使用已登录用户的凭据将 Windows 代理连接到 Azure DevOps Server。选择此方法后，系统不会提示输入凭据。

重要

必须将服务器配置为支持身份验证方法，以使用备用、协商或集成身份验证。

用于注册代理的身份验证方法仅在代理注册期间使用。要详细了解代理在注册后如何与 Azure Pipelines 通信，请参阅与 Azure Pipelines 或 Azure DevOps Server 的通信。

交互与服务

可以将自托管代理作为服务或交互进程运行。

配置代理后，建议先在交互模式下试用它，以确保它正常工作。然后，出于生产用途，建议使用以下模式之一运行代理，以便它可靠地保持运行状态。这些模式还可确保代理在重启计算机时自动启动。

作为服务：可以使用作系统的服务管理器来管理代理的生命周期。在将代理作为系统服务运行时，自动升级代理的体验更好。
作为启用了自动登录的交互式进程：在某些情况下，可能需要以交互方式运行代理以供生产使用（例如，运行 UI 测试）。将代理配置为在此模式下运行时，屏幕保护程序将被禁用。某些域策略可能会阻止你启用自动登录或禁用屏幕保护程序。在这种情况下，可能需要从域策略中寻求豁免，或在域策略不适用的工作组计算机上运行代理。

注意

启用自动登录或禁用屏幕保护程序时，存在安全风险。其他用户可能能够访问计算机并使用自动登录的帐户。如果将代理配置为以这种方式运行，则必须确保计算机受到物理保护（例如，位于安全设施中）。

如果使用远程桌面访问运行代理的计算机并自动登录，关闭远程桌面会导致计算机锁定。在此代理上运行的任何 UI 测试都可能会失败。若要避免此问题，请使用 tscon 命令断开与远程桌面的连接。例如：

%windir%\System32\tscon.exe 1 /dest:console

代理帐户

无论是以服务方式运行代理，还是以交互方式运行代理，都可以选择用于运行代理的计算机帐户。代理账户的选择完全依赖于生成和部署作业中任务的需求。

例如，若要使用 Windows 身份验证运行任务来访问外部服务，代理必须使用有权访问该服务的帐户运行。但是，如果要运行需要浏览器的 UI 测试（如 Selenium 或编码的 UI 测试），浏览器将在代理帐户的上下文中打开。

在 Windows 上，建议使用网络服务或本地服务等服务帐户。这些帐户权限受到限制，其密码不会过期，因此代理需要随着时间的推移减少管理。

这些凭据不同于将代理注册到 Azure Pipelines 或 Azure DevOps Server 时使用的凭据。

代理版本和升级

我们每隔几周就会在 Azure Pipelines 中更新一次代理软件。我们用 {major}.{minor} 格式来表示代理版本。例如，如果代理版本为 2.1，则主要版本为 2，次要版本为 1。

我们将Microsoft托管的代理保持最新状态。如果代理的较新版本仅在次要版本上有所不同，Azure Pipelines 可以自动更新自托管代理。 默认设置处于启用状态。可以通过选择代理，然后选择“设置”在代理池中配置此设置。当管道中的平台功能或其中一项任务需要较新版本的代理时，会请求升级。

如果以交互方式运行自托管代理，或者有较新的代理主要版本可用，则可能需要手动升级代理。可以从组织下的 “代理池 ”选项卡升级代理。没有兼容的代理，管道无法运行。

更新自托管代理

转到 项目设置>代理池。
选择代理池，然后选择“ 更新所有代理”。

还可以通过从 ...菜单中选择“更新代理”来单独更新代理。
选择 “更新 ”以确认。
更新请求将针对池中的每个代理排队，并将在当前运行的所有任务完成后运行。升级通常需要一些时间。此时间足够长，足以下载最新版本的代理软件（大约 200 MB），将其解压缩，并使用新版本重启代理。可以在“代理”选项卡上监视代理的状态。

我们将使用每个 Azure DevOps Server 更新来更新代理软件。我们用 {major}.{minor} 格式来表示代理版本。例如，如果代理版本为 2.1，则主要版本为 2，次要版本为 1。

当你的 Azure DevOps Server 具有较新版本的代理，并且这个较新的代理只在次版本号上有所不同时，它通常可以自动升级。当管道中使用的平台功能或其中一项任务需要较新版本的代理时，会请求升级。从 Azure DevOps Server 2019 开始，无需等待新的服务器发布。可以将新版本的代理上传到应用层，该版本会作为升级提供。

如果以交互方式运行代理，或者代理 的较新版本 可用，则可能需要手动升级代理。可以从项目集合下的代理池选项卡轻松升级代理。没有兼容的代理，管道无法运行。

可以查看代理的版本。转到 代理池 ，然后选择所需代理的 “功能 ”选项卡，如 “配置代理功能”中所述。

若要以编程方式触发代理更新，可以使用 代理更新 API ，如“ 如何以编程方式为特定代理池触发代理更新？”部分所述。

对于无法访问 Internet 的服务器，请将代理 ZIP 文件手动复制到以下文件夹，以用作本地文件。创建代理文件夹（如果不存在）：

Windows： %ProgramData%\Microsoft\Azure DevOps\Agents
Linux：usr/share/Microsoft/Azure DevOps/Agents
macOS：usr/share/Microsoft/Azure DevOps/Agents

代理目录结构

在代理上运行管道作业时，会创建一个目录结构来存储源代码、二进制文件和项目。

代理的主目录是安装代理的目录。目录通常位于：

Microsoft托管代理： C:\agents\<agent version> 在 Windows、 /Users/runner/runners/<agent version> macOS 和 /home/vsts/agents/<agent version> Linux 上。
自托管代理：C:\agent Windows、Users/<username>/agent （~/agent）macOS 和 /home/vsts/agent Linux 上。

代理的工作目录包含存储源和作业输出的工作区。工作目录通常位于：

Microsoft托管代理： C:\a 在 Windows、 /Users/runner/work macOS 和/home/vsts/work Linux 上。
自承载代理： C:\agent\_work 在 Windows、 ~/agent/work macOS 和 /home/agent/_work Linux 上。

工作目录结构为：


    - /work directory
        - /1 build directory/pipeline workspace
            - /s source/working directory
            - /b binaries directory
            - /a artifacts staging directory
            - /TestResults Test results directory

Directory	说明	例子	预定义变量
代理主目录	代理安装位置。	Microsoft托管代理： Windows： `C:\agents\3.248.0` Linux：`/home/vsts/agents/3.248.0` macOS：`/Users/runner/runners/3.248.0` 自托管代理 Windows： `C:\agent` Linux：`home/agent` macOS：`~/agent`	`Agent.HomeDirectory`
工作目录	代理存储源代码、二进制文件和项目的位置。	Microsoft托管代理： Windows： `C:\a` Linux：`/home/vsts/work` macOS：`/Users/runner/work` 自托管代理 Windows： `C:\agent\_work` Linux：`/home/agent/_work` macOS：`~/agent/work`	`Agent.WorkFolder` `Agent.RootDirectory` `System.WorkFolder`
生成目录或工作区	管道作业运行的位置。	Microsoft托管代理： Windows： `C:\a\1` Linux：`/home/vsts/work/1` macOS：`/Users/runner/work/1` 自托管代理 Windows： `C:\agent\_work\1` Linux：`/home/agent/_work/1` macOS：`~/agent/work/1`	`Agent.BuildDirectory` `Pipeline.Workspace`
`s` - 源目录或工作目录	包含从存储库检出的源代码。如果作业中有多个 `checkout` 步骤，源代码将签出到以存储库命名的目录，该目录作为 `s` 的子文件夹。	Microsoft托管代理： Windows： `C:\a\1\s` Linux：`/home/vsts/work/1/s` macOS：`/Users/runner/work/1/s` 自托管代理 Windows： `C:\agent\_work\1\s` Linux：`/home/agent/_work/1/s` macOS：`~/agent/work/1/s`	`Build.SourcesDirectory` `Build.RepositoryLocalPath` `System.DefaultWorkingDirectory`
`b` - 二进制文件目录	包含版本输出。	Microsoft托管代理： Windows： `C:\a\1\b` Linux：`/home/vsts/work/1/b` macOS：`/Users/runner/work/1/b` 自托管代理 Windows： `C:\agent\_work\1\b` Linux：`/home/agent/_work/1/b` macOS：`~/agent/work/1/b`	`Build.BinariesDirectory`
`a` - 工件暂存目录	包含版本工件。在自托管代理的每次运行间隙进行清理。	Microsoft托管代理： Windows： `C:\a\1\a` Linux：`/home/vsts/work/1/a` macOS：`/Users/runner/work/1/a` 自托管代理 Windows： `C:\agent\_work\1\a` Linux：`/home/agent/_work/1/a` macOS：`~/agent/work/1/a`	`Build.StagingDirectory` `Build.ArtifactStagingDirectory` `System.ArtifactsDirectory`
`TestResults` 目录	包含测试结果。在自托管代理的每次运行间隙进行清理。	Microsoft托管代理： Windows： `C:\a\1\TestResults` Linux：`/home/vsts/work/1/TestResults` macOS：`/Users/runner/work/1/TestResults` 自托管代理 Windows： `C:\agent\_work\1\TestResults` Linux：`/home/agent/_work/1/TestResults` macOS：`~/agent/work/1/TestResults`	`Common.TestResultsDirectory`

在Microsoft托管代理上，每次运行都会使用不同的代理，因此工作目录不会在运行之间保留。在自承载代理上，默认情况下，只会在运行之间清理项目暂存目录和测试结果目录。有关工作区清理选项的详细信息，请参阅工作区。

有关预定义变量的详细信息，请参阅预定义变量。

FAQ

如何确保我使用的是最新的代理版本？

转到 “代理池 ”选项卡：
1. (https://dev.azure.com/{yourorganization}) 登录到组织。
2. 选择 Azure DevOps>组织设置。
3. 选择 代理池。
1. 登录到项目集合 (http://your-server/DefaultCollection)。
2. 选择 Azure DevOps>集合设置。
3. 选择 代理池。
选择包含代理的池。
确保已启用代理。
转到“功能”选项卡：
1. 从代理池选项卡中，选择所需的代理池。
2. 选择代理，然后选择所需的代理。
3. 选择功能选项卡。
  
  注意
  
  Microsoft 托管的代理不显示系统功能。有关 Microsoft 托管代理上安装的软件的列表，请参阅使用 Microsoft 托管代理。
1. 从代理池选项卡中，选择所需的池。
2. 选择代理，然后选择所需的代理。
3. 选择功能选项卡。
查找 Agent.Version 功能。可以将此值与 Azure Pipelines 代理页上的最新已发布代理版本进行比较。
每个代理在运行需要较高版本的代理的任务时，都会自动自行更新。如果要手动更新某些代理，请右键单击池，然后选择“ 更新所有代理”。

是否可以更新属于 Azure DevOps Server 池的代理？

是。从 Azure DevOps Server 2019 开始，可以将服务器配置为在本地磁盘上查找代理包文件。此配置将替代在发布时服务器附带的默认版本。当服务器无权访问 Internet 时，此方案也适用。

从具有 Internet 访问权限的计算机，从 Azure Pipelines 代理 GitHub 发布页下载最新版本的代理包文件（.zip 或.tar.gz表单）。
使用所选方法（例如 USB 驱动器、网络传输等）将下载的包文件传输到每个 Azure DevOps Server 应用程序层。将代理文件放在 %ProgramData%\Microsoft\Azure DevOps\Agents 文件夹下。如果没有标记为 “代理”的文件夹，请创建一个。
你已完成所有设置！每当更新代理时，Azure DevOps Server 现在都使用本地文件。每个代理在运行需要较高版本的代理的任务时，都会自动自行更新。但是，如果要手动更新某些代理，请右键单击池，然后选择“更新所有代理”。

自托管代理与 Microsoft 托管的代理相比是否有任何性能优势？

在许多情况下，有。如果使用自托管代理，则可运行增量生成。例如，如果定义的管道不清理存储库且不执行干净的生成，则生成通常运行速度更快。除非使用诸如缓存等功能，否则无法通过Microsoft托管代理获得这些优势，因为管道完成后会销毁代理。

Microsoft 托管的代理可能需要更长的时间来启动你的生成。尽管作业通常需要几秒钟时间才能分配给Microsoft托管的代理，但有时可能需要几分钟时间才能分配代理，具体取决于系统上的负载。

能否在同一台计算机上安装多个自托管代理？

是。此方法可能适用于运行不消耗许多共享资源的进程的代理。例如，如果代理运行的发布主要用于协调部署，并且不会在代理本身上执行太多操作，则可尝试使用该方法。

你可能会发现，在其他情况下，在同一台计算机上运行多个代理并不会提高效率。例如，对于那些运行占用大量磁盘空间和输入/输出资源的构建的代理，可能价值不大。

如果并行构建任务使用相同的单例工具部署（例如 npm 包），则可能会遇到问题。一个生成可能会在另一个生成使用它时更新依赖项，这可能会导致不可靠的结果和错误。

代理在取消管道作业时该怎么办？

对于 Microsoft 托管代理，代理将被销毁并返回到 Azure Pipelines 池。

对于自托管代理：

取消管道后，代理会将一系列命令发送到正在执行当前步骤的进程。
第一个命令的超时值为 7.5 秒。
如果进程未终止，则会发送第二个命令，超时为 2.5 秒。
如果进程没有终止，代理就会命令将其终止。
如果进程忽略了这两个初始终止请求，就会被强制终止。

从初始请求到终止的时间约为 10 秒。

发出给进程以取消管道的命令因代理作系统而异：

macOS 和 Linux：发送的命令依次为SIGINT、然后是SIGTERM，再然后是SIGKILL。
Windows：发送到进程的命令是Ctrl+C，接着是Ctrl+Break，然后是Process.Kill。

如何以编程方式触发特定代理池的代理更新？

可以使用以下 API 触发池的代理更新：

POST https://dev.azure.com/{organization}/_apis/distributedtask/pools/{poolId}/messages?agentId={agentId}&api-version=6.0

POST https://{server url}/tfs/{collection}/_apis/distributedtask/pools/{poolId}/messages?agentId={agentId}&api-version=6.0

注意

有关详细信息，请参阅 API 和 Azure DevOps Server 版本映射。

URI 参数

名称	在	必需	类型	说明
`agentId`	查询	`False`	字符串	要更新的代理。如果未指定，则会为所有代理触发更新。
`organization`	路径	`True`	字符串	Azure DevOps 组织的名称。
`poolId`	路径	`True`	整数 (int32)	要使用的代理池。
`api-version`	查询	`False`	字符串	要使用的 API 版本。若要使用此版本的 API，应将该值设置为 `6.0`。

若要触发代理更新，请求正文应为空。

Azure Pipelines 代理是 GitHub 上的开放源代码。

有关代理的详细信息，请参阅 Azure DevOps 学习路径中的“生成应用程序 ”中的以下模块：

反馈

此页面是否有帮助？

Last updated on 2025-12-17