TeamCity Agent 配置完整教程（配合 Docker Compose 快速部署）
在《使用 Docker Compose 从零部署 TeamCity + PostgreSQL（详细新手教程）》中，我们成功部署了 TeamCity Server 和数据库服务。但要真正运行构建任务，还需要至少一个 Build Agent（构建代理）。
本教程将继续补充，教你如何配置 TeamCity Agent，确保构建任务能够正常执行。
一、什么是 TeamCity Agent？
TeamCity 构建系统采用 主从架构：
- Server：管理构建配置、查看状态、处理 UI 界面
- Agent：真正执行构建脚本，比如编译代码、运行测试、部署项目
每个 Agent 启动后需向 Server 注册并获得授权，之后才能参与构建任务。
二、添加 Agent 到 Docker Compose
1. 修改 docker-compose.yml
在已有的 Compose 配置中添加如下服务：
services:# TeamCity 服务teamcity-server:...# 数据库postgres:...teamcity-agent:image: jetbrains/teamcity-agent:latestcontainer_name: teamcity-agentdepends_on:- teamcity-serverenvironment:- SERVER_URL=http://teamcity-server:8111volumes:- /home/teamcity/agent:/data/teamcity_agent/confuser: "1000:1000"restart: unless-stoppedmem_limit: 4gcpus: 2.0
⚠️ 如果已经其他方式部署TeamCity服务，可删除
teamcity-server和postgres，并把- SERVER_URL=http://teamcity-server:8111修改为TeamCity服务访问地址
2. 创建 agent 配置目录
sudo mkdir -p /home/teamcity/agent
sudo chown -R 1000:1000 /home/teamcity/agent
这将用于存储 agent 的配置数据（授权信息等）。
3. 启动服务
docker compose up -d
此时 Agent 会尝试连接 TeamCity Server 并自动注册。
三、授权 Agent
-
登录 TeamCity 后台：
http://<你的服务器IP>:8111 -
点击右上角齿轮图标 → 进入 Agents 页面
-
在 Unauthorized Agents 栏中，找到刚上线的 Agent，点击
Authorize即可 -
授权成功后，Agent 状态会变为
Connected或Idle，表示可以分配构建任务
四、多个 Agent 如何管理？
你可以添加多个 agent，组成 agent pool，提高并发能力。例如：
teamcity-agent-2:image: jetbrains/teamcity-agent:latestcontainer_name: teamcity-agent-2depends_on:- teamcity-serverenvironment:- SERVER_URL=http://teamcity-server:8111volumes:- /home/teamcity/agent2:/data/teamcity_agent/confuser: "1000:1000"restart: unless-stoppedmem_limit: 4gcpus: 2.0
⚠️ 每个 Agent 的配置目录应不同，否则会冲突。
五、构建任务绑定 Agent
在某些场景下，你可能希望某些任务只在特定 agent 上执行。设置方法：
- 编辑构建配置
- 进入 Agent Requirements
- 设置要求的系统属性、环境变量或 agent 名称
六、常见问题解决
❓ Agent 无法连接 Server？
- 检查
SERVER_URL是否正确：应使用容器网络中的服务名（如http://teamcity-server:8111） - 检查防火墙是否阻止 8111 端口
- 查看 agent 日志：
docker logs -f teamcity-agent
❓ Agent 一直 unauthorized？
- 登录 Web 后台 → Agents 页面 → 手动点击 Authorize
- 如果不想每次手动授权，可以进入 TeamCity 管理 → Agent Authorization Rules，开启自动授权
七、总结
本文介绍了如何：
- 在 Docker Compose 中添加并启动 TeamCity Agent
- 授权 Agent 并连接 Server
- 扩展多个 Agent 实例
- 针对性分配构建任务
配合前一篇 TeamCity Server 部署教程，你现在拥有了一个完整的 CI 环境，能自动拉取代码、构建、测试、部署！