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

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

重要

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

注意

本文引用了 CentOS，这是一个接近生命周期结束 (EOL) 状态的 Linux 发行版。 请相应地考虑你的使用和规划。 有关详细信息，请参阅 CentOS 生命周期结束指南。

若要运行作业，至少需要一个代理。 Linux 代理可以生成和部署不同类型的应用，包括 Java 和 Android 应用。 有关受支持的 Linux 分发版的列表，请参阅检查先决条件 。

注意

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

了解代理

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

检查先决条件

代理基于 .NET Core 6。 你可以在多个 Linux 分发版上运行此代理。 我们支持 .NET 6 支持的以下分发版子集：

• 支持的发行版
  • X64
    • CentOS 7, 8
    • Debian 10+
    • Fedora 36+
    • openSUSE 15+
    • Red Hat Enterprise Linux 7+
      • 不再需要单独的包
    • SUSE Enterprise Linux 12 SP2 或更高版本
    • Ubuntu 22.04、20.04、18.04、16.04
    • Azure Linux 2.0
  • ARM64
    • Debian 10+
    • Ubuntu 22.04、20.04、18.04
  • Alpine x64
    • Alpine Linux 3.13 及更高版本（需要代理 3.227 或更高版本）
• Git - 无论使用哪种平台，都需要安装 Git 2.9.0 或更高版本。 强烈建议安装最新版本的 Git。
• .NET - 代理软件在 .NET 6 上运行，但安装自己的 .NET 版本，因此没有 .NET 先决条件。
• Subversion - 如果要从 Subversion 存储库生成，必须在计算机上安装 Subversion 客户端。
• TFVC - 如果要从 TFVC 存储库生成，请参阅 TFVC 先决条件。

注意

代理安装程序知道如何检查其他依赖项。 可以通过在代理目录中运行 ./bin/installdependencies.sh，在受支持的 Linux 平台上安装这些依赖项。

请注意，.NET 所需的其中一些依赖项是从第三方站点（如 packages.efficios.com）中提取的。 在运行 installdependencies.sh 脚本之前，请审查该脚本，确保可从 Linux 计算机访问任何引用的第三方站点。

此外，请确保所有必需的存储库都连接到 installdependencies.sh 中使用的相关包管理器（如 apt 或 zypper）。

对于依赖项安装相关的问题（例如“在存储库中找不到依赖项”或“检索存储库索引文件时出现问题”），可以联系分发版所有者以获取进一步的支持。

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

准备权限

自托管代理的信息安全性

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

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

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. 在“获取代理”对话框中，单击“Linux”。

5. 在左窗格中，选择特定的风格。 我们为许多 Linux 发行版提供 x64 或 ARM。

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

7. 按照页面上的说明进行操作。
   

8. 将代理解压缩到所选的目录中。 通过 cd 转到该目录，运行 ./config.sh。

服务器 URL

Azure Pipelines：https://dev.azure.com/{your-organization}

身份验证类型

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

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

以交互方式运行

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

若要以交互方式运行代理，请执行以下步骤：

1. 如果一直将代理作为服务来运行，请卸载服务。

2. 运行代理。

   ./run.sh
   

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

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

运行一次

对于配置为以交互方式运行的代理，可以选择让代理仅接受一个作业。 在此配置中运行：

./run.sh --once

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

作为 systemd 服务运行

如果代理在以下操作系统上运行，可以将代理作为 systemd 服务来运行：

• Ubuntu 16 LTS 或更高版本
• Red Hat 7.1 或更高版本

我们向你提供了一个示例 ./svc.sh 脚本，可以将代理作为 systemd 服务来运行和管理。 当你配置代理后，将生成此脚本。 建议在运行脚本之前先查看脚本，并根据需要进行更新。

下面是一些重要的注意事项：

• 如果将代理作为服务来运行，则无法以 root 用户身份运行代理服务。
• 运行 SELinux 的用户已报告在使用已提供的 svc.sh 脚本时遇到困难。 请参阅此代理问题开始了解。 SELinux 不是官方支持的配置。

注意

如果你有不同的分发版，或者你更喜欢其他方法，可以使用任何你喜欢的服务机制。 请参阅服务文件。

命令

更改到代理目录

例如，如果你在主目录的 myagent 子文件夹中进行了安装：

cd ~/myagent$

安装

命令：

sudo ./svc.sh install [username]

此命令用于创建指向 ./runsvc.sh 的服务文件。 此脚本会设置环境（下面介绍了更多详细信息），并启动代理主机。 如果未指定 username 参数，则用户名取自通过 sudo 命令设置的 $SUDO_USER 环境变量。 此变量始终等于调用了 sudo 命令的用户的名称。

开始

sudo ./svc.sh start

状态

sudo ./svc.sh status

停止

sudo ./svc.sh stop

卸载

在卸载前应先停止。

sudo ./svc.sh uninstall

更新环境变量

当你配置服务时，它会为当前登录用户创建一些有用的环境变量的快照，例如 PATH、LANG、JAVA_HOME、ANT_HOME 和 MYSQL_PATH。 如果需要更新变量（例如，在安装一些新软件后），可以运行以下命令：

./env.sh
sudo ./svc.sh stop
sudo ./svc.sh start

在代理根目录下，环境变量的快照存储在 .env 文件中（PATH 存储在 .path 中），你也可以直接更改这些文件以应用环境变量更改。

在服务启动之前运行指令

你也可以运行自己的指令和命令，以在服务启动时运行。 例如，可以设置环境或调用脚本。

1. 编辑 runsvc.sh。

2. 将以下行替换为你的指令：

   # insert anything to setup env when running as a service
   

服务文件

当你安装服务时，会放置一些服务文件。

systemd 服务文件

将创建 systemd 服务文件：

/etc/systemd/system/vsts.agent.{tfs-name}.{agent-name}.service

举个例子，你已使用 our-linux-agent 名称配置了一个代理（如上文所述）。 服务文件将是：

• Azure Pipelines：组织的名称。 例如，如果连接到 https://dev.azure.com/fabrikam，服务名称将为 /etc/systemd/system/vsts.agent.fabrikam.our-linux-agent.service

• TFS 或 Azure DevOps Server：本地服务器的名称。 例如，如果连接到 http://our-server:8080/tfs，服务名称将为 /etc/systemd/system/vsts.agent.our-server.our-linux-agent.service

sudo ./svc.sh install 从以下模板生成此文件：./bin/vsts.agent.service.template

.service 文件

sudo ./svc.sh start 通过读取 .service 文件查找服务，该文件包含上述 systemd 服务文件的名称。

备用服务机制

我们提供了 ./svc.sh 脚本，方便你将代理作为 systemd 服务来运行和管理。 但是，你也可以使用任何喜欢的服务机制（例如：initd 或 upstart）。

可以使用上面所述的模板来帮助生成其他类型的服务文件。

使用 cgroup 避免代理失败

一定要避免代理失败或变得不可用的情况，否则代理将无法流式传输管道日志或将管道状态报告回服务器。 可以通过使用 cgroups 和较低的 oom_score_adj 来缓解高内存压力引发此类问题的风险。 完成此操作后，Linux 会先从管道作业进程回收系统内存，然后再从代理进程回收内存。 了解如何配置 cgroups 和 OOM 分数。

替换代理

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

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

移除并重新配置代理

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

1. 停止并卸载服务，如上一部分所述。

2. 移除代理。

   ./config.sh remove
   

3. 输入凭据。

移除代理后，可以再次配置代理。

无人参与配置

可以从脚本设置代理，无需人工干预。 必须传递 --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 的方案。
  • alt（基本身份验证）

身份验证选项

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

池和代理名称

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

代理安装

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

仅部署组

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

仅环境

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

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

诊断

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

./run.sh --diagnostics

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

自托管代理的网络诊断

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

有关其他选项的帮助

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

./config.sh --help

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

功能

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

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

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

重要

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

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

常见问题解答

我可以在哪里了解有关新 v3 代理软件的详细信息？

有关 v3 代理软件的信息和常见问题解答，请参阅代理软件版本 3。

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

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

为什么需要 sudo 来运行服务命令？

./svc.sh 使用 systemctl，后者需要 sudo。

源代码：GitHub 上的 systemd.svc.sh.template

我正在运行防火墙，我的代码在 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

注意

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

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

使用自签名证书运行代理

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

在 Web 代理后面运行代理

如何重启代理

如果是以交互方式运行代理，请参阅以交互方式运行中的重启说明。 如果是将代理作为 systemd 服务来运行，请依次按照停止、启动代理的步骤操作。

如何配置代理以绕过 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。

TFVC 先决条件

如果要使用 TFVC，还需要 Oracle Java JDK 1.6 或更高版本。 （Oracle JRE 和 OpenJDK 不足以实现此目的。）

TEE 插件用于 TFVC 功能。 它有一个 EULA，如果你打算使用 TFVC，需要在配置期间接受该 EULA。

由于 TEE 插件不再会维护，并且包含一些过时的 Java 依赖项，因此从代理 2.198.0 开始，它不再包含在代理分发版中。 但是，如果要签出 TFVC 存储库，则会在签出任务执行期间下载 TEE 插件。 执行作业后，将移除 TEE 插件。

注意

注意：你可能会注意到，由于此下载机制，签出任务需要很长时间才能开始运行。

如果代理在代理或防火墙后面运行，你需要确保访问以下网站：https://vstsagenttools.blob.core.windows.net/。 将从此地址下载 TEE 插件。

如果你使用的是自托管代理，并且在下载 TEE 时遇到问题，可以手动安装 TEE：

1. 将 DISABLE_TEE_PLUGIN_REMOVAL 环境或管道变量设置为 true。 此变量可防止代理在签出 TFVC 存储库后移除 TEE 插件。
2. 从 Team Explorer Everywhere GitHub 版本手动下载 TEE-CLC 版本 14.135.0。
3. 将 TEE-CLC-14.135.0 文件夹的内容提取到 <agent_directory>/externals/tee。