项目管理员指南

基本 TeamCity 工作流程

下图说明了基本的 TeamCity 工作流程：

1. TeamCity 服务器 检测到存储库中的更改。

2. 服务器将此更改写入数据库。

3. 附加到构建配置的 触发器检测到数据库中的相关更改并启动构建。

4. 触发的构建出现在 构建队列中。

5. 构建已分配给一个空闲的兼容构建代理。

6. 代理执行在构建配置中描述的构建步骤。 在执行步骤时，代理向 TeamCity 服务器报告构建进度。 它实时发送所有的日志消息、测试报告、代码覆盖率结果，因此您可以实时监控构建过程。

7. 构建完成后，代理将 构建工件发送到服务器。

步骤、配置和项目

在 TeamCity 中，构建流程可以由以下模块组成：

Project（项目）

项目 是用户可以创建的最大 TeamCity 实体。 一个项目的子项目、独立构建配置和管道。

• 您可以添加嵌套子项目，将配置和管道组织到不同的类别中。

• 大多数 TeamCity 用户权限是基于项目的。 这使您可以为不同的团队创建项目，并为独立的项目定义用户组。

• 项目可以拥有 连接、 参数 、工件存储、 云代理配置文件以及与其所有子项目、配置和管道共享的其他实体。 例如，您可以在项目级别创建一个到 GitLab 的连接，任何由该项目拥有的配置或管道都可以利用此连接访问远程存储库。

• 项目本身不执行任何构建、测试或交付任务。 这些任务由项目拥有的构建配置和管道执行。

Root project（根项目） 是 TeamCity 自动创建的最顶层项目。 此项目无法删除，并允许您创建服务器范围的连接、参数、云代理配置文件和工件存储。

Build configuration（构建配置）

build configuration（构建配置） 是按特定顺序执行的一系列构建步骤。 通过配置，您可以：

• 按需要的顺序排列步骤；

• 暂时禁用单个步骤。

• 为步骤设置 条件以确定何时执行。 如果条件不满足，则跳过相应的步骤。 例如，步骤 #3 可以设置为仅在步骤 #2 失败时运行，而步骤 #4 可以配置为仅在 Windows 代理上执行。

配置还可以转换为 模板 ，使其易于克隆和重用，而无需手动配置每个新设置。 克隆后，每个副本都可以独立自定义。

您还可以将来自同一项目或不同项目的配置合并到一个 统一工作流程中。

Build chain（构建链）

build chain（构建链） 是通过 快照依赖互相关联的一系列构建配置。 您可以将同一项目或不同项目的配置链接到一个单一的链中。 一个链可以部分执行，直到所需的构建配置。 例如，您可以跳过 "Deploy" 阶段，在 "Test → Build → Deploy" 链中。

有关更多信息，请参阅以下文章： 设置依赖项 | Build Chain（构建链）

管道

管道 是传统 构建链的轻量级、用户友好的替代方案。 每个管道包含一个或多个作业，每个作业运行一系列构建步骤。

管道允许您在单个屏幕上设计完整的多阶段工作流，而无需创建单独的构建配置并通过快照依赖将它们链接起来。

与可以运行到所需构建配置的构建链不同，管道始终运行其所有作业。

管道和构建配置都由项目拥有。

有关更多指导，请参阅 管道与构建配置和链的比较 部分。

工作

工作 是管道的单个元素，表示按顺序逐一执行的一系列构建步骤。 与构建配置不同，作业会执行其所有步骤，而没有任何额外的执行条件。

作业只能在管道内创建，并类似于更大构建链中的单个构建配置。

Build step（构建步骤）

build step（构建步骤） 是执行预定义命令集的基本构建模块。 这可以是单个命令（如 mvn test 或 gradle clean build ）或一系列操作（例如自定义 Python 或 Bash 脚本）。 构建步骤完全运行，不会部分执行。

构建步骤被分组到作业或构建配置中。

编辑和查看模式

在查看 TeamCity 配置、管道和项目时，您可以在两种模式之间切换：

视图模式

用于日常操作的查看模式，显示构建历史记录。 用户可以导航到单个构建以检查构建日志、查看与此构建一起触发的依赖配置、下载生成的工件等。 有关更多信息，请参阅 用户指南。

编辑模式

允许您修改项目或配置设置：已配置的构建步骤、启用和禁用的构建功能、构建触发器等。 根据用户的 权限 ，这些设置中的某些可能不可用。

要在两种模式之间切换，请使用右上角的 设置 切换按钮。

TeamCity 会保持选定的模式，除非您手动切换。 这意味着如果您查看/编辑一个配置的设置，导航到另一个配置时也会显示其设置。

有关可用项目和配置设置的更多信息，请参阅 创建和编辑项目 和 创建和编辑构建配置 部分。

VCS 根目录

VCS root（VCS 根） 是 TeamCity 与 VCS 存储库通信的基石。 此重要元素定义了与 VCS 提供程序 的连接，以执行广泛的操作：存储库检出、代码源标记、将构建状态回传到 VCS 等。

VCS 根存储以下信息：

• TeamCity 用于拉取和推送远程文件的获取和推送 URL。

• 分支信息：TeamCity 应跟踪的存储库分支列表以及哪个分支是默认（主）分支。

• 身份验证设置：TeamCity 用于访问存储库的凭据。

• 检出设置：指定如何存储远程文件以及是否应与主存储库一起检出子模块。

• 自定义更改轮询设置，允许您覆盖默认的 60 秒间隔。

与 VCS 根相关的部分在项目和配置设置中均可用。

然而，配置从不拥有根。 您可以将 VCS 根“附加”到配置，但根始终存储在（由）项目中。 此技术带来了以下结果：

• 一个 VCS 根可以附加到多个配置，这意味着多个构建配置可以使用相同的身份验证和检出设置访问同一个存储库。

• 单个配置可以附加多个 VCS 根，这使您能够在一个配置中使用不同的存储库。

• 编辑 VCS 根会影响所有使用它的配置。 在修改 VCS 根设置时，您可以选择复制此根并将更新的设置存储在此新克隆中，同时保持原始根不变。 这使您能够自定义一个构建配置，而不影响共享此根的其他配置。

尽管 VCS 根是任何与远程存储库交互的构建配置的基本部分，但在许多场景中，TeamCity 会自动生成根，而无需您为每个新构建配置手动创建它们。 有关示例，请参见 本教程。

构建功能

构建功能是可以添加到任何构建配置中的功能模块，以启用额外的功能。 例如， 提交状态发布器 构建功能将 TeamCity 构建结果发布到存储代码文件的 VCS，而 调查自动分配器 识别最新更改导致构建失败的用户，并自动分配任务以解决这些问题。 已配置的构建功能可以随时暂时禁用，而无需将其移除。

相关文章： 添加构建功能

分支操作

TeamCity 允许您为不同的分支设置不同的构建规则。 例如，您可能希望在出现新更改时构建“production”分支，每晚构建“development”分支，并忽略“sandbox”分支。 为此，您需要指定分支规范和过滤器。

收集更改

一旦您的项目设置完成，TeamCity 就可以接收有关提交到 分支规范中包含的存储库分支的所有新更改的信息。 新更改通知通过以下方式之一接收：

定期存储库轮询

默认情况下，TeamCity 每 60 秒自动轮询其项目目标的所有 VCS 存储库。 此方法的缺点是：

• 效率低下——TeamCity 不断轮询所有存储库，即使是那些很少有新更改的存储库。

• 性能——如果您的 TeamCity 服务器有大量项目，定期轮询可能会产生显著的负载。

• 延迟——用户提交更改后，可能需要等待最多一分钟才能在 TeamCity 配置的 待处理更改选项卡中显示此更改。 用户还可以使用 操作配置菜单手动触发此过程：

  

要更改轮询间隔，请导航到 常规 TeamCity 服务器设置。 要为单个配置覆盖此值，请编辑 VCS 根 最小轮询间隔设置。

Webhook

Webhooks 允许 VCS 托管提供商通知 TeamCity 有新更改。 与默认轮询机制相比，此行为具有以下优点：

• 效率——TeamCity 服务器在更改出现时接收更改通知。

• 速度——更改通知在提交后立即到达。

缺点是，Webhooks 需要为每个存储库/项目手动设置。

已配置提交钩子的项目仍会轮询其远程存储库，作为钩子停止工作时的备份机制。 然而，每次成功的 hook 通信，轮询间隔会自动翻倍。 TeamCity 将此间隔增加到的最大值是 4 小时，而最小间隔是 15 分钟。 如果定时轮询揭示了没有触发提交钩子的更改，TeamCity 将会将轮询间隔重置为默认值。

相关文章： 配置 VCS 提交后钩子

自动启动构建

TeamCity 用户可以通过配置右上角的 运行 按钮随时触发新构建。 要自动启动新构建，您需要配置 触发器。

TeamCity 提供多种触发器，可根据不同事件启动新构建，例如基于时间的触发器用于计划构建、基于更改的触发器用于新提交、在其他配置完成时启动构建的触发器等。

相关文章： 配置构建触发器

工件

工件是构建过程中生成的文件。 这些文件可供以下对象使用：

• TeamCity 用户可以从 构建结果页面 下载它们。

• 其他 TeamCity 构建可以使用 构件依赖性 导入这些文件。

要选择哪些文件应作为构建工件可用：

1. 打开 配置设置并导航到 常规设置选项卡。

2. 设置 构建工件路径 属性。 您可以先运行一个生成所需文件的构建。 然后，您将能够点击“从最新构建中选择文件”按钮，并从下拉菜单中选择文件，而无需手动输入其路径。

相关文章： 构建工件

设置依赖项

实际的 CI/CD 流水线通常结合多个独立的阶段。 例如，“Build”、“Test”和“Deploy to Staging”配置（或作业）可以独立运行或按顺序运行。

TeamCity 提供了多种选项来创建这些独立实体之间的关系。

Build Chain（构建链）

构建链是使用 快照依赖项互连的经典 TeamCity 配置集合。

快照依赖项是从右到左的关系。 例如，在“ A -> B ”链中，配置“B”依赖于配置“A”，因此“B”在“ A ”首先生成合适的构建之前无法运行。 “合适”构建的标准取决于您的设置，请参阅 合适的构建部分了解更多信息。 同时，“A”可以独立运行，而不会触发新的“B”构建。

对于关键任务场景，您可以设置依赖配置以始终强制生成新的上游配置构建，即使项目没有最近的更改。

管道

这是构建链的简化替代方案，其中作业代表流程的每个阶段。 对于较小的、不太复杂的工作流（整个流程大约 10 到 15 个阶段），这是推荐的选项。

与在构建链中链接的构建配置相比，流水线展示了以下差异：

• 您只能链接属于同一流水线的作业。 而构建链允许您链接完全独立的 TeamCity 项目所拥有的构建配置。

• 不支持需要手动配置的独立工件和快照依赖项。 当您选择一个应在当前作业之前运行的作业时，您可以立即选择是否导入其所有工件。

• 流水线会运行其所有作业，而不考虑它们的依赖关系。 构建链具有更多的自定义选项，并且可以 部分执行。

完成构建触发器

完成构建触发器建立从左到右的关系。 例如，您可以创建类似于构建链的“ A -> B ”序列，但有一个关键区别：“B”可以独立运行，而每个新的“ A ”构建会自动触发一个新的“B”构建。

完成构建触发器提供了一种简单但不灵活的方式来触发下游构建，通常可以被快照依赖项替代或补充。

构件依赖性

工件依赖项允许配置导入其他配置构建过程中生成的文件。 例如，“Delivery”配置可以将“Build”配置生成的文件（Docker 镜像、NuGet 包、HTML 文档页面等）部署到指定资源。

工件依赖项不会 非 在配置之间创建显式链接：两者可以独立运行，而不会触发彼此的构建。 如果您使用工件依赖项而没有相应的快照依赖项，依赖构建无法确保存在合适的工件来源（上游配置构建）。 因此，您可能需要设置工件依赖项以定位固定/标记的构建。

Deployment

部署通常是 CI/CD 流程的最后阶段，将构建生成的工件交付到外部位置。 根据您的场景和需求，您可以将此操作作为最终构建步骤，或独立的 部署配置。

在 TeamCity 中部署工件的方法：

• 通过命令行 ，使用任何通用运行器，例如 Command Line或 PowerShell。 这是最直接的方法。 只需添加构建步骤，选择任何此类运行器，并按照在常规终端中一样输入命令。 在这种情况下，您从 TeamCity 获得的好处是灵活的自动化、与之前的构建阶段同步，以及在 TeamCity UI 中方便地查看构建结果。
  这样，您还可以在第三方存储中，如 Amazon S3，更新分发文件。

• 使用适合您平台的特定 runner. 例如，如果您构建 .NET 项目，部署它们的最佳方式是通过我们的 .Net 运行器。 它支持所有相关的 .NET 命令，如 pack 或 publish ，并提供各种其他功能。 其他的运行器在 此部分 下列出。

• 使用部署工具. TeamCity 提供了几个专门用于部署的构建运行程序： SMB 上传、 FTP 上传、 SSH 上传和 SSH Exec。 他们可以通过不同的协议上传构建工件，并且允许您在 TeamCity UI 中配置此上传过程。

• 使用 AWS CodeDeploy runner 用于将应用程序部署到 AWS EC2 和本地实例。 要使用这个运行器，您需要下载并安装我们的 AWS CodeDeploy 插件 ，如 此处 所描述的那样。 参见相关的 博客文章。

调查和静音

TeamCity 中的每个构建问题或测试失败都可以作为单独的事件进行调查。 有关更多信息，请参阅以下文章： 处理构建和测试失败。

构建问题和失败的测试可以 静音 ，以便即使遇到这些问题，构建也能成功完成。 请注意，具有默认项目开发者 角色的用户无法静音问题，只有项目管理员可以执行此操作。

要自动将调查分配给更改可能导致构建失败的用户，请配置 调查自动分配器 构建功能。

教程：在 TeamCity 中创建您的第一个项目

配置并运行您的第一个构建 教程将引导您完成设置 TeamCity 项目的主要阶段：建立 VCS 连接、设置构建操作、配置附加功能、将用户分配到此项目等。