plotbox/teamcity-agent

定制化TeamCity Agent镜像文档

一、镜像概述和主要用途

概述

本镜像是基于官方JetBrains TeamCity Agent镜像的定制版本，在保留原版Agent核心功能的基础上，预安装了多种常用构建工具、编程语言环境及系统工具，以扩展TeamCity的构建能力，满足复杂CI/CD场景需求。

主要用途

作为TeamCity构建代理（Agent），连接TeamCity Server并执行构建任务。通过预安装的额外工具，支持多语言项目构建、容器化应用打包、自动化测试及复杂构建流程，减少构建环境配置时间，提升构建效率。

二、核心功能和特性

1. 继承官方Agent功能

• 完整支持TeamCity Agent与Server的通信协议，自动注册、心跳检测及任务调度
• 支持构建任务隔离、资源监控及日志收集

2. 额外预安装工具集

• 构建工具：Maven 3.9.x、Gradle 8.3.x、Ant 1.10.x
• 版本控制工具：Git 2.40.x、SVN 1.14.x
• 容器工具：Docker 25.0.x、Docker Compose 2.24.x
• 编程语言环境：
  • Java：JDK 8/11/17（通过update-alternatives切换）
  • Python 3.11.x（含pip）
  • Node.js 20.x（含npm/yarn）
  • Go 1.21.x
• 系统工具：curl、wget、jq、zip/unzip、rsync、make、gcc

三、使用场景和适用范围

使用场景

• 多语言项目构建：需同时支持Java后端+Node.js前端、Python脚本+Go服务等混合语言项目
• 容器化应用构建：直接在Agent中构建Docker镜像并推送至仓库
• 自动化测试环境：集成多种测试工具（如JUnit、pytest、Cypress）的统一执行环境
• 复杂构建流程：依赖系统工具（如jq解析JSON、rsync同步文件）的定制化构建逻辑

适用范围

• 适合需要扩展构建工具链的TeamCity环境（如企业级CI/CD平台）
• 需减少Agent初始化配置时间（预安装工具避免重复下载）的场景
• 不建议用于仅需基础构建能力的简单项目（可能造成资源浪费）

四、详细使用方法和配置说明

4.1 镜像获取

假设镜像存储于私有仓库（如registry.example.com/teamcity-agent-custom:latest），或通过本地Dockerfile构建。拉取命令：

bash
docker pull registry.example.com/teamcity-agent-custom:latest

4.2 基本运行（docker run）

核心命令

bash
docker run -d \
  --name teamcity-agent-01 \
  -v /opt/teamcity/agents/agent01/conf:/data/teamcity_agent/conf \  # Agent配置目录（持久化）
  -v /opt/teamcity/agents/agent01/work:/data/teamcity_agent/work \  # 工作空间（持久化构建产物）
  -e SERVER_URL="http://teamcity-server:8111" \  # TeamCity Server地址
  -e AGENT_NAME="agent-01-custom" \  # 自定义Agent名称（可选，默认随机生成）
  -e AGENT_TOKEN="your-agent-token" \  # Agent注册令牌（从Server获取）
  -e DOCKER_HOST="unix:///var/run/docker.sock" \  # 若需使用Docker，挂载宿主机Docker守护进程
  -v /var/run/docker.sock:/var/run/docker.sock \  # 共享宿主机Docker（可选，用于Docker in Docker）
  registry.example.com/teamcity-agent-custom:latest

4.3 Docker Compose配置

创建docker-compose.yml，更便于管理Agent生命周期：

yaml
version: '3.8'
services:
  teamcity-agent:
    image: registry.example.com/teamcity-agent-custom:latest
    container_name: teamcity-agent-01
    restart: always
    volumes:
      - ./agent/conf:/data/teamcity_agent/conf  # 本地目录挂载Agent配置
      - ./agent/work:/data/teamcity_agent/work  # 本地目录挂载工作空间
      - /var/run/docker.sock:/var/run/docker.sock  # 可选：启用Docker访问
    environment:
      - SERVER_URL=http://teamcity-server:8111  # TeamCity Server地址（需与Server网络互通）
      - AGENT_NAME=agent-01-custom
      - AGENT_TOKEN=your-agent-token  # 从TeamCity Server > Agents > Pools > Create Agent获取
      - WORK_DIR=/data/teamcity_agent/work  # 工作空间路径（默认与挂载目录一致）
    networks:
      - teamcity-network  # 确保与TeamCity Server在同一网络

networks:
  teamcity-network:
    external: true  # 假设已存在与Server共享的网络

启动命令：

bash
docker-compose up -d

4.4 环境变量说明

4.5 挂载目录说明

4.6 高级配置

自定义工具路径

若需覆盖预安装工具版本，可通过环境变量指定路径，例如：

bash
-e MAVEN_HOME="/opt/maven-custom"  # 优先使用自定义Maven路径（需提前挂载工具目录）

资源限制

通过docker run参数限制CPU/内存：

bash
--cpus 2 --memory 4g  # 限制2核CPU、4GB内存

4.7 注意事项

• 版本兼容性：确保Agent镜像版本与TeamCity Server版本一致（如Server 2023.11，Agent也需对应版本基础镜像）
• 网络可达性：Agent容器需能访问SERVER_URL（建议与Server部署在同一网络，或通过端口映射暴露Server）
• 权限问题：挂载宿主机目录时，需确保容器内用户（默认tcagent，UID 1000）对目录有读写权限，可通过-u root临时调试（生产环境不建议）
• 资源分配：根据构建任务复杂度调整CPU/内存（如编译大型项目建议至少4GB内存）

五、常见问题

• Agent无法连接Server：检查SERVER_URL是否正确（需包含http://或https://）、网络是否互通（可通过docker exec -it <agent-container> curl <server-url>测试）
• Docker命令无权限：确认/var/run/docker.sock已挂载，且容器内用户有访问权限（可添加--group-add docker参数）
• 工具版本不符：通过docker exec -it <agent-container> <tool> --version检查预安装工具版本，或提交镜像更新需求