Jenkins 到 TeamCity 迁移指南

概述

TeamCity 提供了广泛的强大集成和智能自动化功能，以提升您的 CI/CD 工作流。然而，迁移一个复杂的、公司范围的构建集群始终是一个挑战。本指南概述了迁移过程，并突出了这两个 CI 系统之间的关键相似点和差异，以支持平稳过渡。

TeamCity 与 Jenkins：关键相似点与差异

TeamCity 和 Jenkins 都是用于自动化构建、测试和部署的流行 CI/CD 工具。虽然它们共享一些核心功能，但两者之间也存在显著差异。

相似点

两种工具都支持使用流水线来构建和部署工作流（尽管它们使用的术语和方法略有不同）。
TeamCity 和 Jenkins 都可以通过插件或扩展进行高度配置和自定义。
两种工具都支持与基于容器的工作流集成，包括 Docker。

差异

配置格式. Jenkins 使用声明式流水线（基于 Groovy 的文件）或脚本化流水线（Jenkins DSL）。使用 TeamCity，您始终可以选择通过 UI 配置构建流程，使用基于 Kotlin 的配置脚本，或两者结合使用。
托管选项. TeamCity 提供了自托管解决方案和 SaaS 服务（通过 JetBrains 托管的云实例）。 Jenkins 仅支持自托管，要求用户管理自己的基础设施。
设置和维护的简易性. TeamCity 提供了更友好的设置流程和开箱即用的精美界面。每个配置任务——从设置云代理到管理服务器节点和清理规则——都可以直接通过 TeamCity UI 完成。您还可以尝试 TeamCity Pipelines ，这是一种更加以用户为中心的解决方案，只需几次点击即可设置构建流程。 Jenkins 通常需要更多的手动设置和配置，并且严重依赖插件，这可能会增加维护开销。
内置功能与插件. TeamCity 内置支持管理构建代理、测试框架、代码质量检查和报告工具。 Jenkins 的功能严重依赖于第三方插件，这些插件需要单独选择和配置以实现类似的功能。
与开发工具的集成. 由于 TeamCity 由 JetBrains 开发，它与其开发者工具生态系统（如 IntelliJ IDEA 和其他 JetBrains IDE）紧密集成。 Jenkins 提供与许多工具的集成，但通常需要插件或自定义配置来设置这些连接。
成本. TeamCity 的免费版本限制了构建代理和配置的数量，扩展需要额外费用。 Jenkins 作为开源软件，没有前期成本，但托管和插件维护需要作为运营费用考虑。

规划迁移

审查您的 Jenkins 设置

首先了解 Jenkins 中当前运行的所有内容。这将帮助您避免意外情况，并确保在 TeamCity 中实现功能对等。

清点所有 Jenkins 作业和流水线
导出完整的流水线列表，无论是脚本化的还是声明式的。注意命名约定、文件夹结构、触发器和分支策略。
列出所有正在使用的插件
使用匹配 Jenkins 插件与 TeamCity 功能生成列表。对于每个插件，记录其用途以及是否在 TeamCity 中有对应功能（许多功能是内置的）。
记录外部集成
确定 Jenkins 如何与工具通信，例如制品库（Artifactory、Nexus）、容器管理器（Docker、Podman、Kubernetes）、密钥管理器（Vault、AWS Secrets Manager）、通知工具（Slack、电子邮件、MS Teams）、基础设施工具（Terraform、Ansible 等）。
审查身份验证和访问控制
您是否使用 SSO、LDAP、GitHub OAuth 或手动用户？记录角色和权限，以便迁移到 TeamCity 的用户/组模型。
衡量性能和资源使用情况
收集构建时长、队列时间和代理利用率等指标。这为比较迁移后的性能提供了基准。

准备 TeamCity 环境

在开始实际迁移之前，请确保您的 TeamCity 设置已准备就绪。

启动一个 TeamCity 实例选择 TeamCity Cloud（由 JetBrains 完全管理）或 TeamCity On-Premises（由您的团队托管和维护）。
配置构建代理
TeamCity 需要构建代理来执行任务。决定您将使用：
- 自托管的静态代理（例如裸机或虚拟机）
- 基于云的代理（例如 AWS、GCP、Azure）
- 按需代理（支持 Docker/Kubernetes）
连接您的版本控制系统
通过 VCS Roots 添加您的代码库。 TeamCity 支持 GitHub / GitHub Enterprise、GitLab、Bitbucket Cloud、Server 和 Data Center、Azure Repos、Perforce Helix 以及其他通过 SSH/HTTP(S) 协议的 VCS 提供商。
学习 TeamCity 结构的基础知识
TeamCity 的工作组织方式与 Jenkins 不同。基本概念包括：
- 项目——顶级容器
- 构建配置——类似于 Jenkins 的任务
- 模板——可重用的构建逻辑
- 构建链——可视化并控制依赖关系
- Kotlin DSL——以代码形式定义构建逻辑，并在 Git 中进行版本管理。请参阅本指南的术语映射与功能比较部分。
设置密钥和凭据
在 TeamCity 中为 API 密钥、令牌和密码定义安全参数。将任何 Jenkins 凭据映射到这些参数。

术语映射与功能比较

在开始之前，让我们回顾一下关键的 Jenkins 术语如何对应于 TeamCity。

Jenkins	TeamCity
Jenkins Master / Node	TeamCity 服务器
哑代理 / 永久代理	代理池
执行器	TeamCity 代理
查看或 Folder	项目
工作/项目/项目	构建配置
Build（构建）	构建步骤
预步骤	构建步骤（部分）引导步骤
构建后操作	构建步骤（部分）部署者部署构建配置
构建触发器	构建触发器
源代码控制管理（SCM）	VCS 根
工作区	构建 Checkout 目录
管道	构建链（通过快照依赖项）
Label	代理需求

以下部分更详细地解释了一些关键的 Jenkins 概念与其在 TeamCity 中的对应关系。

配置文件

Jenkins 使用 Jenkinsfile，用 Groovy 编写。它以代码形式定义流水线步骤。
TeamCity 使用 Kotlin 或 XML 设置文件。 TeamCity 可以从 UI 配置的项目中自动生成设置，您也可以在本地使用完整的 IDE 支持进行编辑。设置文件可以存储在构建项目旁边，也可以存储在一个完全独立的远程存储库中。

构建定义

Jenkins 任务可以通过 UI 配置，也可以在 Jenkinsfile 中定义为脚本化或声明式流水线。
构建由构建配置生成，归父项目所有。每个配置可以包含多个步骤、触发器、参数等。

变量

Jenkins 变量通过环境块或 params {} 在流水线脚本中设置。也可以在 UI 中配置。
TeamCity 使用参数，这些参数可以按构建配置、项目或全局定义。这些参数包括传递给代理机器的环境变量和配置参数。参数可以与其他配置共享（输出参数），也可以配置为私有（输入参数）。

条件步骤

Jenkins 通过声明式流水线中的 when {} 块或脚本化流水线中的 Groovy if 支持条件执行。
TeamCity 的步骤条件可以在 UI 或 Kotlin DSL 中设置。支持多种条件：您可以仅在另一个步骤成功时执行某个步骤，仅在其失败时执行，或仅在特定参数具有所需值时执行，等等。

工件管理

在 Jenkins 中，您必须显式声明要归档的文件，使用 archiveArtifacts。
您可以使用 TeamCity UI、Kotlin DSL 或手动发送服务消息来发布构建过程中生成的文件作为制品。制品依赖允许在各种配置之间共享已发布的制品。

容器管理器

Jenkins 通过 Docker Pipeline 插件或 Kubernetes 插件支持 Docker，但您需要安装和配置它们。
TeamCity 提供内置支持 Docker 和 Podman ，包括 Docker 步骤、代理镜像和服务容器。无需插件。

构建代理

Jenkins 代理必须手动设置和连接（SSH、Docker 等）。通过 Kubernetes 的代理模板需要插件设置。
TeamCity 支持云代理（JetBrains 托管）、基于 Docker 的代理和传统的自托管代理，配置最小化。

并行执行

Jenkins 支持脚本化流水线中的并行块或声明式流水线中的并行阶段。
TeamCity 可以并行运行构建或构建步骤，使用构建依赖、将测试拆分为批次以及代理端并行处理。

构建日志

Jenkins 默认将构建结果输出到控制台。您可以使用插件通过时间戳和颜色增强日志。搜索和导航功能有限。
TeamCity 提供实时日志流，带有时间戳和高亮显示， Prometheus 格式的服务器负载指标，以及每个构建步骤的归档历史。可以将 TeamCity 与第三方可观测性解决方案（如 Dynatrace、Grafana 等）集成。

有关 TeamCity 和 Jenkins 功能更详细的比较，请参阅本文档。

匹配 Jenkins 插件与 TeamCity 功能

与 Jenkins 不同，Jenkins 的许多核心功能依赖于第三方插件，而 TeamCity 内置了大多数基本功能——如 Git 和 Docker 支持、测试报告、密钥管理和通知。这意味着更少的维护部分，没有插件兼容性问题，并且提供更稳定的开箱即用体验。

以下是一些 Jenkins 插件与 TeamCity 内置功能的对应关系。

Jenkins 插件	对应的 TeamCity 功能
Pipeline	构建配置与 Kotlin DSL
Blue Ocean	构建链
Credentials plugin	各种参数，用于不同的用例：存储在 TeamCity 服务器上的密钥、“密码”类型的参数，以及从外部存储（如 HashiCorp Vault）检索敏感数据的远程参数。
Artifactory 插件	内置的制品存储和云/本地存储库支持。支持 S3 存储桶和其他云存储提供商。
Git 插件	一流的 Git 支持，具有深度 VCS 集成（GitHub、GitLab、Bitbucket、Azure Repos 等）。
Docker 插件	内置 Docker 和 Podman 支持：使用 Docker 作为构建环境，拉取服务，构建/推送镜像。
Slack 通知插件	内置通知：Slack、电子邮件、Microsoft Teams、基于 Webhook 和服务消息的通知，支持可自定义模板。
Kubernetes 插件	多种内置 Kubernetes 集成级别：设置 Kubernetes 云配置文件或使用您的集群作为外部执行器处理 TeamCity 构建。
JUnit 插件	原生支持解析 JUnit 测试结果、可视化测试报告、测试历史和不稳定测试检测。
HTML 发布插件	内置支持发布和查看 HTML 构建报告。
限制并发构建插件	智能队列优先级、每个项目/代理的构建限制以及代理需求逻辑。
AnsiColor 插件	原生日志输出，支持带颜色的 ANSI 和构建日志中的语法高亮。
Timestamper 插件	TeamCity 日志内置结构化时间戳、日志折叠和过滤功能。
工作区清理插件	内置工作区和制品清理规则，支持可自定义的保留策略。
构建超时插件	灵活的构建超时选项（绝对值、不活动、自定义逻辑），直接在构建配置设置中。
参数化触发插件	内置快照和制品依赖，使用特定参数触发构建。

迁移示例

在 Jenkins 中，任务是定义一系列任务的基本单元。在 TeamCity 中，这一概念由构建配置表示。每个构建配置指定了一组构建步骤、触发器和执行构建所需的其他设置。

Jenkins 使用用 Groovy 编写的 Jenkinsfile 定义构建流水线。此文件通常位于代码库的根目录中，描述了构建过程的步骤和阶段。

示例 1. 基本流水线配置

Jenkins 配置：

pipeline {
agent any

    stages {
        stage('hello') {
            steps {
                echo "Hello World"
            }
        }
    }
}

   

在 TeamCity 中，您可以选择通过 UI 或使用 Kotlin DSL 配置流水线。使用 Kotlin DSL 配置流水线的一些好处包括：

可读性和可维护性
版本控制：将配置存储在任何支持的 VCS 中，以提高可追溯性
可扩展性：支持循环、条件和可重用组件。将其视为一个功能齐全的编程语言，而不仅仅是像 XML、XAML 或 YAML 这样的标记语言，这意味着可以使用自定义数据类、自定义库等。
UI 同步：在 UI 中所做的更改可以反映在 DSL 中，反之亦然。

如果您选择使用 Kotlin DSL 进行配置，您的设置将位于远程目录中（默认情况下是代码库根目录中的隐藏 .teamcity 文件夹），并以类型安全的 Kotlin 代码编写。这使您更容易及早发现错误，并利用 IDE 功能，如代码补全。

以下是之前描述的 Jenkins 文件在 TeamCity Kotlin DSL 中的等效设置：

import jetbrains.buildServer.configs.kotlin.*

project {
    buildType(HelloBuild)
}

object HelloBuild : BuildType({
    name = "Hello Build"

    steps {
        script {
            name = "Say Hello"
            scriptContent = "echo Hello World"
        }
    }
})

   

此 Kotlin 代码定义了一个项目，其中包含一个运行脚本打印 Hello World 的构建配置。 TeamCity 在连接到您的代码库时会自动获取此配置。

示例 2：简单构建任务

Jenkins:

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                sh 'mvn clean package'
            }
        }
    }
}

   

在 TeamCity 中，您可以使用通用的命令行步骤执行常规构建操作，或使用专门的构建步骤与特定构建工具交互： .NET、 Maven、 Python、 Gradle 等。

TeamCity Kotlin DSL（CLI 步骤）：

import jetbrains.buildServer.configs.kotlin.*

project {
    buildType(SimpleBuild)
}

object SimpleBuild : BuildType({
    name = "Simple Build"

    steps {
        script {
            name = "Maven Build"
            scriptContent = "mvn clean package"
        }
    }
})

   

通过 TeamCity UI（Maven 步骤）：

创建一个构建配置。
添加一个 Maven 构建步骤。
将 Maven 步骤的目标属性设置为 clean package。

示例 3：运行测试

Jenkins:

pipeline {
    agent any
    stages {
        stage('Test') {
            steps {
                sh 'pytest tests/'
            }
        }
    }
}

   

TeamCity Kotlin DSL:

import jetbrains.buildServer.configs.kotlin.*

project {
    buildType(RunTests)
}

object RunTests : BuildType({
    name = "Run Tests"

    steps {
        script {
            name = "Run Pytest"
            scriptContent = "pytest tests/"
        }
    }

    requirements {
        contains("teamcity.agent.jvm.os.name", "Linux") // Optional: adjust based on your environment
    }
})

   

TeamCity 用户界面:

创建一个构建配置。
添加一个构建步骤，类型为命令行或 Python。
指定 pytest tests/ 步骤脚本。

示例 4：部署到生产环境

Jenkins:

pipeline {
    agent any
    stages {
        stage('Deploy') {
            steps {
                sh 'kubectl apply -f deployment.yaml'
            }
        }
    }
}

   

TeamCity Kotlin DSL:

import jetbrains.buildServer.configs.kotlin.*

project {
    buildType(DeployToProduction)
}

object DeployToProduction : BuildType({
    name = "Deploy to Production"

    steps {
        script {
            name = "Apply Kubernetes Deployment"
            scriptContent = "kubectl apply -f deployment.yaml"
        }
    }

    requirements {
        contains("teamcity.agent.jvm.os.name", "Linux") // Adjust if needed
    }
})

   

通过 TeamCity UI：

创建一个部署配置。
添加一个 CLI 构建步骤。
设置 kubectl apply -f deployment.yaml 命令。

触发器

Jenkins 和 TeamCity 都支持构建触发器以自动启动构建。在 Jenkins 中，常用的触发器包括 cron、 pollSCM 和 GitHub webhook triggers。

在 TeamCity 中，各种触发器可用，以提供类似的自动化功能。

VCS 触发器：当检测到与构建配置相关联的版本控制系统根目录中有变化时，构建将会被触发。
GitHub Checks Webhook 触发器：每次向源 GitHub 仓库推送提交时都会触发构建。此外，还会在未配置提交状态发布器的 GitHub 页面上发布详细的构建结果信息。
计划触发器：在指定时间触发构建。
完成构建触发器：在选定的配置构建完成后，将会触发此构建。
Maven 依赖触发器：如果检测到指定 Maven 工件内容的修改通过校验和变化，将触发构建。
Maven 快照依赖触发器：如果远程仓库中的快照依赖内容发生更改被检测到（通过校验和更改检测），则触发构建。
Retry build trigger ：如果上次构建失败或未能开始，则触发构建。
远程分支运行触发器：每当 TeamCity 在构建配置的 VCS 根的特定分支中检测到新的更改时，个人构建会自动触发。支持 Git 和 Mercurial。
NuGet 依赖触发器：如果在 NuGet 仓库中检测到 NuGet 包的更新，将启动构建。
Perforce shelve trigger ：在 Perforce 暂存文件发生更改时开始构建。

通过利用这些触发器，您可以确保 CI/CD 工作流的高效自动化，减少人工干预并提高部署速度。

环境变量

Jenkins 允许在 environment 块中定义环境变量。在 TeamCity 中，环境变量作为构建参数进行管理，可以在项目或构建配置级别定义。

Jenkins:

pipeline {
   environment {
      API_KEY = 'my_secret_key'
   }
   stages {
      stage('Build') {
         steps {
            echo "Using API Key: ${API_KEY}"
         }
      }
   }
}

  

TeamCity Kotlin DSL:

import jetbrains.buildServer.configs.kotlin.*

project {
    buildType(UseApiKey)
}

object UseApiKey : BuildType({
    name = "Use API Key"

    params {
        password("API_KEY", "credentialsJSON:*****") // Replace with your actual secure credential reference
    }

    steps {
        script {
            name = "Echo API Key"
            scriptContent = "echo \"Using API Key: %API_KEY%\""
        }
    }
})

  

在 TeamCity UI 中的等效操作：

打开构建配置或项目设置，创建一个名为 env.API_KEY 的参数。
指定参数值。
通过 %env.API_KEY% 语法在构建步骤或配置设置中引用它。

构建后操作

在 Jenkins 中，构建后操作定义在 post 部分，包括通知、归档制品或触发其他构建等任务。

在 TeamCity 中，可以使用构建功能或额外的构建步骤来实现类似的功能，这些步骤可以根据成功或失败条件执行。

制品在设置 VCS 连接时配置，在 VCS 根目录内。至少运行一次构建，您将能够使用文件/文件夹浏览器轻松选择应作为制品发布的生成文件。
通知是在每个构建配置的基础上设置的。
交付任务由部署配置和部署者执行。

结论

从 Jenkins 迁移到 TeamCity 提供了更高的效率、增强的自动化以及对插件的依赖减少。我们希望本指南可以作为一个良好的起点，帮助您从 Jenkins 迁移到 TeamCity。

最后修改日期： 2025年 8月 12日