TeamCity 2019.1帮助

设置并运行其他构建代理

在开始定制项目和创建构建配置之前,需要配置构建代理 。在继续进行代理程序安装之前,请查看代理程序-服务器通信前提条件部分。

在此页:

先决条件

必要的操作系统和环境权限

在安装之前,请查看“ 软件冲突”部分 。如有任何问题,请确保未使用任何冲突的软件。

请注意,要运行TeamCity构建代理,用于运行代理的环境和用户帐户必须符合以下要求:

共同

代理程序(java)必须

  • 能够打开通过服务器配置的服务器URL的出站HTTP连接serverUrl物业buildAgent.properties文件(通常与您在浏览器中用来查看TeamCity UI的地址相同)。将请求发送到配置的URL下的路径不应受到限制。另请参阅推荐的反向代理设置 。确保代理或服务器计算机上安装的所有防火墙,网络配置和代理(如果有)均符合这些要求。

  • 递归对以下目录具有完全权限(读/写/删除): (自动代理升级和代理工具支持所必需), 和代理系统目录(由workDirtempDirsystemDir中的参数buildAgent.properties文件)

  • 能够启动流程(运行构建)。

  • 能够使用以下父进程出口启动嵌套进程(在代理升级期间使用)

视窗

  • 作为服务登录(作为Windows服务运行)

  • 启动/停止服务(要作为Windows服务运行,代理升级才能正常运行,另请参阅Microsoft KB文章

  • 调试程序(需要执行进程转储功能)

  • 重新启动计算机(代理重新启动功能需要)

  • 为了能够监视作为Windows 服务运行的构建代理的性能 ,启动代理的用户必须是Performance Monitor Users组的成员。

的Linux

  • 用户必须能够运行shutdown命令(用于在云环境中运行时的代理计算机重新启动功能和计算机关闭功能)

  • 使用systemd时,不应杀死主进程出口上的进程(使用RemainAfterExit = yes

与构建相关的权限

构建过程由TeamCity代理启动,因此共享环境,并在TeamCity代理使用的OS用户下执行。确保已相应配置TeamCity代理。有关相关的Windows服务限制,请参阅已知问题

代理服务器数据传输

TeamCity代理通过配置为URL的URL连接到TeamCity服务器。 serverUrl代理属性。这称为单向代理到服务器连接。如果进行了专门配置,TeamCity代理可以使用旧版双向通信 ,这也需要建立从服务器到代理的连接。要查看特定服务器的代理服务器通信是单向还是双向,请导航至“ 代理|代理”。 | “代理摘要”选项卡的“ 详细信息”部分的“ 通信协议”

单向代理到服务器通信

代理通过轮询协议使用单向代理到服务器的连接:代理建立与TeamCity Server的HTTP(S)连接,并定期轮询服务器以获取服务器命令。

建议使用HTTPS进行代理到服务器的通信(请参阅相关的服务器配置说明 )。如果将代理程序和服务器部署到安全环境中,则可以将代理程序配置为使用纯HTTP URL来连接到服务器,因为这样可以减少传输开销。请注意,通过从代理建立的连接到服务器的连接传输的数据包括构建设置,存储库访问凭证和密钥,存储库源,构建工件,构建进度消息和构建日志。如果使用HTTP协议,则可以通过“中间人”攻击来破坏数据。

双向通讯

双向通信是代理程序与服务器之间的传统连接,需要专门启用它(请参见下面的示例)。启用后,它要求代理通过HTTP(或HTTPS)连接到服务器,服务器需要通过HTTP连接到代理。

通过服务器建立的连接传递给代理的数据会通过不安全的HTTP通道传递,因此可能会暴露给任何可能监听服务器和代理之间流量的第三方。此外,由于代理和服务器可以相互发送“命令”,因此可以发送HTTP请求和捕获响应的攻击者从理论上讲可以诱使代理执行任意命令并执行其他具有安全影响的动作。

TeamCity代理使用的通信协议由以下值确定: teamcity.agent.communicationProtocols服务器内部属性 。该属性接受以逗号分隔的协议的有序列表( pollingxml-rpc支持的协议名称),并设置为teamcity.agent.communicationProtocols=polling默认。如果指定了多个协议,则代理将尝试使用此列表中的第一个协议进行连接,如果失败,它将尝试通过列表中的第二个协议进行连接。 polling表示单向协议, xml-rpc -较旧的双向通讯。

更改通讯协议

  • 要更改所有座席的通信协议,请设置TeamCity服务器teamcity.agent.communicationProtocols服务器内部属性 。更改后,所有连接到服务器的代理将使用新设置。要更改现有连接的协议,请重新启动TeamCity服务器。

  • 默认情况下,未配置代理的属性。当代理首次连接到服务器时,它会从TeamCity服务器接收它。要在初始代理配置后更改单个代理的协议,请更改teamcity.agent.communicationProtocols 代理属性中的属性 。代理的属性将覆盖服务器属性。更改后,代理将在完成正在运行的构建(如果有)时自动重新启动。

  • 将版本为2018.1+的TeamCity代理连接到9.1之前的版本的TeamCity服务器时(例如,在升级后回滚之后),将需要更新代理以使用xml-rpc协议(或可以重新安装),以便能够连接到较旧的服务器以执行自我更新过程。

安装其他构建代理

1。使用以下任一选项安装构建代理:

2。安装后,配置代理,在其中指定其名称和TeamCity服务器的地址。 conf/buildAgent.properties文件。

3。启动代理。如果代理似乎无法正常运行,请检查代理日志

当新安装的代理程序首次连接到服务器时,它将出现在Agents页, Unauthorized agents拥有授权权限的管理员/用户可以看到的标签。除非在TeamCity Web UI中得到授权,否则代理将不会运行构建。默认情况下,与服务器在同一计算机上运行的代理是经过授权的。

授权代理的数量受服务器上代理许可证数量的限制。请参阅“ 许可政策”下的更多内容。

通过Windows安装程序进行安装

  1. 在TeamCity Web UI中,导航到“ 代理”选项卡。

  2. 单击“ 安装构建代理”链接,然后选择“ Windows Installer”以下载安装程序。

  3. 在代理上,运行agentInstaller.exe Windows Installer,然后按照安装说明进行操作。

通过Docker Agent映像安装

  1. 在TeamCity Web UI中,导航到“ 代理”选项卡。

  2. 点击Install Build Agents链接,然后选择Docker Agent Image

  3. 请按照打开的页面上的说明进行操作。

通过ZIP文件安装

  1. 确保在代理计算机上正确安装了JDK(JRE)1.8.0_161或更高版本(支持Java 6-10,但建议使用1.8.0_161 +)。

  2. 在代理计算机上,确保JRE_HOME要么JAVA_HOME设置了环境变量(分别指向已安装的JRE或JDK目录)。

  3. 在TeamCity Web UI中,导航到“ 代理”选项卡。

  4. 单击“ 安装构建代理”链接,然后选择“ Zip文件分发”以下载存档。

  5. 将下载的文件解压缩到所需目录。

  6. 导航到\conf目录中,找到名为buildAgent.dist.properties并将其重命名为buildAgent.properties

  7. 编辑buildAgent.properties文件以指定TeamCity服务器URL(建议使用HTTPS,请参阅注释 )和代理名称。有关代理配置的详细信息,请参阅“ 构建代理配置”部分。

  8. 在Linux下,您可能需要授予执行权限bin/agent.sh外壳脚本。

通过Agent Push安装

TeamCity提供的功能允许将构建代理安装到远程主机。当前支持的服务器主机平台和构建代理目标的组合是:

  • 从基于Unix的TeamCity服务器上,只能将构建代理安装到Unix主机(通过SSH)

  • 从基于Windows的TeamCity服务器,可以将构建代理安装到Unix(通过SSH)或Windows(通过psexec)主机

远程主机要求

远程主机有一些要求:

平台

先决条件

的Linux

1。已安装JDK(JRE)6-10( 建议使用1.8.0_161或更高版本 )。JVM应该可以通过JAVA_HOMEJRE_HOME )全局环境变量或位于全局路径中(即不在用户的.bashrc文件中,依此类推)

2。的unzip效用。

3。要么wget要么curl

视窗

1。已安装JDK / JRE 6-10( 建议使用 1.8.0_161或更高版本 )。

2。 Sysinternals psexec.exe在TeamCity服务器上。它必须在路径中可访问。您可以使用管理 |安装。 工具页面。请注意,PsExec将其他要求应用于远程Windows主机(例如,必须可以访问远程主机上的管理共享 )。了解有关PsExec的更多信息。

安装

  1. 在TeamCity Server Web UI中,导航到“ 代理” |“ 代理”代理推送选项卡,然后单击安装代理...。
    如果要对多个目标主机使用相同的设置,则可以使用这些设置创建一个预设 ,并在每次将代理安装到另一个远程主机时都使用该预设

  2. 在“ 安装代理”对话框中,选择一个保存的预设或选择“使用自定义设置”,指定目标主机平台并配置相应的设置。通过SSH将代理推送到Linux系统支持指定为SSH端口参数的自定义端口(默认为22)。预设中指定的端口可以在主机名中覆盖,例如hostname.domain:2222 ,在实际安装代理程序期间。

  3. 您可能需要下载Sysinternals psexec.exe ,在这种情况下,您会看到相应的警告以及指向管理 |链接的链接。您可以在“ 工具”页面上下载它。

您可以在“ 代理程序云”配置文件设置中使用“代理程序推送”预设来将构建代理程序自动安装到已启动的云实例。

启动构建代理

TeamCity构建代理可以手动启动,也可以配置为自动启动。

手动启动

要手动启动代理 ,请运行以下脚本:

  • 对于Windows:\bin\agent.bat start

  • 对于Linux和macOS:\bin\agent.sh start

自动启动

要将代理配置为自动启动 ,请参见相应部分:

  • 视窗
  • Linux :使用以下命令配置守护进程agent.sh start命令启动它并agent.sh stop命令停止它。

  • 苹果系统

Windows下自动启动代理

要在Windows下的计算机启动时自动运行代理,可以将代理设置为作为Windows服务运行,也可以使用另一种自动启动进程的方式。
使用Windows服务方法是最简单的方法,但是Windows将某些约束应用于以这种方式运行的进程。
只要满足所有要求 ,TeamCity代理就可以在Windows服务下可靠地工作,但是配置为在代理上运行的生成过程通常不是这种情况。

这就是为什么仅在所有构建脚本都支持的情况下才建议将TeamCity代理作为Windows服务运行的原因。否则,建议使用特定于操作系统的替代方法来自动启动TeamCity代理。
一种方法是在Windows启动时配置自动用户登录 ,然后配置TeamCity代理启动(通过agent.bat start )(例如,通过Windows Task Scheduler )。

Build Agent作为Windows服务

在Windows中,您可能希望将TeamCity代理作为Windows服务运行,以使其在没有任何用户登录的情况下运行。如果使用Windows代理安装程序,则可以选择在安装向导中安装该服务。

以下说明可用于手动安装Windows服务(例如, .zip代理安装)。还应执行此过程,以在同一台计算机上为第二个及后续代理创建Windows服务。

要安装服务:

  1. 检查服务是否具有所需的名称和ID(请参阅下面的#4,服务名称为TeamCity Build Agent默认情况下)不存在;如果已安装,请将其删除。

  2. 检查wrapper.java.command物业\launcher\conf\wrapper.conf文件在JDK安装目录中包含Java可执行文件的有效路径。您可以使用wrapper.java.command=../jre/bin/java与Windows发行版一起安装的代理。确保指定java.exe文件的路径,且不带引号。

  3. 如果要以用户帐户(推荐)而不是“系统”身份运行代理,请添加wrapper.ntservice.accountwrapper.ntservice.password的属性\launcher\conf\wrapper.conf具有适当凭证的文件

  4. (适用于第二和后续安装)修改\launcher\conf\wrapper.conf文件,以便wrapper.console.titlewrapper.ntservice.namewrapper.ntservice.displaynamewrapper.ntservice.description属性在计算机内具有唯一值。

  5. 跑过\bin\service.install.bat具有足够特权的用户下的脚本来注册新代理服务。确保仅在按照说明进行配置后才第一次启动代理。

要启动服务:

  • /bin/service.start.bat (或使用标准的Windows Services小程序)

要停止服务:

  • /bin/service.stop.bat (或使用标准的Windows Services小程序)

您也可以使用标准Windows net.exe实用程序,用于在安装服务后对其进行管理。
例如(假设默认服务名称):

净启动TCBuildAgent

\launcher\conf\wrapper.conf该文件还可以用于更改代理JVM参数。

用于运行构建代理服务的用户帐户必须具有足够的权限来启动/停止代理服务,如描述上面

在Linux下自动启动代理

要在Linux下的计算机引导上自动运行代理,请使用以下命令配置守护进程agent.sh start命令启动它并agent.sh stop命令停止它。

对于systemd,请参见示例teamcityagent.service配置文件:

[Unit]描述= TeamCity Build Agent After = network.target [Service]类型= oneshot用户= teamcityagent组= teamcityagent ExecStart = / home / teamcityagent / agent / bin / agent.sh start ExecStop =-/ home / teamcityagent / agent / bin / agent.sh stop#支持代理升级,因为主进程启动子进程并退出,然后退出RemainAfterExit = yes#支持代理升级,因为主进程在升级过程中获取SIGTERM,并且映射到退出代码143 SuccessExitStatus = 0 143 [Install] WantedBy = default.target

对于init.d ,请参考示例过程:

1。导航到服务启动/停止服务脚本目录:

cd /etc/init.d/

2。打开构建代理服务脚本:

须藤vim buildAgent

3。将以下内容粘贴到文件中:

#!/ bin / sh ### BEGIN INIT INFO#提供:TeamCity Build Agent#必需的开始:$ remote_fs $ syslog#必需的停止:$ remote_fs $ syslog#缺省的开始:2 3 4 5#缺省的停止:0 1 6#简短描述:在引导时启动构建代理守护程序#描述:启用守护程序提供的服务。### END INIT INFO#提供正确的用户名:USER =“ agentuser”大小写“ $ 1”,开始)su-$ USER -c“ cd BuildAgent / bin; ./agent.sh start” ;;停止)su-$ USER -c“ cd BuildAgent / bin; ./agent.sh停止” ;; *)回显“使用开始/停止”出口1 ;; esac出口0

4。设置执行文件的权限:

须藤chmod 755 buildAgent

5,建立链接以使用适当的工具在计算机启动和重新启动时启动代理服务:

  • 对于Debian / Ubuntu:

sudo update-rc.d buildAgent默认
  • 对于Red Hat / CentOS:

sudo chkconfig buildAgent在

在macOS下自动启动代理

对于macOS / Mac OS X,TeamCity提供了在构建用户登录时自动加载构建代理的功能。

LaunchAgent方法

通过配置自动构建代理启动LaunchAgent , 跟着这些步骤:

1。通过Mac在Mac上安装构建代理buildAgent.zip

2。准备conf/buildAgent.properties文件(至少在此设置代理名称)。

3。确保下的所有文件buildAgent目录归拥有者所有your_build_user以确保适当的代理升级过程。

4。通过以下命令加载构建代理:

mkdir buildAgent / logs#目录应在your_build_user用户下创建sh buildAgent / bin / mac.launchd.sh load

在下面运行这些命令your_build_user帐户。

您必须等待几分钟 ,构建代理才能从TeamCity服务器自动升级。您可以在日志中查看该过程:

tail -f buildAgent / logs / teamcity-agent.log

5,当构建代理升级并成功连接到TeamCity服务器后,停止代理:

sh buildAgent / bin / mac.launchd.sh卸载

6。从TeamCity服务器升级构建代理后,复制buildAgent/bin/jetbrains.teamcity.BuildAgent.plist归档到$HOME/Library/LaunchAgents/目录。

7。配置您的Mac系统自动登录的用户打造,如所描述这里

8。重启。

在系统启动时,构建用户应自动登录,并且构建代理应启动。

要快速检查构建代理程序是否正在运行,请使用以下命令:

launchctl列表| grep BuildAgent 69722 0 jetbrains.teamcity。BuildAgent

在Mac OS上配置第二个Build Agent

如果要启动多个构建代理,请通过以下更改重复安装和启动构建代理的过程:

  • 在另一个目录中安装第二个构建代理。

  • conf/buildAgent.properties指定其他代理名称。

  • 别跑buildAgent/bin/mac.launchd.sh ;代替
    • 创建副本$HOME/Library/LaunchAgents/jetbrains.teamcity.BuildAgent.plist归档为$HOME/Library/LaunchAgents/jetbrains.teamcity.BuildAgent2.plist

    • 编辑$HOME/Library/LaunchAgents/jetbrains.teamcity.BuildAgent2.plist文件并设置以下参数:
      • Label参数jetbrains.teamcity.BuildAgent2

      • WorkingDirectory参数到第二个构建代理主目录的正确路径

    • 使用命令启动第二个代理launchctl load $HOME/Library/LaunchAgents/jetbrains.teamcity.BuildAgent2.plist

要检查两个构建代理程序是否都在运行,请使用以下命令:

launchctl列表| grep BuildAgent 70599 0 jetbrains.teamcity。BuildAgent2 69722 0 jetbrains.teamcity。BuildAgent

停止构建代理

要手动停止代理 ,请运行\agent带一个脚本stop参数。

使用stop请求在当前构建完成后停止。
使用stop force请求立即停止(如果构建正在代理上运行,它将被突然停止(取消))。
在Linux下,您还有另外一种选择stop kill杀死代理程序。

如果代理程序在连接控制台的情况下运行,则您也可以在控制台中按Ctrl + C组合键以停止代理程序(如果正在运行内部版本,它将被取消)。

在Mac OS上停止代理服务

如果构建代理已作为LaunchAgent服务,可以使用launchctl效用:

launchctl卸载$ HOME / Library / LaunchAgents / jetbrains.teamcity。BuildAgent.plist#或launchctl删除jetbrains.teamcity。BuildAgent

配置Java

TeamCity构建代理是一个Java应用程序,需要JDK 8-10版本才能工作。OpenJDK 8(例如,通过AdoptOpenJDK )1.8.0_161或更高版本,建议使用32位。还支持Oracle Java 8

生成代理包含两个过程:

  • 代理启动器–启动代理进程的Java进程

  • 代理-构建代理的主要过程;作为代理启动器的子进程运行

(Windows) .exe TeamCity发行版与OpenJDK 1.8.0_161捆绑在一起。
如果运行TeamCity代理的早期版本,则需要重复安装代理以更新JVM。

建议使用x32位JDK(而非JRE)。对于某些生成器,例如IntelliJ IDEA项目 ,Java InspectionsDuplicates ,都需要JDK。如果没有Java构建,则可以安装JRE而不是JDK。
可以使用x64位Java,但您可能需要将-Xmx主代理进程的内存值(参见配置生成代理启动属性和一致好评部分服务器)。

为了.zip代理安装,您需要安装相应的Java版本。通过以下方式使其可用PATH或在以下位置之一可用:

  • /jre目录

  • 在指向的目录中TEAMCITY_JREJAVA_HOME要么JRE_HOME环境变量(检查是否仅定义了其中一个变量)。

  • 如果您打算通过Windows服务运行代理,请确保设置wrapper.java.command物业\launcher\conf\wrapper.conf文件到Java可执行文件的有效路径

在代理上升级Java

如果您尝试启动代理,但无法在任何默认位置中找到所需的Java版本(当前为Java 6),则代理将报告启动错误,进程将无法启动,并且代理在TeamCity UI中将显示为断开连接。

如果构建代理使用的Java版本低于Java 8,则您将在代理页面上看到相应的警告,并在Web UI中看到运行状况项

建议使用最新的Java 8、32位版本。OpenJDK 8(例如,通过AdoptOpenJDK )1.8.0_161或更高版本,建议使用32位。还支持Oracle Java 8

要在代理上更新Java,请执行以下一项操作:

  • 如果TeamCity UI中的座席详细信息页面显示具有相应操作的Java版本注释,则可以切换到使用较新的Java:如果在座席上检测到与当前位数相同的适当Java版本,则座席页面将提供自动切换为使用该Java的操作。在操作调用后,使用新的Java重新启动代理进程(一旦代理变为空闲,即完成当前构建,则完成)。

  • (Windows)由于构建代理Windows安装程序与必需的Java捆绑在一起,因此您可以使用Windows安装程序手动重新安装该代理( .exe )从TeamCity服务器“ 代理”页面获得。请参阅安装说明 。在安装更新的代理之前,请先卸载该代理的先前版本,这一点很重要: Uninstall.exe在代理主目录中,清除所有“ 删除... ”复选框,然后单击“ 卸载”

  • 在代理上将所需的Java安装到标准位置之一,然后重新启动代理-代理随后应检测到它并提供操作以在Web UI中使用较新的Java(请参见上文)。

  • 在代理上安装所需的Java并将代理配置为使用它。

在同一台计算机上安装多个构建代理

如果计算机能够同时运行多个构建,则可以在同一台计算机上安装多个TeamCity代理。但是,我们建议每(虚拟)台计算机运行一个代理,以最大程度地减少构建的交叉影响并使构建更可预测。当安装多个代理时,建议将它们安装在不同的OS用户下,以使用户级资源(例如Maven / Gradle / NuGet本地工件高速缓存)不会冲突。

TeamCity平等对待所有代理,无论它们是安装在同一台机器上还是安装在不同机器上。
在同一台计算机上安装多个TeamCity构建代理时,请考虑以下事项:

  • 在此类代理上运行的构建不应与任何资源(公用磁盘目录,OS进程,OS临时目录)冲突。

  • 根据硬件和内部版本,您可能会体验到内部版本性能下降。同时运行多个构建时,请确保没有磁盘,内存或CPU瓶颈。

  • 建议将代理设置为在不同的OS用户下运行

安装一个代理后,可以按照常规安装过程安装其他代理(请参阅下面的Windows服务例外),但请确保:

  • 代理安装在单独的目录中。

  • 代理商具有特色workDirtempDir目录中的buildAgent.properties文件。

  • 的值nameownPort的性质buildAgent.properties是独一无二的

  • 没有在代理上运行的内部版本指定绝对签出目录。

确保没有指定绝对检查目录的构建配置(或者,确保此类构建配置启用了“ clean checkout ”选项,并且它们不能并行运行)。

通常,对于新的代理程序安装,您只需将现有代理程序的目录复制到新位置即可, tempworklogssystem目录。然后,修改conf/buildAgent.properties与新nameownPort价值观。清除(删除或删除值) authorizationToken属性,并确保workDirtempDir是亲戚/不与其他特工发生冲突。

如果要在Mac OS上安装第二个构建代理,请参见此处的其他详细信息。

如果您使用Windows Installer安装其他代理程序并希望将代理程序作为服务运行,则将需要执行手动步骤,因为安装程序不支持在同一台计算机上将第二个代理程序作为服务安装:现有服务会被覆盖(另请参阅功能请求 )。
为了安装第二个代理,建议手动安装第二个代理(使用.zip代理分发)。您可以使用Windows代理安装程序,并且不选择服务安装,但是这种方式将丢失初始安装的代理的卸载选项。
安装第二个代理后,如上一节所述为其注册一个新服务。


也可以看看:

概念生成代理