项目管理员指南

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

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

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

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

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

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

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

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

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

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

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

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

  • 暂时禁用单个步骤。

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

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

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

• Project（项目）——独立构建配置的集合。 这些配置可以单独运行，但被分组到一个项目下以共享公共资源： 连接、 参数 、工件存储、 云代理配置文件等。

  每个项目都可以由另一个项目拥有以获得相同的好处：子项目可以访问其父项目拥有的实体。 最顶层的项目，称为 Root project（根项目） ，由 TeamCity 自动创建。 此根项目无法删除，非常适合设置全局可访问的参数、连接、云配置文件和其他共享资源。

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

视图模式

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

编辑模式

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

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

note

对于访问权限受限的 TeamCity 用户， 设置 切换按钮要么完全禁用，要么仅允许他们以只读模式查看项目/配置设置。

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

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

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”构建。

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

完成构建触发器

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

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

构件依赖性

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

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

部署通常是 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 插件 ，如 此处 所描述的那样。 参见相关的 博客文章。

tip

如果您通过第三方服务部署产品，TeamCity允许在开始外部部署操作之前 从代理中断开构建。 这有助于更优化地利用代理。

此方法需要一些高级配置，因此我们建议仅在您熟悉 TeamCity 中的构建和代理配置后尝试。

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

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

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

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