在《使用 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:latest
    container_name: teamcity-agent
    depends_on:
      - teamcity-server
    environment:
      - SERVER_URL=http://teamcity-server:8111
    volumes:
      - /home/teamcity/agent:/data/teamcity_agent/conf
    user: "1000:1000"
    restart: unless-stopped
    mem_limit: 4g
    cpus: 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

1. 登录 TeamCity 后台：

   http://<你的服务器IP>:8111
   

2. 点击右上角齿轮图标 → 进入 Agents 页面

3. 在 Unauthorized Agents 栏中，找到刚上线的 Agent，点击 Authorize 即可

4. 授权成功后，Agent 状态会变为 Connected 或 Idle，表示可以分配构建任务

---

四、多个 Agent 如何管理？

你可以添加多个 agent，组成 agent pool，提高并发能力。例如：

  teamcity-agent-2:
    image: jetbrains/teamcity-agent:latest
    container_name: teamcity-agent-2
    depends_on:
      - teamcity-server
    environment:
      - SERVER_URL=http://teamcity-server:8111
    volumes:
      - /home/teamcity/agent2:/data/teamcity_agent/conf
    user: "1000:1000"
    restart: unless-stopped
    mem_limit: 4g
    cpus: 2.0

⚠️ 每个 Agent 的配置目录应不同，否则会冲突。

---

五、构建任务绑定 Agent

在某些场景下，你可能希望某些任务只在特定 agent 上执行。设置方法：

1. 编辑构建配置
2. 进入 Agent Requirements
3. 设置要求的系统属性、环境变量或 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 环境，能自动拉取代码、构建、测试、部署！