TeamCity On-Premises 2024.03 Help

升级 TeamCity 服务器和代理

TeamCity 支持从任何先前的版本升级到后续版本。 除非在 升级说明 中有特别说明，否则所有的设置和数据都将被保留。

建议您定期规划升级，至少在发布几次错误修复更新后，运行最新的 TeamCity 版本。 这样，您运行的是一个得到全面 支持的版本，包含最新的修复和安全补丁。

安全补丁

TeamCity 是一个严重依赖于服务器、构建代理、VCS 提供商以及其他外部服务（如 AWS S3 桶或 Nexus LFS 存储库）之间通信的 Web 应用程序。 因此，当在非封闭环境中部署时，TeamCity 容易受到利用常见漏洞和暴露（CVEs）进行攻击的威胁，包括那些从其使用的第三方解决方案和库中继承的漏洞。

为了降低风险，强烈建议您及时安装包含安全修复的任何更新。 解决非关键性安全漏洞的修复会在常规的 问题修复更新 中得到解决。 请参阅 发布说明，并查看我们的 安全公告 来查看已修复问题的列表。

存在严重安全威胁的关键性漏洞将在单独的非计划安全补丁中得到修复。 一旦找到解决方案，这些补丁将立即发布。 如果有此类更新可用，TeamCity 会自动下载并提示管理员进行安装。

要停止 TeamCity 自动下载这些补丁，请在 Administration | Updates 页面取消选中 "自动下载可用的安全补丁并在准备安装时通知管理员" 的选项。 然而，我们强烈建议您不要禁用此功能，因为它能保证对新出现的安全威胁做出迅速的响应，并确保迅速更新。

升级前

在升级 TeamCity 之前：

要升级服务器：

  1. 备份当前的 TeamCity 数据，包括设置、数据库和补充数据。 在升级失败的不大可能的情况下，您将需要备份以回退到之前的版本。

  2. 执行升级步骤：

授权许可

在升级前，请确保您的许可证的维护期尚未过期（使用 Administration | Licenses 页面查看您的许可证密钥）。 许可证仅对在维护期内实施发布的 TeamCity 版本有效。 检查 发布列表 中的有效发行日期。
一般来说，所有的小更新（即 YYYY.MM.B TeamCity 版本中 B 部分的变动）都使用相同的发布日期（即主版本的发布日期）。
如果并非所有的许可证都覆盖了目标版本的发布日期，那么在升级之前，请考虑 更新许可证（您可以在升级之前就用新版的替换掉旧的许可证密钥）。

如果您只是在评估新版本，您可以在 下载页面 获取评估许可证。 请注意，每个 TeamCity 版本只能评估一次。 要延长评估期，联系 JetBrains 销售部门。

当您从 TeamCity 4.x 或更早版本升级时，请注意，TeamCity 5.0 和以后版本的许可策略与以前的 TeamCity 版本不同。 审查官方网站上的 许可政策 页面以及 许可和升级 部分。

升级 TeamCity 服务器

TeamCity 支持从任何以前的版本升级到当前版本。
除非特别注明，否则在更改主版本时不可能保留数据进行降级，但在修复 bug 的版本中是可能的。

一般政策是，错误修复更新（由 B 部分的更改表示在 YYYY.MM.B TeamCity 版本中）不会改变数据格式，因此您可以在错误修复版本内自由升级/降级。 然而，在升级到下一个主要版本时（更改了 YYYY.N ），您将无法在保留数据的情况下降级：您需要 还原备份 到适当的版本。 阅读更多关于发布编号的信息。

在升级过程中，除非在 升级说明 中另有说明，否则所有的 TeamCity 配置设置和其他数据都会被保留。 如果您已自定义了 TeamCity 安装（例如更改了 Tomcat 服务器设置），那么您需要在升级后重复这个自定义操作。

升级的一般方法是删除 TeamCity 服务器主目录中的所有旧版安装文件，然后将新文件放入同一位置。 确保保护 TeamCity Data Directory 和数据库（事先做好备份），同时也需要备份并恢复之前定制的设置（例如，在 ...\conf\server.xml, ...\conf\web.xml 文件中）。 日志目录（ ...\logs ）可以保留旧的安装文件。

连接到服务器的代理将 自动 升级。

关于数据格式升级，存在几个重要的问题：

  • 数据结构无法降级。 一旦新版的 TeamCity 更改了数据库和数据目录的数据格式，您就无法使用这些数据来运行旧版的 TeamCity。 请确保您在升级 TeamCity 之前 备份 数据。

  • 数据库和数据目录应同时进行升级。 确保在首次启动新服务器时，它使用正确的 TeamCity Data Directory，而该目录又在 <TeamCity 数据目录>\config\database.properties 文件中正确地配置了数据库。 同时，请确保数据目录完成（例如，所有构建日志和制品都到位），不支持从旧版服务器的数据目录复制数据目录内容。

如果您不小心执行了不一致的升级，请检查 恢复指南。

自动更新

为了能够自动更新，TeamCity 服务器应能够联系 jetbrains.com， download.jetbrains.com 和 download-cdn.jetbrains.com。

当检测到 TeamCity 的新版本时，服务器会为系统管理员显示相应的健康项目。 该项目指向服务器的 Administration | Updates 页面，页面上列出了所有可用于更新的版本。 该页面包含有关许可证兼容性、新版本描述以及执行自动更新的控制，如果您愿意，可以选择使用自动更新而非手动更新程序。

自动更新程序如下：

  1. TeamCity 服务器已停止。

  2. 更新脚本被运行以执行以下操作：

    1. 在 <TeamCity 安装目录>/.old 目录中创建当前安装的备份。

    2. 将已停止的服务器更新至新版本。

  3. 接下来，更新后的服务器开始启动。
    更新进度被记录在 <TeamCity 安装目录>/logs/teamcity-update.log 文件中。

如果自动更新失败，执行以下操作以恢复您的 TeamCity 到更新前的状态：

  1. 如果您的 TeamCity 服务器正在运行，那么请停止它。

  2. 对于存在于 <TeamCity 安装目录>/.old 目录中的每一个文件夹，删除 <TeamCity 安装目录> 中的相应文件夹。 请不要删除 "bin" 文件夹，因为其部分文件没有备份到 TC_home/.old 目录。

  3. 将 <TeamCity 安装目录>/.old 文件夹中的所有内容复制并粘贴到 <TeamCity 安装目录> ，替换所有重复的文件。

  4. 启动 TeamCity 服务器。

自动更新的其他限制：

  • 某些文件，如 TeamCityService.exe 和 teamcity-server.bat ，并未被包含在自动更新的范围内。

  • 某些自定义，例如，更改了服务器上下文的安装，不受自动更新的支持。

  • Windows 卸载程序在升级过程中不会更新，因此在多次更新后，旧的 TeamCity 版本仍会在 Windows 列表中出现。 在卸载过程中，可能不会删除所有的 TeamCity 安装文件。

手动更新

使用 Windows Installer

  1. 创建备份。 您可以在更新后的 TeamCity 启动时，通过 "basic" 配置文件在 TeamCity 维护模式 页面上创建备份。

  2. 请注意用于运行 TeamCity 服务器的用户名。 在安装新版本时，您将需要它。

  3. 如果您有任何定制的 Windows 服务设置，请储存它们，以便以后重复定制。

  4. 如果您正在使用 64 位 Java 来运行服务（例如，在服务器的 Administration | Diagnostics 或在线程转储中查找 "64"），请考虑备份 <TeamCity 安装目录>\jre 目录。

  5. （可选，因为这些不会被升级覆盖）备份捆绑的 Tomcat 服务器（如端口，HTTPS 协议等）或 JRE 的自定义内容（如果有的话）。

  6. 检查您是否已安装了本地代理（尽管不建议安装本地代理），以便您稍后在安装程序中选择此选项。

  7. 运行新的安装程序，并将其指向 TeamCity 的安装位置（安装位置会自动记住）。 确认卸载之前的安装。 TeamCity 卸载程序确保了正确的卸载，但是您可能需要确保 TeamCity 服务器安装目录 在卸载完成后不包含任何非定制文件。 如果有的话，在继续安装之前备份/删除它们。

  8. 如果有提示，指定上一个安装时使用的 <TeamCity Data Directory>/。

  9. （可选，因为这些不会被升级覆盖）确保您已经安装了外部数据库驱动程序（仅当您使用外部数据库时适用）。

  10. 检查并恢复您需要的 Windows 服务和 Tomcat 配置的任何自定义内容。 当从 TeamCity 7.1 或更早的版本升级时，请确保将 服务器内存设置 转移至 环境变量。

  11. 如果您之前使用 64 位 Java 运行服务器，请恢复先前备份的 <TeamCity 安装目录>\jre 目录，或者重复 64 位 Java 安装步骤。

  12. 如果您在 conf\teamcity-server-log4j.xml 文件中使用了自定义的 Log4j 配置并希望保留它（注意，建议使用 日志预设），请将安装程序创建的 conf\teamcity-server-log4j.xml.backup 与默认文件进行比较和合并，默认文件以默认名称保存。 将 conf\teamcity-*-log4j.xml.dist 文件与相应的 conf\teamcity-*-log4j.xml 文件进行比较，确保 .xml 文件包含所有 .dist 文件的默认设置。 建议将 .dist 文件复制到相应的 .xml 文件，直到您真正需要更改的日志配置。

  13. 启动 TeamCity 服务器（如果它与安装程序一起安装，则启动代理）。

  14. 请查阅 TeamCity Maintenance Mode 页面，确保没有遇到任何问题，并点击相应的按钮进行升级确认。 仅在此之后，所有数据才会被转换为较新的格式。

如果您遇到无法解决的错误，请确保旧版的 TeamCity 没有在运行 / 不会在启动时运行，重启机器，然后重复安装过程。

使用 .tar.gz 发行版

  1. 创建备份。

  2. 备份自上次安装以来定制的文件（最可能是 [TOMCAT_HOME] /conf/server.xml）

  3. 删除旧的安装文件（完全删除 <TeamCity 安装目录>）。 建议您在此之前备份目录。

  4. 将新的归档文件解压缩到之前安装 TeamCity 的位置。

  5. 如果您使用 Tomcat 服务器（自己的或者封装在 .tar.gz TeamCity 发行版中），建议删除 work 目录的内容。 请注意，这可能会影响部署在同一网络服务器中的其他 web 应用程序。

  6. 恢复在第2步中备份的自定义设置。 如果您有定制的 [TOMCAT_HOME] /conf/server.xml 文件，请将您的更改应用到默认文件的相应部分。

  7. 请确保先前配置的 TeamCity 服务器启动属性（如有）仍然有效。

  8. 启动 TeamCity 服务器。

  9. 请查阅 TeamCity Maintenance Mode 页面，确保没有遇到任何问题，并点击相应的按钮进行升级确认。 只有在此之后，所有的配置数据和数据库模式才会被 TeamCity 转换器更新。

使用 Docker 镜像

  1. 创建备份。

  2. 备份自上次安装以来定制的文件（最可能是 [TOMCAT_HOME] /conf/server.xml）

  3. 如果您已经构建了自己的 Docker 镜像，基于 TeamCity 服务器基础镜像的新版本重新构建您的 Docker 镜像。

  4. 调用 docker run 来在目标主机上启动新的容器（无论是 官方 TeamCity 镜像还是您重建的镜像）。

  5. 请查阅 TeamCity Maintenance Mode 页面，确保没有遇到任何问题，并点击相应的按钮进行升级确认。

升级多节点设置

多节点设置将您的TeamCity服务器执行的任务分配至多个单独的节点，这极大地提高了系统的稳定性和性能。 在此设置中，每个节点都需要进行单独升级。 参阅此部分以获取更多信息：升级/降级。

IDE 插件

我们建议所有用户定期将他们的 IDE 插件更新到与正在使用的 TeamCity 服务器版本兼容的最新版本 —— 至少是 TeamCity 服务器上的 工具 部分中提供的版本。
一般来说，IntelliJ IDEA TeamCity 插件和 Visual Studio TeamCity 插件的版本需要与 TeamCity 服务器版本保持一致。 使用不匹配插件版本的用户在尝试登录与版本不匹配的 TeamCity 服务器时会收到一条消息。

服务器回滚

在罕见的自动或手动服务器升级失败的情况下，您可以将 TeamCity 恢复到其之前的状态。 请参阅以下文章以获取更多信息：

升级构建代理

自动构建代理更新

在启动 TeamCity 服务器（以及更新服务器上的代理分发或插件）时，与服务器连接并且 正确安装 的 TeamCity 代理会自动更新至与服务器对应的版本。 这种情况既会在服务器升级时发生，也会在降级时发生。 如果代理上有正在运行的构建，那么该构建会完成。 除非代理与服务器同步更新，否则不会在代理上启动新的构建。

在开始代理升级之前，将对代理进行空闲磁盘空间检查，默认为 3 GB。 要修改升级所需的值，请配置 teamcity.agent.upgrade.ensure.free.space agent property。

代理更新流程如下：代理（ agent.bat、 agent.sh 或代理服务）将从 TeamCity 服务器下载当前的代理包。 当下载完成且代理处于空闲状态时，它将开始升级过程（代理已停止，代理文件已更新，并且代理已重新启动）。 根据代理硬件和网络带宽的不同，此过程可能需要几分钟的时间。 请不要中断升级过程，因为这样做可能会导致升级失败，您将需要手动重新安装代理。

如果您在 TeamCity UI 中看到一个代理被标识为 "Agent disconnected (Will upgrade)"，请不要关闭代理控制台或重新启动代理进程，而是等待几分钟。

在代理升级过程中，可以打开和关闭各种控制台窗口。 请耐心等待，直到代理升级完成后再进行其他操作。

手动更新构建代理

所有连接的代理会自动升级，只要他们被正确安装，因此不需要手动升级。

如果您需要手动升级 agent，您可以按照下面的步骤操作。

由于 TeamCity 代理不包含任何独特的信息，升级代理的最简单方式是：

  1. 备份 <Agent Home>/conf/buildAgent.properties 文件。

  2. 卸载 / 删除现有的代理。

  3. 安装新的代理版本。

  4. 将之前保存的 buildAgent.properties 文件恢复到相同的位置。

  5. 启动代理。

如果您需要保留所有的代理数据（例如，升级后避免进行清理检出），您可以：

  1. 停止代理。

  2. 删除代理安装中存在的代理 .zip 分发中的所有目录，除了 conf。

  3. 将 .zip 发行版解压到代理安装目录，跳过 "conf" 目录。

  4. 启动代理。

在后一种情况下，如果您在 Windows 下使用服务运行代理，您可能还需要按照 下面 的描述升级 Windows 服务。

升级 构建代理 Windows 服务包装器

如果服务包装器需要更新，新版本将下载到 <agent>/launcher.latest 目录中，但更改不会自动应用。

要手动升级服务包装器，请执行以下操作：

  1. 确保 <agent>/launcher.latest 文件夹存在。

  2. 使用 <agent>\bin\service.stop.bat 停止服务。

  3. 使用 service.uninstall.bat 卸载服务。

  4. 备份 <代理>/launcher/conf/wrapper.conf 文件。

  5. 删除 <agent>/启动器。

  6. 将 <agent>/launcher.latest 重命名为 <agent>/启动器。

  7. 编辑 <代理>/launcher/conf/wrapper.conf 文件。 检查 wrapper.java.command 属性是否指向 java.exe 文件。 将其留空以使用注册表查找 java。 请留下 java.exe 去查找 java.exe 在 PATH 中。 对于独立代理，服务值应为 ../jre/bin/java ，对于在服务器上安装的代理，值应为 ../../jre/bin/java。 wrapper.conf 文件的备份版本可以使用。

  8. 使用 <agent>\bin\service.install.bat 安装服务。

  9. 确保该服务正以正确的用户帐户运行。 请注意，使用 SYSTEM 可能会导致使用 MSBuild/Sln2005 配置的构建失败。

  10. 使用 <agent>\bin\service.start.bat 启动服务。

最后修改日期： 16日 7月 2024年
安装 Agent Tools 升级 DSL