TeamCity 的持续集成体系中，构建代理（Build Agent）是真正执行编译、测试、打包的执行单元。服务器只负责调度和展示，所有实际的构建压力都落在代理机器上。本文以 Windows Server 为例，完整讲解如何安装、配置并以 Windows 服务方式运行 TeamCity 构建代理，同时整理部署过程中最常见的几个坑。
一、安装前的准备与代理工作机制
在动手安装之前，先弄清楚代理和服务器之间的通信方式，后面排查网络问题时会轻松很多。TeamCity 代理默认通过 HTTP 协议与服务器通信，代理侧监听的默认端口是 9090，用于服务器反向推送构建指令。也就是说，数据流向有两个：代理主动通过 serverUrl 向服务器注册和轮询任务，服务器则通过代理的 9090 端口下发构建命令。如果代理机器开启了防火墙，9090 端口必须放行，否则代理会显示为已连接但无法接收构建任务，这是新手最容易被误导的现象。
环境方面需要确认几点：Windows Server 版本建议 2016 及以上；已安装合适版本的 JDK（TeamCity 新版本要求 JDK 8 或 11，具体以官方文档对应版本为准）；磁盘空间至少预留 20GB 给构建检出目录和工作目录；代理机器与服务器机器的时间偏差不要超过几分钟，否则可能引起鉴权异常。提前把这些条件确认好，能省掉大部分安装后的返工。
二、使用 MSIV 安装包部署代理
登录 TeamCity 的 Web 界面，进入 Agents 页面，点击 Install Agents 按钮下载 Windows 平台的 MSI 安装包。推荐使用 MSI 方式安装，因为它会自动注册 Windows 服务，开机自启、崩溃恢复都不需要额外配置。双击安装包后，安装向导会依次询问安装目录（默认为 C:\TeamCity\BuildAgent）、代理监听端口以及 Windows 服务运行账户。
服务账户的选择值得斟酌。默认安装会使用本地系统账户（Local System），权限很大但对网络资源访问有时反而受限。如果构建过程需要访问域内共享目录或以特定域账户身份执行签出、部署操作，建议在安装完成后把服务登录账户改为对应的域账户，格式为 DOMAIN\username，并在本地安全策略中授予该账户作为服务登录的权限。修改位置在服务的属性对话框的登录选项卡中，或在服务管理器中通过命令完成：
sc config TCBuildAgent obj= DOMAIN\builduser password= YourPasswordHere sc failure TCBuildAgent reset= 86400 actions= restart/60000/restart/60000/restart/60000
第二条命令配置了失败自动重启策略，代理服务因构建任务异常退出时会在 60 秒后自动拉起，对保持流水线稳定很有帮助。
三、命令行方式安装与关键配置文件
如果希望更灵活地控制安装过程，可以下载代理的 zip 压缩包手动部署。解压到目标目录例如 C:\TeamCity\BuildAgent 后，核心配置全部集中在一个文件里：C:\TeamCity\BuildAgent\conf\buildAgent.properties。这个文件是纯文本，用记事本就能编辑，几个关键项如下：
serverUrl=http://tcserver.example.internal:8111/ name=win-build-agent-01 ownPort=9090 workDir=C:\\TeamCity\\BuildAgent\\work tempDir=C:\\TeamCity\\BuildAgent\\temp authorizationToken=对应令牌粘贴到这里
serverUrl 必须填写代理机器能够实际访问到的服务器地址。如果服务器在负载均衡器或反向代理后面，这里要写代理可达的内部地址而不是公网地址，否则会出现注册成功但无法通信的诡异问题。ownPort 是代理自身的监听端口，多代理共存于同一台机器时需要各不相同。authorizationToken 在代理首次连接服务器后，从服务器的 Agents 页面中对应条目里复制过来填入，完成授权绑定。
配置完成后，执行服务安装脚本将其注册为 Windows 服务：
cd C:\TeamCity\BuildAgent\bin service.install.bat service.start.bat
对应地，卸载服务使用 service.stop.bat 和 service.remove.bat。安装脚本内部依赖 Tomcat 提供的 tomcatX.exe 程序，确保 bin 目录下的可执行文件没有被杀毒软件误删，否则服务会安装成功但无法启动。
四、常见问题排查
第一个高频问题是代理界面上一直显示 Unauthorized。这属于正常流程，新代理首次连接后需要在服务器端手动授权：进入 Agents 页面的 Unauthorized 分类，点击对应代理的 Authorize 链接即可。如果授权后又变回未授权状态，通常是 serverUrl 或 authorizationToken 配置有误，检查 buildAgent.properties 中是否有残留的旧令牌。
第二个问题是代理显示 disconnected 或者服务器提示无法连接到代理的 9090 端口。排查顺序建议是：先在代理机器上执行 netstat -ano | findstr 9090 确认端口处于监听状态；再检查 Windows 防火墙入站规则，必要时手动添加放行规则：
netsh advfirewall firewall add rule name="TeamCity Agent" dir=in action=allow protocol=TCP localport=9090
若代理在云环境中，还需检查安全组配置。第三个问题是服务启动失败，事件查看器中报 Java 相关错误，多半是 JDK 版本不匹配或 JAVA_HOME 环境变量指向错误，可以在 C:\TeamCity\BuildAgent\conf\buildAgent.properties 中显式指定 env.JAVA_HOME 变量，或者编辑 bin 目录下的启动脚本强制指定 JVM 路径。日志文件位于 C:\TeamCity\BuildAgent\logs\teamcity-agent.log，遇到疑难问题时先看这里，绝大多数异常都能从日志中找到直接线索。
五、代理环境的后续调优
代理跑起来之后，还有几项值得做的优化。一是通过 buildAgent.properties 的 env.PATH 和 env.* 系列变量为构建注入特定环境，避免污染系统全局环境变量；二是定期清理 work 目录下的旧构建产物，磁盘占满会导致所有构建随机失败；三是在服务器端为代理合理分配兼容性需求，例如限定某代理只服务特定项目，避免长流水线互相排队。做好这些细节，Windows 平台上的 TeamCity 构建环境就能长期稳定运行了。
TeamCity构建代理Windows Server修改时间：2026-09-08 05:40:28