TeamCity Agent 配置完整教程（配合 Docker Compose 快速部署）

本文详细介绍了如何在Docker环境中配置TeamCity构建代理(Agent)，完成完整的CI环境搭建。主要内容包括：1)解释TeamCity的主从架构；2)通过修改docker-compose.yml添加Agent服务；3)创建配置目录并授权Agent连接Server；4)扩展多个Agent实例的方法；5)构建任务绑定特定Agent的技巧；6)常见问题解决方案。文章作为前篇TeamCity S

爱宇阳

1341人浏览 · 2025-06-06 16:16:27

爱宇阳 · 2025-06-06 16:16:27 发布

在《使用 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:
  # 数据库
  postgres:
    ...

  # TeamCity 服务
  teamcity-server:
    ...

  # =====================================================
  # Vue 构建 Agent（Node + pnpm + Docker 构建）
  # =====================================================
  teamcity-agent-vue:
    image: jetbrains/teamcity-agent:latest
    container_name: teamcity-agent-vue
    restart: unless-stopped
    depends_on:
      - teamcity-server
    environment:
      SERVER_URL: http://teamcity-server:8111
      AGENT_NAME: vue-agent
      TZ: Asia/Shanghai
    mem_limit: 8g
    cpus: 4.0
    volumes:
      - /home/teamcity/agent/vue/conf:/data/teamcity_agent/conf
      - /home/teamcity/agent/vue/work:/data/teamcity_agent/work
      - teamcity-agent-vue-system:/opt/buildagent/system
      - teamcity-agent-vue-tools:/opt/buildagent/tools
      - /var/run/docker.sock:/var/run/docker.sock

  # =====================================================
  # Java 构建 Agent（JDK + Maven + Gradle + Docker 构建）
  # =====================================================
  teamcity-agent-java:
    image: jetbrains/teamcity-agent:latest
    container_name: teamcity-agent-java
    restart: unless-stopped
    depends_on:
      - teamcity-server
    environment:
      SERVER_URL: http://teamcity-server:8111
      AGENT_NAME: java-agent
      TZ: Asia/Shanghai
    mem_limit: 8g
    cpus: 4.0
    volumes:
      - /home/teamcity/agent/java/conf:/data/teamcity_agent/conf
      - /home/teamcity/agent/java/work:/data/teamcity_agent/work
      - teamcity-agent-java-system:/opt/buildagent/system
      - teamcity-agent-java-tools:/opt/buildagent/tools
      - /var/run/docker.sock:/var/run/docker.sock

volumes:
  # 用 Docker 卷管理系统目录和工具，避免权限问题
  teamcity-agent-vue-system:
  teamcity-agent-vue-tools:
  teamcity-agent-java-system:
  teamcity-agent-java-tools:

⚠️ 如果已经其他方式部署TeamCity服务，可删除teamcity-server和postgres，并把- SERVER_URL=http://teamcity-server:8111修改为TeamCity服务访问地址

2. 创建 agent 配置目录

sudo mkdir -p /home/teamcity/agent/vue/{conf,system,tools,work} /home/teamcity/agent/java/{conf,system,tools,work}
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: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