Self-hosted Windows agents（自托管 Windows 代理）

Azure DevOps Services

若要生成和部署 Windows、Azure 和其他 Visual Studio 解决方案，至少需要一个 Windows 代理。 Windows 代理还可以生成 Java 与 Android 应用。

重要

本文提供有关将 3.x 代理软件与 Azure DevOps Services 配合使用的指导。 如果使用 Azure DevOps Server 或 TFS，请参阅自托管 Windows 代理（代理版本 2.x）。

注意

本文介绍如何配置自托管代理。 如果使用 Azure DevOps Services 并且 Microsoft 托管的代理满足你的需求，则可以跳过设置自托管 Windows 代理。

了解代理

如果你已知道代理的定义及其工作原理，可随意跳转到下面的部分。 但是，如果你想要详细了解其作用和工作原理的更多背景信息，请参阅 Azure Pipelines 代理。

检查先决条件

确保计算机满足以下先决条件：

• 操作系统版本
  • 客户端操作系统
    • Windows 7 SP1 ESU
    • Windows 8.1
    • Windows 10
    • Windows 11
  • 服务器操作系统
    • Windows Server 2012 或更高版本
• 代理软件安装自己的 .NET 版本，因此没有 .NET 先决条件。
• PowerShell 3.0 或更高版本
• Subversion - 如果要从 Subversion 存储库生成，必须在计算机上安装 Subversion 客户端。
• 推荐 - Visual Studio 生成工具（2015 或更高版本）

第一次应手动运行代理安装程序。 了解代理的工作原理后，或者如果你想要自动设置多个代理，请考虑使用无人参与配置。

硬件规格

代理的硬件规格因需求、团队大小等而异。无法给出普遍适用的通用建议。 作为参考点，Azure DevOps 团队在生成托管代理代码时采用的是利用了托管代理的管道。 另一方面，大部分 Azure DevOps 代码是由 24 核服务器等级的计算机生成的，每个核心运行四个自托管代理。

准备权限

自托管代理的信息安全性

配置代理的用户需要具有池管理员权限，但运行代理的用户不需要。

代理控制的文件夹应该限制为尽可能少的用户，因为它们包含可能被解密或泄露的机密。

Azure Pipelines 代理是一个软件产品，旨在执行从外部源下载的代码。 它本身就可能成为远程代码执行 (RCE) 攻击的目标。

因此，请务必考虑围绕 Pipelines 代理的每次单独使用来执行工作的威胁模型，并确定可以授予运行代理的用户、运行代理的计算机、对 Pipeline 定义具有写入访问权限的用户，以及存储 yaml 的 git 存储库，或控制对新管道的池的访问的用户组的最低权限。

最佳做法是让运行代理的标识与具有将代理连接到池的权限的标识不同。 生成凭据（以及其他与代理相关的文件）的用户与需要读取的用户不同。 因此，仔细考虑向代理计算机本身以及包含敏感文件（如日志和项目）的代理文件夹授予的访问权限会更安全。

只向 DevOps 管理员和运行代理进程的用户标识授予对代理文件夹的访问权限是有意义的。 管理员可能需要调查文件系统，了解生成失败或获取日志文件，以便能够报告 Azure DevOps 失败。

决定要使用哪个用户

作为一个一次性的步骤，必须注册代理。 有权管理代理队列的人员必须完成这些步骤。 代理不会在日常操作中使用此人的凭据，但需要他们完成注册。 详细了解代理的通信方式。

确认用户具有权限

确保你要使用的用户帐户具有注册代理的权限。

用户是 Azure DevOps 组织所有者还是 TFS 或 Azure DevOps Server 管理员？ 如果到这一步，说明你拥有权限。

否则：

1. 打开浏览器并导航到 Azure Pipelines 组织、Azure DevOps Server 或 TFS 服务器的“代理池”选项卡：

   1. (https://dev.azure.com/{yourorganization}) 登录到组织。

   2. 选择“Azure DevOps”、“组织设置”。

      

   3. 选择“代理池”。

      

2. 选择页面右侧的池，然后单击“安全性”。

3. 如果未显示要使用的用户帐户，请让管理员添加该帐户。 管理员可以是代理池管理员、Azure DevOps 组织所有者、TFS 或 Azure DevOps Server 管理员。

   如果是部署组代理，管理员可以是部署组管理员、Azure DevOps 组织所有者、TFS 或 Azure DevOps Server 管理员。

   可以在 Azure Pipelines 的“部署组”页上的“安全性”选项卡中将用户添加到部署组管理员角色。

注意

如果看到如下消息：“很抱歉，无法添加标识。请尝试其他标识。”表明你可能已针对组织所有者或者 TFS 或 Azure DevOps Server 管理员执行了上述步骤。 无需执行任何操作；你已拥有管理代理池的权限。

下载并配置代理

Azure Pipelines

1. 使用已为其准备权限的帐户登录到计算机，如上所述。

2. 在 Web 浏览器中，登录到 Azure Pipelines，并导航到“代理池”选项卡：

   1. (https://dev.azure.com/{yourorganization}) 登录到组织。

   2. 选择“Azure DevOps”、“组织设置”。

      

   3. 选择“代理池”。

      

3. 选择“默认池”，选择“代理”选项卡，然后选择“新建代理”。

4. 在“获取代理”对话框中，选择“Windows”。

5. 在左窗格中，选择计算机上已安装的 Windows OS 版本的处理器体系结构。 x64 代理版本适用于 64 位 Windows，x86 版本适用于 32 位 Windows。 如果不确定安装了哪个版本的 Windows，请按照这些说明进行操作。

6. 在右窗格中，单击“下载”按钮。

7. 按照页面上的说明下载代理。

8. 将代理解压缩到所选目录中。 请确保目录的路径不包含空格，因为工具和脚本并不总是正确转义空格。 建议的文件夹为 C:\agents。 在下载文件夹或其他用户文件夹中提取可能会导致权限问题。

重要

强烈建议从提升的 PowerShell 窗口配置代理。 如果要配置为服务，则必须这样做。

请勿适用 Windows PowerShell ISE 来配置代理。

重要

出于安全原因，我们强烈建议确保代理文件夹 (C:\agents) 只能由管理员编辑。

注意

请避免在代理配置中使用基于 mintty 的 shell，例如 git-bash。 Mintty 与本机输入/输出 Windows API 不完全兼容（此处为一些相关信息），在这种情况下，我们不能保证安装脚本能够正常工作。

安装代理

1. 启动提升的 (PowerShell) 窗口，并将该位置设置为解压缩代理的位置。

   cd C:\agents 
   
   

2. 运行 config.cmd。 这将询问一系列有关配置代理的问题。

   .\config.cmd
   
   

服务器 URL

当安装程序要求提供服务器 URL 时，对于 Azure DevOps Services，请回答 https://dev.azure.com/{your-organization}。

代理安装程序身份验证类型

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

• 个人访问令牌
• 设备代码流
• 服务主体

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

选择交互模式或服务模式

有关是要以交互模式还是以服务形式运行代理的指导，请参阅代理：交互与服务。

如果选择作为服务运行（这是我们建议的做法），则作为运行身份的用户名长度不能超过 20 个字符。

运行代理

以交互方式运行

如果将代理配置为以交互方式运行，请运行以下命令以启动代理。

.\run.cmd

若要重启代理，请按 Ctrl+C 以停止代理，然后运行 run.cmd 以重启代理。

运行一次

还可以选择让代理只接受一个作业，然后退出。 若要使用此配置运行，请使用以下命令。

.\run.cmd --once

此模式下的代理将仅接受一个作业，然后正常关闭（在诸如 Azure 容器实例的服务上的 Docker 中运行时很有用）。

作为服务运行

如果将代理配置为作为服务运行，则代理会自动启动。 可以从服务管理单元查看和控制代理运行状态。 运行 services.msc 并查找以下项之一：

• “Azure Pipelines 代理（代理的名称）”
• “VSTS Agent（代理的名称）”
• “vstsagent。（组织名称）。（代理名称）”

要重启代理，请右键单击条目，然后选择“重启”。

注意

如果需要更改代理的登录帐户，请不要在服务管理单元中更改。 请参阅以下信息来重新配置代理。

若要使用代理，请使用代理池运行作业。 如果未选择其他池，代理将位于“默认”池中。

替换代理

若要替换代理，请再次按照“下载并配置代理”步骤操作。

如果使用与现有代理相同的名称来配置代理，系统会询问是否要替换现有代理。 如果回答是 Y，请确保移除要替换的代理（见下文）。 否则，在几分钟的冲突之后，其中一个代理将关闭。

移除并重新配置代理

若要删除该代理，请执行以下操作：

.\config remove

移除代理后，可以再次对其进行配置。

无人参与配置

可以从脚本设置代理，无需人工干预。 必须传递 --unattended 和所有问题的答案。

若要配置代理，它必须知道组织的 URL，或者知道有权设置代理的人员的集合和凭据。 所有其他响应都是可选的。 可以改用环境变量指定任何命令行参数：对名称使用大写形式，并在前面加上 VSTS_AGENT_INPUT_。 例如，VSTS_AGENT_INPUT_PASSWORD，而不是指定 --password。

必需选项

• --unattended - 代理设置不会提示输入信息，必须在命令行上提供所有设置
• --url <url> - 服务器的 URL。 例如：https://dev.azure.com/myorganization 或 http://my-azure-devops-server:8080/tfs
• --auth <type> - 身份验证类型。 有效值是：
  • pat（个人访问令牌）- PAT 是唯一适用于 Azure DevOps Services 的方案。
  • negotiate（Kerberos 或 NTLM）
  • alt（基本身份验证）
  • integrated（Windows 默认凭据）

身份验证选项

• 如果选择 --auth pat：
  • --token <token> - 指定个人访问令牌
  • PAT 是唯一适用于 Azure DevOps Services 的方案。
• 如果选择 --auth negotiate 或 --auth alt：
  • --userName <userName> - 以 domain\userName 或 userName@domain.com 格式指定 Windows 用户名
  • --password <password> - 指定密码

池和代理名称

• --pool <pool> - 代理要加入的池名称
• --agent <agent> - 代理名称
• --replace - 替换池中的代理。 如果另一个代理以同一名称侦听，它将开始由于冲突而失败

代理安装

• --work <workDirectory> - 存储作业数据的工作目录。 默认为代理目录的根目录下的 _work。 工作目录归指定的代理所有，不应在多个代理之间共享。
• --acceptTeeEula - 接受 Team Explorer Everywhere 最终用户许可协议（仅适用于 macOS 和 Linux）
• --disableloguploads - 不将控制台日志输出流式传输或发送到服务器。 相反，可以在作业完成后从代理主机的文件系统中进行检索。

仅 Windows 启动

• --runAsService - 将代理配置为作为 Windows 服务运行（需要管理员权限）
• --runAsAutoLogon - 配置自动登录并在启动时运行代理（需要管理员权限）
• --windowsLogonAccount <account> - 与 --runAsService 或 --runAsAutoLogon 搭配使用，以 domain\userName 或 userName@domain.com 格式指定 Windows 用户名
• --windowsLogonPassword <password> - 与 --runAsService 或 --runAsAutoLogon 搭配使用，指定 Windows 登录密码（组托管服务帐户和 Windows 内置帐户则不需要，如“NT AUTHORITY\NETWORK SERVICE”）
• --overwriteAutoLogon - 与 --runAsAutoLogon 搭配使用，覆盖计算机上的现有自动登录
• --noRestart - 与 --runAsAutoLogon 搭配使用，在代理配置完成后使主机停止重启

使用 runAsAutoLogon 选项配置代理的故障排除

使用 runAsAutoLogon 选项配置代理，会在每次重启计算机后运行代理。 如果重启计算机后代理没有运行，请执行后续步骤。

如果已在计算机上配置代理

在重新配置代理之前，必须移除旧的代理配置，因此请尝试从代理文件夹运行以下命令：

.\config.cmd remove --auth 'PAT' --token '<token>'

执行命令后，检查代理是否已从代理池中移除：

<Azure DevOps organization> / <Project> / Settings / Agent pools / <Agent Pool> / Agents

如果运行命令未能将代理从代理池中移除，请手动进行移除。

然后，尝试从代理文件夹运行以下命令，重新配置代理：

.\config.cmd --unattended --agent '<agent-name>' --pool '<agent-pool-name>' --url '<azure-dev-ops-organization-url>' --auth 'PAT' --token '<token>' --runAsAutoLogon --windowsLogonAccount '<domain\user-name>' --windowsLogonPassword '<windows-password>'

指定代理名称（任何特定的唯一名称），并在重新配置后检查此代理是否出现在代理池中。

最好解压缩代理存档（可在此处下载），并从新的解压缩代理文件夹运行此命令。

检查是否正确记录并保存了 Windows 注册表项

运行 whoami /user 命令以获取 <sid>。 打开 Registry Editor 并遵循以下路径：

Computer\HKEY_USERS\<sid>\SOFTWARE\Microsoft\Windows\CurrentVersion\Run

检查是否存在 VSTSAgent 键。 如果此键存在，请将其删除，然后关闭 Registry Editor，并通过从代理文件夹运行 .\config.cmd 命令（没有参数）来配置代理。 在回答 Enter Restart the machine at a later time? 问题之前，请再次打开 Registry Editor，检查 VSTSAgent 键是否已出现。 按下 Enter 回答问题，并在重启计算机后检查 VSTSAgent 键是否仍在原处。

检查 Windows 注册表项是否在计算机上正常工作

创建一个包含以下行的 autorun.cmd 文件：echo "Hello from AutoRun!"。 打开 Registry Editor，并在上方的路径中使用 AutoRun 键和值创建一个新的键值对

C:\windows\system32\cmd.exe /D /S /C start "AutoRun" "D:\path\to\autorun.cmd"

重启计算机。 如果看不到显示 Hello from AutoRun! 消息的控制台窗口，表明 Windows 注册表项出现问题。

仅部署组

• --deploymentGroup - 将代理配置为部署组代理
• --deploymentGroupName <name> - 与 --deploymentGroup 搭配使用，指定代理要加入的部署组
• --projectName <name> - 与 --deploymentGroup 搭配使用，设置项目名称
• --addDeploymentGroupTags - 与 --deploymentGroup 搭配使用，指示应添加部署组标记
• --deploymentGroupTags <tags> - 与 --addDeploymentGroupTags 搭配使用，指定以逗号分隔的部署组代理标记列表，例如“web, db”

仅环境

• --addvirtualmachineresourcetags - 用于指示应添加环境资源标记
• --virtualmachineresourcetags <tags> - 与 --addvirtualmachineresourcetags 搭配使用，指定以逗号分隔的环境资源代理标记列表，例如“web, db”

.\config --help 始终列出最新的必需响应和可选响应。

诊断

如果你的自托管代理出现问题，可以尝试运行诊断。 配置代理后：

.\run --diagnostics

这将运行诊断套件，它可以帮助你排查问题。 诊断功能从代理版本 2.165.0 开始提供。

自托管代理的网络诊断

将 Agent.Diagnostic 的值设置为 true 以收集其他日志，这些日志可用于排查自托管代理的网络问题。 有关详细信息，请参阅自托管代理的网络诊断

有关其他选项的帮助

若要了解其他选项，请运行以下命令：

.\config --help

帮助内容提供了有关身份验证备选方案和无人参与的配置的信息。

功能

代理的功能已编目并播发到池中，因此只会为代理分配它可以处理的生成和发布。 请参阅生成和发布代理功能。

在许多情况下，在部署代理后，需要安装软件或实用工具。 一般情况下，你在开发计算机上使用的任何软件和工具也应该在代理上安装。

例如，如果你的生成包含 npm 任务，则除非池中具有安装了 npm 的生成代理，否则该生成不会运行。

重要

功能包括所有环境变量，以及当代理运行时设置的值。 如果在代理运行时其中的任何一个值发生更改，则必须重启代理以拾取新值。 在代理上安装新软件后，必须重启代理才能使新功能显示在池中，以便生成可以运行。

如果你想要排除用作功能的环境变量，可以通过设置环境变量 VSO_AGENT_IGNORE 并提供以逗号分隔的要忽略的变量列表来指定这些变量。

常见问题解答

我的代理运行的是哪个版本的 Git？

默认情况下，Windows 代理使用与代理软件捆绑在一起的 Git 版本。 Microsoft 建议使用与代理捆绑在一起的 Git 版本，但有多个选项可以替代此默认行为，并使用代理计算机在路径中安装的 Git 版本。

• 在管道中将名为 System.PreferGitFromPath 的管道变量设置为 true。
• 在自托管代理上，可以在代理根目录中创建名为 .env 的文件，并在文件中添加 System.PreferGitFromPath=true 行。 有关详细信息，请参阅如何为每个单独的代理设置不同的环境变量？

若要查看管道使用的 Git 版本，可以查看管道中 checkout 步骤的日志，如以下示例所示。

Syncing repository: PathFilter (Git)
Prepending Path environment variable with directory containing 'git.exe'.
git version
git version 2.26.2.windows.1

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

1. 导航到“代理池”选项卡：

   1. (https://dev.azure.com/{yourorganization}) 登录到组织。

   2. 选择“Azure DevOps”、“组织设置”。

      

   3. 选择“代理池”。

      

2. 单击包含代理的池。

3. 确保已启用代理。

4. 导航到“功能”选项卡：

   1. 从“代理池”选项卡中，选择所需的代理池。

      

   2. 选择“代理”，然后选择所需的代理。

      

   3. 选择“功能”选项卡。

      

      注意

      Microsoft 托管的代理不显示系统功能。 有关 Microsoft 托管代理上安装的软件的列表，请参阅使用 Microsoft 托管代理。

5. 查找 Agent.Version 功能。 可以针对最新发布的代理版本检查此值。 请参阅 Azure Pipelines 代理，并检查页面上列出的最高版本号。

6. 每个代理在运行需要较高版本的代理的任务时，都会自动自行更新。 如果要手动更新某些代理，请右键单击池，然后选择“更新所有代理”。

我正在运行防火墙，我的代码在 Azure Repos 中。 代理需要与哪些 URL 通信？

如果正在防火墙后面的安全网络中运行代理，请确保代理可以启动与以下 URL 和 IP 地址的通信。

域 URL	说明
https://{organization_name}.pkgs.visualstudio.com	适用于使用 {organization_name}.visualstudio.com 域的组织的 Azure DevOps 打包 API
https://{organization_name}.visualstudio.com	适用于使用 {organization_name}.visualstudio.com 域的组织
https://{organization_name}.vsblob.visualstudio.com	适用于使用 {organization_name}.visualstudio.com 域的组织的 Azure DevOps 遥测
https://{organization_name}.vsrm.visualstudio.com	适用于使用 {organization_name}.visualstudio.com 域的组织的发布管理服务
https://{organization_name}.vssps.visualstudio.com	适用于使用 {organization_name}.visualstudio.com 域的组织的 Azure DevOps 平台服务
https://{organization_name}.vstmr.visualstudio.com	适用于使用 {organization_name}.visualstudio.com 域的组织的 Azure DevOps 测试管理服务
https://*.blob.core.windows.net	Azure Artifacts
https://*.dev.azure.com	适用于使用 dev.azure.com 域的组织
https://*.vsassets.io	通过 CDN 的 Azure Artifacts
https://*.vsblob.visualstudio.com	适用于使用 dev.azure.com 域的组织的 Azure DevOps 遥测
https://*.vssps.visualstudio.com	适用于使用 dev.azure.com 域的组织的 Azure DevOps 平台服务
https://*.vstmr.visualstudio.com	适用于使用 dev.azure.com 域的组织的 Azure DevOps 测试管理服务
https://app.vssps.visualstudio.com	适用于使用 {organization_name}.visualstudio.com 域的组织
https://dev.azure.com	适用于使用 dev.azure.com 域的组织
https://login.microsoftonline.com	Microsoft Entra 登录日志
https://management.core.windows.net	Azure 管理 API
https://vstsagentpackage.azureedge.net	代理包

若要确保你的组织使用任何现有的防火墙或 IP 限制，请确认 dev.azure.com 和 *dev.azure.com 已打开，并更新允许列出的 IP，以包括以下 IP 地址，具体取决于你的 IP 版本。 如果当前允许列出 13.107.6.183 和 13.107.9.183 IP 地址，请予以保留，因为不需要移除它们。

IPv4 范围

• 13.107.6.0/24
• 13.107.9.0/24
• 13.107.42.0/24
• 13.107.43.0/24

IPv6 范围

• 2620:1ec:4::/48
• 2620:1ec:a92::/48
• 2620:1ec:21::/48
• 2620:1ec:22::/48

注意

有关允许的地址的详细信息，请参阅允许的地址列表和网络连接。

如何使用自签名证书运行代理？

注意

使用自签名证书运行代理仅适用于 Azure DevOps Server。

使用自签名证书运行代理

如何在 Web 代理后面运行代理？

在 Web 代理后面运行代理

如何重启代理

如果是以交互方式运行代理，请参阅以交互方式运行中的重启说明。 如果要以服务身份运行代理，请按照作为服务运行中的步骤重启代理。

如何为每个单独的代理设置不同的环境变量？

在代理的根目录下创建一个 .env 文件，并按以下格式将要设置的环境变量放入文件中，然后重启代理。

MyEnv0=MyEnvValue0
MyEnv1=MyEnvValue1
MyEnv2=MyEnvValue2
MyEnv3=MyEnvValue3
MyEnv4=MyEnvValue4

如何配置代理以绕过 Web 代理并连接到 Azure Pipelines？

如果希望代理绕过代理并直接连接到 Azure Pipelines，应配置 Web 代理，使代理能够访问以下 URL。

对于使用 *.visualstudio.com 域的组织：

https://login.microsoftonline.com
https://app.vssps.visualstudio.com 
https://{organization_name}.visualstudio.com
https://{organization_name}.vsrm.visualstudio.com
https://{organization_name}.vstmr.visualstudio.com
https://{organization_name}.pkgs.visualstudio.com
https://{organization_name}.vssps.visualstudio.com

对于使用 dev.azure.com 域的组织：

https://dev.azure.com
https://*.dev.azure.com
https://login.microsoftonline.com
https://management.core.windows.net
https://vstsagentpackage.azureedge.net
https://vssps.dev.azure.com

若要确保你的组织使用任何现有的防火墙或 IP 限制，请确认 dev.azure.com 和 *dev.azure.com 已打开，并更新允许列出的 IP，以包括以下 IP 地址，具体取决于你的 IP 版本。 如果当前允许列出 13.107.6.183 和 13.107.9.183 IP 地址，请予以保留，因为不需要移除它们。

IPv4 范围

• 13.107.6.0/24
• 13.107.9.0/24
• 13.107.42.0/24
• 13.107.43.0/24

IPv6 范围

• 2620:1ec:4::/48
• 2620:1ec:a92::/48
• 2620:1ec:21::/48
• 2620:1ec:22::/48

注意

此过程使代理能够绕过 Web 代理。 对于在生成中运行的每个任务和工具，生成管道和脚本仍必须处理绕过 Web 代理的过程。

例如，如果使用 NuGet 任务，必须将 Web 代理配置为支持绕过托管正在使用的 NuGet 源的服务器的 URL。

我正在使用 TFS，上述部分中的 URL 对我不起作用。 在哪里可以获得帮助？

网站设置和安全性

“为代理服务启用 SERVICE_SID_TYPE_UNRESTRICTED”是什么意思？

在 Windows Server 上配置代理软件时，可以从以下提示符指定服务安全标识符。

Enter enable SERVICE_SID_TYPE_UNRESTRICTED for agent service (Y/N) (press enter for N)

代理软件的早期版本将服务安全标识符类型设置为 SERVICE_SID_TYPE_NONE，这是当前代理版本的默认值。 要将安全服务标识符类型配置为 SERVICE_SID_TYPE_UNRESTRICTED，请按 Y。

有关详细信息，请参阅 SERVICE_SID_INFO 结构和安全标识符。