TeamCity On-Premises 2026.1 Help

备忘单：在服务器和代理机器上更新 Java

本文简要介绍了代理和服务器机器上 Java 更新的过程。有关详细信息，请参阅以下文章。 有关详细信息，请参阅以下文章。

迁移至 Java 21

从版本 2026.1 开始，TeamCity 服务器和代理都需要 Java 21 才能启动。 TeamCity 服务器仅支持 Java 21，而 TeamCity 构建代理可以运行在更新的版本（例如 Java 25）。 我们计划在未来的发行版中正式支持最新的 Java 版本。

升级指南

升级过程主要包含两个基本步骤：

  1. 在机器上安装 Java 21。

  2. 确保 TeamCity 能检测并使用该安装版本。

具体过程取决于您的操作系统。

更新服务器

TeamCity Windows 安装程序和服务器 Docker 镜像中包含 Amazon Corretto 64 位 Java 21，因此您无需手动安装。 只需运行 TeamCity 2025.11 安装程序，它将提供所需的 JDK。

    TeamCity 服务器 .tar.gz 归档包不包含 Java，您需要手动安装。 请确保所安装的 JDK 与您的平台匹配。 例如， Amazon Corretto 21 提供适用于在 ARM64 和 x86_64 架构下运行的 Linux 与 macOS 系统的多个版本。

    安装 Java 21 后，将其安装路径分配给 JAVA_HOME 或 TEAMCITY_JRE 环境变量。 详细操作请参阅 此 StackOverflow 线程。

    • JAVA_HOME 是一个全局变量，用于指定您机器上的默认 JDK。 设置后， java -version 终端命令应指向相应版本。

    • TEAMCITY_JRE 变量仅被 TeamCity 使用，允许您为其他应用程序保留不同版本的 Java 作为默认值。

      更新代理

      要定位所有需要更新的代理（包括本地和 云代理），请前往 代理 | 概览 | 参数报告 ，并通过 teamcity.agent.jvm.specification 属性值筛选器筛选代理。

      过时代理报告

      要使用 REST API查找所有过时的代理：

      # Find outdated local agents curl --location --request GET 'http://$SERVER_URL/app/rest/agents?locator=parameter:(name:teamcity.agent.jvm.specification,value:21,matchType:does-not-match)&fields=count,agent(id,name,connected,authorized,properties($locator(name:teamcity.agent.jvm.specification),property(name,value)))' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer $TC_ACCESS_TOKEN' # Find outdated cloud profiles # Requires profiles to have at least one running agent curl --location --request GET 'http://$SERVER_URL/app/rest/cloud/profiles&fields=cloudProfile(id,name,images(cloudImage(id,name))&locator=image:(agent:(parameter:(name:teamcity.agent.jvm.specification,value:21,matchType:does-not-match))) \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer $TC_ACCESS_TOKEN'

      更新本地代理

      在升级代理机器之前，建议先卸载当前代理以避免潜在问题：

      1. 转到 代理主目录 ，运行 Uninstall.exe ，保留所有“Remove ...”复选框不选中，然后完成卸载。

      2. 在浏览器中打开 TeamCity UI 并登录。

      3. 在侧边导航栏中，打开 支持人员。

      4. 点击 安装代理 ，下载捆绑了 JDK 的 .exe 代理安装程序。

      5. 在每个需要更新的代理机器上运行该安装程序。

      如果构建代理作为服务运行，请确保 wrapper.java.command 属性在 <agent_home>/launcher/conf/wrapper.conf 文件中指向所需的 Java 版本。 有关详细信息，请参阅以下文章： 升级 构建代理 Windows 服务包装器。

        要更新代理机器，请遵循与服务器相同的操作流程。 或者，您也可以安装一个 已包含所需 JDK 的代理归档包。 具体操作如下：

        1. 在 TeamCity UI 中导航到 管理 | 代理 JDK。

        2. 点击 添加 JDK 上传所需 Java 版本。

        3. 一旦 TeamCity 下载了目标 JDK，相应选项将显示在 代理 | 安装代理 | 包含 JDK 的代理发行版 下方。 完整代理安装中包含 /jre 目录。 启动后，代理优先使用该目录中的 Java，而不是通过 JAVA_HOME 和 TEAMCITY_JRE 环境变量返回的版本。

          更新云代理

          云代理可以位于持久的云主机实例上，或从镜像启动的临时虚拟机上。 根据虚拟机类型和云主机提供商的不同，更新说明可能有所不同。 例如，对于以 EC2 AMIs为目标的 TeamCity 云配置文件，需要：

          1. 按照 更新本地代理部分的说明更新基础镜像，并确保该代理能成功连接到 TeamCity。

          2. 从该基础镜像构建新的 AMI。

          3. 将 TeamCity 云配置文件和镜像更新为以新的 AMI 为目标。

          无人值守 Java 升级

          如果通过软件包管理器（例如 Linux 上的 apt-get ）安装了 Java，可能会在不通知的情况下将 Java 升级到最新可用版本。 即使此版本受 TeamCity 支持，也可能会导致某些问题。 例如，正在运行的构建代理需要重启，否则无法找到正确的 JDK 并无法运行其任务。

          为避免这些潜在问题，建议手动安装 Java 并配置 JAVA_HOME 和 TEAMCITY_JRE 环境变量。 例如，可能需要通过运行以下命令来禁用 Ubuntu 无人值守升级：

          # Check the unattended upgrade status systemctl status unattended-upgrades # Stop the service sudo systemctl stop unattended-upgrades # Disable the service sudo systemctl disable --now unattended-upgrades # Edit the configuration file sudo nano /etc/apt/apt.conf.d/20auto-upgrades # TODO: Insert or edit the 'APT::Periodic::Unattended-Upgrade "0";' line in the config file
          2026年 8月 6日
          如何操作...Change（更改）