JBoss EAP XP 升级和迁移指南

Red Hat JBoss Enterprise Application Platform 7.4

从 JBoss EAP XP 2.0.x 升级和迁移到 JBoss EAP XP 3.0.0 的指南

摘要

This document provides information about upgrading JBoss EAP XP 2.0.x to JBoss EAP XP 3.0.0 and any necessary application migration.

使开源包含更多

红帽承诺替换我们的代码、文档和 Web 属性中存在问题的语言。我们从这四个术语开始:master、slave、黑名单和白名单。由于这一努力的力量,这些更改将在即将发布的几个版本中逐渐实施。详情请查看 CTO Chris Wright 信息

对红帽文档提供反馈

我们感谢您对我们文档的反馈。要提供反馈,您可以突出显示文档中的文本并添加注释。按照以下步骤了解提交对红帽文档的反馈。

先决条件

  • 登录红帽客户门户。
  • 在红帽客户门户中,以多页 HTML 格式查看文档。

流程

  1. 单击 Feedback 以查看现有读取器注释

    注意

    反馈功能仅以多页 HTML 格式启用。

  2. 突出显示您要提供反馈的文档中的部分。
  3. 在显示在您选择的文本附近的提示菜单中,单击 Add Feedback

    文本框将在页面右侧的"反馈"部分中打开。

  4. 在文本框中输入您的反馈,然后单击 Submit

    您已创建了文档问题。

  5. 要查看问题,请单击反馈视图中的问题跟踪器链接。

第 1 章 JBoss EAP XP 升级

1.1. 升级和迁移

使用 JBoss EAP XP 升级和迁移指南中所述的步骤准备、升级您的 JBoss EAP XP 2.0.x 产品,并将其迁移到 JBoss EAP XP 3.0.0 产品。JBoss EAP XP 3.0.0 仅兼容 JBoss EAP 7.4。如果您在 JBoss EAP 7.3 上运行服务器,并且希望对其应用 JBoss EAP XP 3.0.0 修补程序,您必须首先将 JBoss EAP 7.3 实例升级到 JBoss EAP 7.4。

本指南参考可用于升级和迁移过程的工具。这些工具如下:

  • 应用迁移工具(MTA)
  • JBoss 服务器迁移工具

在成功将 JBoss EAP XP 2.0.x 版本升级到 JBoss EAP XP 3.0.0 后,您就可以开始为 JBoss EAP 7.4 实例实施任何应用迁移。

其他资源

1.2. 准备升级和迁移

升级 JBoss EAP 扩展包后,您可能需要更新应用代码。

对于 JBoss EAP XP 3.0.0,JBoss EAP XP 2.0.x 应用程序可能会有一些向后兼容性。但是,如果您的应用使用已弃用的功能或从 JBoss EAP XP 2.0.x 中删除的功能,您可能需要更改应用代码。

在开始迁移过程前,请查看以下新项目:

  • JBoss EAP XP 3.0.0 版本中添加的功能.
  • JBoss EAP XP 3.0.0 中添加的 MicroProfile 功能.
  • 对现有 MicroProfile 功能的增强.
  • JBoss EAP XP 3.0.0 中弃用的功能和功能.
  • 从 JBoss EAP XP 3.0.0 中删除的功能和功能。
  • 您可用来从一个 EAP XP 版本迁移到另一个版本的工具。

检查列出的项目后,分析您的环境并规划升级过程和迁移过程。确保您备份计划迁移到 JBoss EAP XP 3.0.0 的任何应用。

现在,您可以将当前的 JBoss EAP XP 2.0.x 版本升级到 JBoss EAP XP 3.0.0。您可以在升级过程后实施任何应用程序迁移

其他资源

1.3. 新的 JBoss EAP XP 功能

JBoss EAP XP 3.0.0 包括新功能,可增强红帽对 JBoss EAP 应用对 MicroProfile 规范的实施。

注意

MicroProfile 被动消息传递子系统支持红帽 AMQ 流。此功能实施 MicroProfile 主动消息传递 1.0 API,红帽提供作为 JBoss EAP XP 3.0.0 技术预览的功能。

红帽在 JBoss EAP 上测试了红帽 AMQ Streams 2021.Q2。但是,请查看红帽 JBoss 企业应用平台支持的配置页面,以获取有关已在 JBoss EAP XP 3.0.0 上测试的最新红帽 AMQ Streams 版本的信息。

JBoss EAP XP 3.0.0 发行版本包括以下新功能:

  • 启动应用后运行 CLI 脚本。
  • 使用 --cli-script=<path to CLI script> 参数在运行时更新可引导 JAR 文件的服务器配置。
  • 使用 MicroProfile 响应消息传递 1.0 API 在微服务之间发送和接收消息。
  • 使用 MicroProfile 响应消息传递 1.0 API 编写和配置用户应用,以便应用能够高效、异步地发送、接收和处理事件流。
  • 在服务器配置中启用 MicroProfile 响应功能,因为 MicroProfile 被动消息传递仅在服务器上预安装。
  • 查看通过 MicroProfile 被动消息传递通过 Kafka 快速入门进行 MicroProfile 响应消息,了解如何在服务器上完成以下任务:

    • 启用 MicroProfile 响应消息传递子系统。
    • 使用 MicroProfile 被动消息传递运行和测试应用,以发送数据并从红帽 AMQ Streams 接收数据。

其他资源

1.4. 对 MicroProfile 功能的增强

JBoss EAP XP 3.0.0 版本包括对以下 MicroProfile 4.0 组件的支持:

  • MicroProfile Config
  • MicroProfile 容错
  • MicroProfile Health
  • MicroProfile JWT
  • MicroProfile Metrics
  • MicroProfile OpenAPI
  • MicroProfile OpenTracing
  • MicroProfile REST Client

其他资源

1.5. 已弃用且不支持的 MicroProfile 功能

将应用迁移到 JBoss EAP XP 3.0.0 之前,请注意 JBoss EAP XP 2.0.x 中提供的一些功能可能已弃用或不再受支持。

由于维护成本高、社区兴趣较低和更好的替代解决方案,红帽移除了对部分技术的支持。

确保您查阅红帽 JBoss EAP XP 3.0.0 发行说明指南和 7.4.0 发行说明指南,以了解任何不受支持的和已弃用的功能。

其他资源

第 2 章 从 JBoss EAP XP 2.0.x 服务器迁移到 JBoss EAP XP 3.0.0 服务器的工具

您可以选择以下工具之一来升级 JBoss EAP XP 2.0.x 产品并将其迁移到 JBoss EAP XP 3.0.0 产品:

  • 应用迁移工具(MTA)
  • JBoss 服务器迁移工具

2.1. 使用 JBoss 服务器迁移工具迁移您的服务器配置

更新服务器配置时使用 JBoss 服务器迁移工具,使其包含 JBoss EAP XP 3.0.0 的新功能和设置。如果 JBoss EAP XP 3.0.0 支持配置,您可以保留现有的 JBoss EAP XP 2.0.x 服务器配置。

JBoss 服务器迁移工具读取您现有的 JBoss EAP XP 2.0.x 服务器配置文件,并将任何新的所需子系统添加到这些文件中。该工具还使用新功能更新现有的子系统配置,同时移除任何过时的子系统配置。

您可以使用 JBoss 服务器迁移工具为您的 JBoss EAP XP 3.0.0 配置迁移受管域中的单机服务器和服务器。

JBoss EAP XP 3.0.0 包括 JBoss 服务器迁移工具,因此您无需下载文件并安装 工具。发出 jboss-server-migration 脚本(位于 EAP_HOME/bin 目录中)以启动该工具。

其他资源

2.2. 使用 Migration Toolkit for Application 分析应用程序进行迁移

Migration Toolkit for Application(MTA)包括可扩展且可自定义的基于规则的工具,可简化 Jakarta 应用程序的迁移。您可以使用工具包来分析应用的 API、技术和架构。该工具包为您提供了您计划从 JBoss EAP XP 2.0.x 迁移到 JBoss EAP XP 3.0.0 的应用的报告。

您可以使用 MTA 分析标准 JBoss EAP 应用和可引导 JAR 应用。

MTA 报告输出以下信息:

  • 对所有所需迁移更改的详细解释.
  • 更改是必须的还是可选的。
  • 无论更改是复杂还是简单。
  • 需要迁移更新的代码链接。
  • 用于帮助您完成所需迁移更改的信息提示和链接。
  • 估算发现的每个迁移问题的工作量,以及迁移应用的总预计工作量。

您还可以使用 MTA 分析 JBoss EAP XP 2.0.x 应用的代码和架构,然后再将其迁移到 JBoss EAP XP 3.0.0。迁移到 JBoss EAP XP 3.0.0 时,用于将应用从 JBoss EAP XP 2.0.x 迁移到 JBoss EAP XP 3.0.0 的 MTA 规则集可报告 XML 描述符、特定应用代码和参数。

2.3. 从 JBoss EAP 7.3 及更早版本升级

JBoss EAP XP 3.0.0 仅支持 JBoss EAP 7.4。

如果您在 JBoss EAP 7.3 或更早版本上运行服务器,并希望使用 JBoss EAP XP,请将服务器升级到 JBoss EAP 7.4。尝试安装 JBoss EAP XP 之前完成任何必要的迁移。

其他资源

2.4. MicroProfile 应用迁移

MicroProfile 4.0 基于 Jakarta EE 8 平台。虽然 Jakarta EE 8 与 Java EE 8 的 API 向后兼容,但 Jakarta EE 8 依赖性取代了所有 MicroProfile 规范的 Java EE 8 依赖关系。

MicroProfile 4.0 包含对所有主要 MicroProfile 规范的更新。

以下规范包括 MicroProfile 4.0 的 API 兼容更改:

  • MicroProfile Config
  • MicroProfile 容错
  • MicroProfile Health
  • MicroProfile Metrics
  • MicroProfile OpenAPI

您必须将这些规格的应用更新为最新的 Jakarta EE 8 规格。

您可以通过选择以下方法之一将您的应用更新为 MicroProfile 4.0:

  • 将 MicroProfile 4.0 依赖项添加到项目的 pom.xml 文件中。
  • 使用 JBoss EAP XP BOM 将支持的工件导入到您项目的 pom.xml 文件的 JBoss EAP XP 依赖关系管理中。

其他资源

  • 如需有关 MicroProfile 4.0 以及用于更新应用以使用 MicroProfile 4.0 的选项的更多信息,请参阅 GitHub 上的 MicroProfile 4.0

2.5. 可引导 JAR 应用程序迁移

将 JBoss EAP XP 2.0.0 可引导 JAR 应用迁移至 JBoss EAP XP 3.0.0 之前,您可能需要更新 JBoss EAP XP 可引导 JAR Maven 插件配置。

对于 JBoss EAP XP 3.0.0,extraServerContentDirs 配置元素取代了 extraServerContent 配置元素。这个元素命名替换与预先存在的 extra-server-content-dirs 元素一致。

如果您在 JBoss EAP Maven 插件配置中使用 extraServerContent 元素,则必须将此元素替换为 extraServerContentDirs 元素。如果您使用了 extra-server-content-dirs 元素,则不需要进行任何配置更改。

第 3 章 Thorntail 应用程序 Maven 项目迁移

红帽构建的 Thorntail 即将结束其生命周期。如果您有一个 Thorntail 应用,您可以将应用的 Maven 项目迁移到 JBoss EAP XP。Thorntail 应用程序通过两种方式打包:

  • 将 Thorntail 运行时打包为 Uberjar,一个可执行 JAR,
  • 打包在标准 WAR 存档中,以在 Thorntail 尾部 JAR 中部署和运行,这是仅运行时可执行文件 JAR.

迁移至 JBoss EAP XP 时,可以将 Thorntail 应用打包为可引导 JAR 并修剪 JBoss EAP XP 运行时,以包含 MicroProfile 平台和应用依赖的其他技术。

将应用迁移到 JBoss EAP XP 时,您必须移除任何 Thorntail 部分依赖项,并将任何必需的 MicroProfile 和 Jakarta EE 8 规范的构件添加到 Maven 项目依赖项中。

注意

您可以在运行时使用 JBoss CLI 工具或 JBoss EAP Web 控制台来更改服务器配置。但是,与打包期间所做的配置更改不同,在运行时对配置所做的任何更改都不会保留,在您重新启动可引导 JAR 时会丢失。

3.1. 将 Thorntail 应用 Maven 项目迁移到 JBoss EAP XP

如果您的 Thorntail 应用程序依赖于诸如 Jakarta Enterprise Beans、Jakarta 服务器 Faces、Jakarta Connector API、SOAP Web 服务或 CORBA 等技术,您可以将应用程序的 Maven 项目迁移到 JBoss EAP XP。

Galleon 层用于配置 JBoss EAP XP 运行时在可引导 JAR 中打包的功能。当您迁移使用 Jakarta EE 8 规格的 Thorntail 应用程序时,您必须将相关的 Galleon 层添加到可引导 JAR Maven 插件配置中。

使用 Galleon 层时,JBoss EAP XP 生成服务器配置并将其打包在可引导 JAR 中。如果没有使用 Galleon 层,则在可引导 JAR 中打包与默认 standalone-microprofile.xml 相同的配置。

如果您使用 <cloud> 配置元素为云构建可引导 JAR,则与默认 standalone-microprofile-ha.xml 类似的 OpenShift 配置会应用到您的可引导 JAR。

可引导 JAR Maven 插件在打包可引导 JAR 的 JAR 时执行 JBoss CLI 脚本。

流程

  1. 删除任何 Thorntail BOM 导入。

    pom.xml 文件中删除 io.thorntail Thorntail BOM 导入的示例。

    <dependencyManagement>
      <dependencies>
        <dependency>
          <groupId>io.thorntail</groupId>
          <artifactId>bom</artifactId>
          <version>${version.thorntail}</version>
          <type>pom</type>
          <scope>import</scope>
        </dependency>
      </dependencies>
    </dependencyManagement>

  2. 使用 JBoss EAP XP BOM 将受支持的构件导入到 JBoss EAP XP 依赖关系管理。

    使用 jboss-eap-jakartaee8-with-tools BOM 将支持的工件导入到项目的示例。

    <dependencyManagement>
            <dependencies>
                <!-- importing the jakartaee8-with-tools BOM adds specs and other useful artifacts as managed dependencies -->
                <dependency>
                    <groupId>org.jboss.bom</groupId>
                    <artifactId>jboss-eap-jakartaee8-with-tools</artifactId>
                    <version>${version.server.bom}</version>
                    <type>pom</type>
                    <scope>import</scope>
                </dependency>
                <!-- importing the microprofile BOM adds MicroProfile specs -->
                <dependency>
                    <groupId>org.jboss.bom</groupId>
                    <artifactId>jboss-eap-xp-microprofile</artifactId>
                    <version>${version.microprofile.bom}</version>
                    <type>pom</type>
                    <scope>import</scope>
                </dependency>
            </dependencies>
        </dependencyManagement>

    注意

    仅在您的应用依赖于 MicroProfile 平台中不包含的 Jakarta EE 8 规范时导入 jakartaee8-with-tools BOM。

  3. 将 Thorntail Maven 插件替换为 JBoss EAP XP 可引导 JAR Maven 插件。

    演示如何将 Thorntail Maven 插件替换为 JBoss EAP XP 可引导 JAR Maven 插件。

    <plugin>
       <groupId>org.wildfly.plugins</groupId>
       <artifactId>wildfly-jar-maven-plugin</artifactId>
       <version>${bootable.jar.maven.plugin.version}</version>
       <configuration>
          <feature-pack-location>${org.jboss.eap:wildfly-galleon-pack:${jboss.xp.galleon.feature.pack.version}</feature-pack-location>
          <layers>
             <layer>microprofile-platform</layer>
          </layers>
       </configuration>
       <executions>
          <execution>
             <goals>
                <goal>package</goal>
             </goals>
          </execution>
       </executions>
    </plugin>

    注意

    上例为 Maven 插件版本指定以下属性:

    ${bootable.jar.maven.plugin.version}

    您必须将 Maven 插件版本设置为在项目中替换此属性。例如:

    <properties>
        <bootable.jar.maven.plugin.version>4.0.3.Final-redhat-00001</bootable.jar.maven.plugin.version>
    </properties>
    • 可引导 JAR 插件默认构建 UberJAR,这意味着它将 JBoss EAP XP 运行时与所部署的应用进行打包。要构建 hollow JAR,请在插件配置中添加 <hollow-jar>true</hollow-jar>
  4. 对 Maven 项目中的 Thorntail 部分进行以下更改:

    1. 删除 Thorntail 部分依赖项。

      显示从 Maven 项目中删除 io.thorntail Thorntail 部分的示例。

      <dependencies>
        <dependency>
          <groupId>io.thorntail</groupId>
          <artifactId>jaxrs</artifactId>
        </dependency>
      </dependencies>

    2. 配置 Maven 依赖项。

      使用 XML 代码段添加依赖项到 Jakarta EE 8 JAX-RS 和 MicroProfile Config API 的构件的示例。

      <dependencies>
          <!-- Import the MicroProfile Config API, we use provided scope as the API is included in the server -->
          <dependency>
            <groupId>org.eclipse.microprofile.config</groupId>
            <artifactId>microprofile-config-api</artifactId>
            <scope>provided</scope>
          </dependency>
          <!-- Import the Jakarta REST API, we use provided scope as the API is included in the server -->
          <dependency>
            <groupId>org.jboss.spec.javax.ws.rs</groupId>
            <artifactId>jboss-jaxrs-api_2.1_spec</artifactId>
            <scope>provided</scope>
          </dependency>
        </dependencies>

    3. 删除 Thorntail YAML 文件、系统属性和环境属性。
    4. 配置 Galleon 层.

      为需要 JAX-RS 的应用在可引导 JAR Maven 插件中配置 Galleon 层的示例:

      <plugin>
        <groupId>org.wildfly.plugins</groupId>               <artifactId>wildfly-jar-maven-plugin</artifactId>                  <configuration>
         ...
            <layers>
              <layer>jaxrs-server</layer>
              <layer>microprofile-platform</layer>
            </layers>
        </configuration>
         ...
      </plugin>

其他资源