在 macOS 上部署生成和发布代理

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

重要

本文提供有关将 3.x 代理软件与 Azure DevOps Services 配合使用的指导。 如果使用 Azure DevOps Server 或 TFS，请参阅自承载 macOS 代理 (代理版本 2.x) 。

若要生成和部署 Xcode 应用或 Xamarin.iOS 项目，至少需要一个 macOS 代理。 此代理还可以生成和部署 Java 和 Android 应用。

注意

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

如果你已经知道代理是什么及其工作原理，请随时跳转到以下部分。 但是，如果想要了解其用途及其工作方式的更多背景信息，请参阅 Azure Pipelines 代理。

如果要从 Subversion 存储库生成，则必须在计算机上安装 Subversion 客户端。

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

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

代理控制的文件夹应限制为尽可能少的用户，并且这些文件夹包含可解密或外泄的机密。

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

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

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

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

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

在主页中，打开个人资料。 转到安全详细信息。

创建个人访问令牌。

注意

如果要配置部署组代理，或者在注册 VM 环境资源时看到错误，则必须将 PAT 范围设置为 “所有可访问的组织”。

在主页中，打开用户设置，然后选择“个人访问令牌”。

创建个人访问令牌。

对于范围，选择 “ (读取的代理池”，管理) 并确保清除所有其他框。 如果是 部署组 代理，则对于范围，请选择“ 部署组 (读取、管理) 并确保清除所有其他框。

选择“创建新的个人访问令牌”窗口窗口底部的“显示所有范围”，查看范围的完整列表。

复制令牌。 配置代理时，将使用此令牌。

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

用户是 Azure DevOps 组织所有者、TFS 还是Azure DevOps Server管理员？ 请在此处停止，你拥有权限。

否则：

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

选择 “Azure DevOps， 组织设置”。

选择 “代理池”。

选择 “Azure DevOps” “集合设置”。

选择 “代理池”。

选择 “Azure DevOps” “集合设置”。

选择 “代理池”。

导航到项目，然后选择 “设置 ” (齿轮图标) >“代理队列”。

选择 “管理池”。

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

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

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

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

注意

如果看到如下消息：很抱歉，无法添加标识。请尝试其他标识。你可能为组织所有者、TFS 或Azure DevOps Server管理员执行了上述步骤。 无需执行任何操作;你已具有管理代理队列的权限。

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

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

选择 “Azure DevOps， 组织设置”。

选择 “代理池”。

选择 “Azure DevOps” “集合设置”。

选择 “代理池”。

选择 “Azure DevOps” “集合设置”。

选择 “代理池”。

导航到项目，然后选择 “设置 ” (齿轮图标) >“代理队列”。

选择 “管理池”。

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

在“ 获取代理 ”对话框中，单击“ macOS”。

单击“下载”按钮。

遵照页面上的说明操作。

清除 tar 文件上的扩展属性： xattr -c vsts-agent-osx-x64-V.v.v.tar.gz。

将代理解压缩到所选目录。 cd 到该目录并运行 ./config.sh。 请确保目录的路径不包含空格，因为工具和脚本并不总是正确地转义空格。

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

Azure DevOps Server：https://{your_server}/tfs

选择 “PAT”，然后将 创建的 PAT 令牌 粘贴到命令提示符窗口中。

注意

使用 PAT 作为身份验证方法时，PAT 令牌仅用于代理的初始配置。 有关详细信息，请参阅 与 Azure Pipelines 或 TFS 通信。

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

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

如果已将代理作为服务运行， 请卸载该服务。

运行代理。

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

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

对于配置为以交互方式运行的代理，可以选择让代理只接受一个作业。 若要在此配置中运行，请执行以下操作：

此模式下的代理将只接受一个作业，然后正常向下旋转 (在Azure 容器实例) 等服务上运行很有用。

我们提供了脚本 ./svc.sh ，用于作为启动的 LaunchAgent 服务运行和管理代理。 配置代理后，将生成此脚本。 该服务有权访问 UI 以运行 UI 测试。

注意

如果你更喜欢其他方法，则可以使用任何你喜欢的服务机制。 请参阅 服务文件。

在以下部分中，这些令牌将被替换：

{agent-name}

{tfs-name}

例如，配置了一个代理， (如上所示，) 名称 our-osx-agent为 。 在以下示例中， {tfs-name} 将为：

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

TFS：本地 TFS AT 服务器的名称。 例如，如果连接到 http://our-server:8080/tfs，则服务名称将为 vsts.agent.our-server.our-osx-agent

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

命令：

此命令创建指向 ./runsvc.sh的已启动 plist。 此脚本在以下) 设置环境 (更多详细信息，并启动代理的主机。

命令：

输出：

如果服务正在运行，则左侧数字为 pid。 如果第二个数字不为零，则表示出现问题。

命令：

输出：

如果服务正在运行，则左侧数字为 pid。 如果第二个数字不为零，则表示出现问题。

命令：

输出：

卸载前应停止。

命令：

通常，代理服务仅在用户登录后运行。 如果希望代理服务在计算机重启时自动启动，可以将计算机配置为在启动时自动登录和锁定。 请参阅 将 Mac 设置为在启动期间自动登录 - Apple 支持。

注意

有关详细信息，请参阅 终端极客：更安全地使用自动登录 博客。 该博客中提到的 .plist 文件可能不再在源中可用，但可以在此处找到一个副本： Lifehacker - 在登录之前使 OS X 加载桌面。

配置服务时，需要为当前登录用户快照一些有用的环境变量，例如 PATH、LANG、JAVA_HOME、ANT_HOME 和 MYSQL_PATH。 如果需要 (更新变量，例如，在安装一些新软件后) ：

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

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

编辑 runsvc.sh。

将以下行替换为说明：

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

创建 .plist 服务文件：

例如：

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

./svc.sh start 通过读取 .service 文件查找服务，该文件包含上述 plist 服务文件的路径。

我们提供了脚本 ./svc.sh ，方便你以启动的 LaunchAgent 服务的形式运行和管理代理。 但是，你可以使用你喜欢的任何类型的服务机制。

可以使用上面描述的模板来帮助生成其他类型的服务文件。 例如，如果不需要 UI 测试且不想配置自动登录和锁定，请修改模板以生成作为启动守护程序运行的服务。 请参阅 Apple 开发人员库：创建启动守护程序和代理。

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

使用与现有代理相同的名称配置代理时，系统会询问是否要替换现有代理。 如果回答 Y，请确保删除代理 (看到下面要替换) 。 否则，在发生几分钟的冲突后，其中一个代理将关闭。

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

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

删除代理。

输入凭据。

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

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

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

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

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

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

如果未通过运行 命令将其删除，请手动从代理池中删除代理。

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

指定代理名称 () 的任何特定唯一名称，如果重新配置后此代理出现在代理池中，则检查。

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

运行 whoami /user 命令以获取 。 打开 Registry Editor 并按照路径操作：

检查是否存在 VSTSAgent 密钥。 如果此密钥存在，请将其删除，然后通过运行.\config.cmd命令 (来关闭Registry Editor并配置代理，而无需从代理文件夹中) 。 在回答问题Enter Restart the machine at a later time?之前，请再次打开 Registry Editor ，检查键VSTSAgent是否已出现。 按 Enter 以回答问题，并检查键是否VSTSAgent在重启计算机后保持其位置。

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

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

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

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

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

若要了解其他选项，请执行以下操作：

该帮助提供有关身份验证替代项和无人参与配置的信息。

代理的功能在池中编录和播发，以便只为其分配可以处理的生成和发布。 请参阅 生成和发布代理功能。

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

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

重要

功能包括代理运行时设置的所有环境变量和值。 如果这些值中的任何值在代理运行时发生更改，则必须重新启动代理才能获取新值。 在代理上安装新软件后，必须重启代理才能在池中显示新功能，以便运行生成。

如果要将环境变量排除为功能，可以通过设置一个环境变量 VSO_AGENT_IGNORE 来指定它们，其中包含逗号分隔的要忽略的变量列表。

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

选择 “Azure DevOps， 组织设置”。

选择 “代理池”。

选择 “Azure DevOps” “集合设置”。

选择 “代理池”。

选择 “Azure DevOps” “集合设置”。

选择 “代理池”。

导航到项目，然后选择 “设置 ” (齿轮图标) >“代理队列”。

选择 “管理池”。

单击包含代理的池。

确保已启用代理。

导航到“功能”选项卡：

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

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

选择“ 功能 ”选项卡。

注意

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

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

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

选择“ 功能 ”选项卡。

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

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

选择“ 功能 ”选项卡。

选择所需的代理，然后选择“ 功能 ”选项卡。

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

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

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

从可以访问 Internet 的计算机，从 Azure Pipelines 代理 GitHub 版本页下载 (.zip 或 .tar.gz 表单) 的代理包文件的最新版本。

使用所选方法（如 U 盘、网络传输等) ） (将下载的包文件传输到每个Azure DevOps Server应用程序层。 将代理文件放在 文件夹下 %ProgramData%\Microsoft\Azure DevOps\Agents 。

你已完成所有设置！ 现在，每当更新代理时，Azure DevOps Server都将使用本地文件。 每个代理在运行需要较新版本的代理的任务时都会自动更新自身。 但是，如果要手动更新某些代理，请右键单击池，然后选择“ 更新所有代理”。

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

选择 “Azure DevOps， 组织设置”。

选择 “代理池”。

选择 “Azure DevOps” “集合设置”。

选择 “代理池”。

选择 “Azure DevOps” “集合设置”。

选择 “代理池”。

导航到项目，然后选择 “设置 ” (齿轮图标) >“代理队列”。

选择 “管理池”。

单击包含代理的池。

确保已启用代理。

导航到“功能”选项卡：

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

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

选择“ 功能 ”选项卡。

注意

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

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

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

选择“ 功能 ”选项卡。

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

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

选择“ 功能 ”选项卡。

选择所需的代理，然后选择“ 功能 ”选项卡。

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

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

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

从可以访问 Internet 的计算机，从 Azure Pipelines 代理 GitHub 版本页下载 (.zip 或 .tar.gz 表单) 的代理包文件的最新版本。

使用所选方法（如 U 盘、网络传输等) ） (将下载的包文件传输到每个Azure DevOps Server应用程序层。 将代理文件放在 文件夹下 %ProgramData%\Microsoft\Azure DevOps\Agents 。

你已完成所有设置！ 现在，每当更新代理时，Azure DevOps Server都将使用本地文件。 每个代理在运行需要较新版本的代理的任务时都会自动更新自身。 但是，如果要手动更新某些代理，请右键单击池，然后选择“ 更新所有代理”。

Apple 开发人员库：创建启动守护程序和代理

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

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

IPv4 范围

IPv6 范围

注意

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

使用自签名证书运行代理

在 Web 代理后面运行代理

如果要以交互方式运行代理，请参阅 以交互方式运行中的重启说明。 如果以服务的形式运行代理，请按照 “停止 ”步骤操作，然后 启动 代理。

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

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

IPv4 范围

IPv6 范围

注意

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

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

网站设置和安全性

其中某些功能仅在 Azure Pipelines 上可用，在本地尚不可用。 如果你已升级到最新版本的 TFS，则可在本地使用这些功能。

如果要使用 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：