安装并启动 TeamCity 代理
TeamCity 构建代理 是一种软件，它侦听来自 TeamCity 服务器的命令并启动实际的构建过程。 一个生产环境下的 TeamCity 设置需要在专用机器上安装额外的构建代理。 在此之前，请确保阅读关于 代理服务器通讯、 系统要求、 冲突软件以及 安全性的注释。
如果您安装了与 Tomcat servlet 容器捆绑的 TeamCity ，或使用 TeamCity 的 Windows 安装程序，服务器和一个构建代理都会安装在同一台机器上。 这并不是 生产环境 推荐的配置方式，因为存在 安全问题。 此外，构建过程可能会降低网络用户界面的响应速度，从而影响整体 TeamCity 服务器的运行效率。
常见构建代理概念
代理是一种软件，通常用于检出源代码、下载其他构建的工件并运行构建过程。 它的安装和配置与 TeamCity 服务器是分开的。
代理可以安装在物理机器和 云托管的虚拟机器上。
代理可以运行任何 兼容的构建配置的构建。 每个代理可以有一个独特的环境：架构、操作系统、已安装的工具等。 这些属性定义了代理可以运行哪些构建。
一个代理可以一次运行一个构建。 代理的数量基本上限制了并行构建的数量以及运行构建过程的环境数量。
为了确保代理的平稳运行，您需要定期更新从可执行文件或归档文件安装的代理的核心软件和工具。 例如，在将 TeamCity 服务器升级到较新版本后，从现有虚拟机镜像启动的所有云代理需要一些时间来更新（此过程会自动进行，但会延迟排队构建开始的时间）。 为了确保您的代理始终运行最新的软件，请将它们作为 Docker 容器运行。
由于构建可以在 Docker 或 Podman 容器中运行，代理机器的操作系统本身并不限制代理与项目的兼容性。 换句话说，您可以在 Windows 代理上运行特定于 Linux 的任务，反之亦然。
TeamCity 构建代理包含 两个进程 ：代理启动器（一个启动代理进程的 Java 进程）和代理（作为代理启动器的子进程运行的构建代理的主要进程）。
构建代理状态
构建代理的状态由三对相互独立的状态描述。 代理始终从每对状态中取一个值，因此这些状态会组合在一起：新安装的代理通常是 已连接、 未授权且 已启用 ；例如，也可以有一个为了维护而从轮转中移除的代理，它 已连接、 已授权 ，但 已禁用。
只有在同时已连接、已授权且已启用时，代理才会运行构建。
- 已连接 / 已断开连接
TeamCity 会自动设置此状态。 如果代理已在服务器上注册并响应服务器命令，则代理为 connected ；否则为 已断开连接。
无法从 UI 更改此状态 — 断开连接的代理表示代理进程未运行或无法访问服务器。 先查看代理自身的日志和
serverUrl属性，该属性位于其 配置文件中。授权是您对服务器可以使用此机器的显式确认。 新代理会保持 未授权 状态，直到在 支持人员 页面上对其授权为止，包括安装在与 TeamCity 服务器相同机器上的代理。 云代理的行为有所不同：只要有可用的代理许可证，TeamCity 会在它们连接后立即自动授权。
未授权的代理无法运行构建。 此外，TeamCity 完全不会与未授权代理所在的机器通信：无法查看其 日志 、转储其线程、打开 交互式终端以及重启该机器。 这可以防止服务器与尚未经过验证的机器通信，因此只有在知道连接的是哪台机器时，才授权代理。
授权还会管理许可证：已授权代理的数量不能超过服务器上的 代理许可证数量。 取消授权代理会释放其许可证以供另一个代理使用，这就是在多台机器之间轮换使用有限许可证池的方式。 如需提高上限，请购买额外许可证。
- 已启用/已禁用
启用和禁用代理可控制构建流向仍受信任和管理的机器。 可 在 UI 中切换此状态；对于云代理，对应的操作是 禁用以进行维护。
TeamCity 只会把排队的构建以分布式方式分配给 已启用 代理。 禁用代理不会停止当前正在该代理上运行的构建，因此可以禁用一台机器，让它先完成工作，然后再将其离线。
已禁用 代理仍会运行显式分配给它的构建，例如通过 自定义构建。 因此，禁用代理通常用于将代理从 构建网格中移出，并在其上重现特定于代理的问题，而不会受到常规构建的干扰。
连接到服务器的所有代理都必须具有唯一名称。
管理代理需要特定权限。 有关更多信息，请参见 管理角色和权限。
检查代理状态
除了 支持人员 页面外，还可以通过 TeamCity CLI 或 REST API 读取代理状态。 这是审核代理群的实用方式 — 例如，查找在大规模部署后已连接但仍在等待授权的代理。
要使用 CLI 列出代理，请使用这三种状态的任意组合来设置筛选器：
要按 ID 或名称检查单个代理：
REST API 中的相同查询使用 agents 定位器：
单个代理的响应会将这三种状态 Exposed 为特性：
代理服务器数据传输
一个 TeamCity 代理通过配置为 serverUrl 代理属性的 URL 连接到 TeamCity 服务器。 这被称为单向 agent-to-server （代理到服务器）连接。
代理使用单向代理至服务器连接通过轮询协议：代理建立一个 HTTP(S) 连接到 TeamCity 服务器，并定期轮询服务器以获取服务器命令。
将本地代理连接到 TeamCity 服务器
云代理
在云中托管 TeamCity 代理允许您实现高度可扩展的解决方案，新代理可以按需启动，当没有构建需要处理时关闭。 有关云托管 TeamCity 代理的更多信息，请参阅 在云中托管构建代理 部分。
代理升级
当需要时，TeamCity 代理将自动升级。 通常，发生这种情况是因为：
服务器已 升级
请注意，更新代理插件和在服务器升级后接收新文件可能会触发代理重启，以使更改生效。 如果代理在具有 足够权限的用户帐户下运行，所有重启将自动发生，无需您的输入。
代理优先级
TeamCity 会根据多项标准选择代理，包括 CPU 数量、过去的性能和代理来源（本地自托管代理优先级最高，其次是 云代理， Kubernetes 执行器 pod的优先级最低）。 可以通过设置整数 teamcity.agent.priority 属性（–10,000 到 10,000 ，默认值： 0 ）来重写此逻辑。
对于 AWS 托管的云代理 ，可以在云镜像设置页面上设置此属性：
对于其他代理类型，请在 <TeamCity_Agent_Home>/conf/buildAgent.properties文件中添加以下行：
teamcity.agent.priority=54
请注意，TeamCity 仅在代理完全启动并连接到服务器后才会识别代理属性。 因此，非 EC2 云代理的优先级仅适用于活动/运行中的实例。 目前，只有 EC2 云镜像在实例启动之前传递代理优先级。
远程调试代理
在代理安装、连接并 授权后，可以直接从 TeamCity UI 调用此代理所在机器的终端。 这项功能让您可以远程查看代理日志，检查已安装的软件，并对特定的代理问题进行调试。
终端不适用于未经授权的代理：TeamCity 不会与尚未被设置为可信任的机器通信，并且会为此类代理隐藏 打开终端 按钮。 要调试授权失败的云实例，请改用云提供商自己的工具——例如，从 AWS 控制台连接到 EC2 实例。
要调用终端，请点击 TeamCity 页眉中的 支持人员 ，选择所需的代理，然后点击 打开终端。
您也可以从 构建结果页面 打开此终端。 在这种情况下，终端会在 checkout directory 中打开，而不是在 $HOME 文件夹中打开。
当终端打开时，您可以点击 在单独的标签页中打开 链接以获得更大的客户端区域。
打开终端 按钮适用于所有类型的代理机器（Linux、Windows 和 macOS），并以启动 TeamCity 代理的同一用户身份调用终端。
为了确保您在进行维护时构建代理处于空闲状态，请禁用它，但不要停止它，因为终端会话需要一个 运行中的 构建代理。 停止构建代理会冻结之前打开的终端标签页，阻止用户输入新的命令。
对于在空闲一段时间后会自动终止的云代理，您可能需要点击 “禁用以进行维护……”按钮，以保持代理的机器运行，并防止其在您仍在调查构建问题时关闭。
打开终端 链接仅对 角色权限包括 "调用交互式代理终端"权限的用户可见。 应授予此权限给所有与相应 agent 的 代理池 关联的项目。 拥有 "Project Administrator" 和 "System Administrator" 角色的用户默认具有此权限。 作为额外的预防措施，每个打开终端的请求都会作为新的 "Agent actions | Connect to agent" 活动写入 审核日志。