内容

目录

一般性

请首先阅读通用的迁移指南页面，以了解适用于 Apache Tomcat® 各版本之间迁移或升级的常见注意事项。

从 9.0.x 迁移到 10.0.x

本节列出了 9.0.x 和 10.0.x 之间所有已知的、可能在升级时导致向后兼容性问题的变更。

要求 Java 8

Apache Tomcat 10.0.x 要求 Java 8 或更高版本。这与 Tomcat 9.0.x 保持不变。

规范 API

Apache Tomcat 10 支持 Jakarta Servlet 5.0、Jakarta Pages 3.0、Jakarta Expression Language 4.0、JakartaWebSocket 2.0 和 Jakarta Authentication 2.0 规范。

Tomcat 9.0.x 和 Tomcat 10.0.x 之间存在一项重大破坏性变更。规范 API 所使用的 Java 包已从javax...变为jakarta...。您将需要针对新的 API 重新编译 Web 应用程序。

Tomcat 可以在部署时使用 Apache Tomcat Jakarta EE 迁移工具将现有 Web 应用程序从 Java EE 8 转换为 Jakarta EE 9。要使用此功能，Web 应用程序应放置在 Host 的 legacyAppBase 文件夹中（默认命名为 webapps-javaee），它们将被转换为 Host 的 appBase 文件夹（默认命名为 webapps）中的等效 Jakarta EE Web 应用程序。

或者，Apache Tomcat Jakarta EE 迁移工具或任何类似的转换工具都可提前使用，以便受益于更快的部署时间和更精确的转换配置选项。

Servlet 5.0 API

Java 包已从javax.servlet变为jakarta.servlet.

Pages 3.0

Java 包已从javax.servlet.jsp变为jakarta.servlet.jsp.

表达式语言 4.0

Java 包已从javax.el变为jakarta.el.

WebSocket 2.0

Java 包已从javax.websocket变为jakarta.websocket.

身份验证 2.0

Java 包已从javax.security.auth.message变为jakarta.security.auth.message.

内部 API

尽管 Tomcat 10 内部 API 与 Tomcat 9 大致兼容，但在细节层面存在许多变更，并且它们不具备二进制兼容性。与 Tomcat 内部机制交互的自定义组件开发者应查阅相关 API 的 JavaDoc。

特别值得注意的是

  • GenericPrincipal.getPassword()已被移除。

系统属性

许多 Tomcat 特定的系统属性支持已被移除，并由 Connector、Context 或 Manager 等相应组件上的属性所取代。

web.xml 默认设置

conf/web.xml 将默认请求和响应字符编码设置为 UTF-8。

会话管理

会话在重启时默认禁用持久化。它可以在以下位置全局重新启用：conf/context.xml或针对每个 Web 应用程序启用。

HTTP/2

在 HTTP/1.1 和 HTTP/2 连接器之间重复的配置设置已从 HTTP/2 连接器中移除，HTTP/2 连接器现在将从相关的 HTTP/1.1 连接器继承这些设置。

日志

日志实现现在仅在有内容写入日志文件时才创建日志文件。

访问日志模式

为与 httpd 对齐，%D 模式现在记录请求时间为微秒而非毫秒。要以毫秒记录请求时间，请使用 %{ms}T。

升级 10.0.x

当将 Apache Tomcat 实例从 Tomcat 10 的一个版本升级到另一个版本时，特别是在为 $CATALINA_HOME 和 $CATALINA_BASE 使用不同位置时，需要确保将配置文件中的任何更改（例如新属性和默认值的更改）作为升级的一部分应用。为帮助识别这些变更，可以使用下方表格查看 Tomcat 10 不同版本中配置文件之间的差异。

Tomcat 10.0.x 显著变更

Tomcat 开发者旨在使每个补丁版本完全向后兼容之前的版本。偶尔，为了修复 Bug，有必要破坏向后兼容性。在大多数情况下，这些变更将不会被察觉。本节列出了并非完全向后兼容的变更，这些变更在升级时可能会导致问题。

  • 从 10.0.3 版本开始，HostConfig.check(String) 方法的语义已更改。该方法不再是在调用前将应用程序标记为已服务，而是在检查资源前将其标记为已服务，并在检查完成后取消标记为已服务。如果在调用该方法时应用程序已被标记为已服务，则该方法将是一个空操作（NO-OP）。

  • 从 10.0.9 版本开始，由于 CONFIDENTIAL 传输保证，Tomcat 在添加 "Cache-Control: private" 时不再添加 "Expires" HTTP 响应头。这可能会导致那些未明确设置自身头信息但依赖 Tomcat 之前行为的应用程序的缓存行为发生变化。如果您希望禁用缓存，则需要在应用程序中明确配置。有关更多信息，请参阅 BZ 65513。

  • 从 10.0.11 版本开始，由于 Commons FileUpload 的更新分支现在使用 java.nio.file.Files，使用多部分上传的应用程序需要确保 JVM 配置了足够的直接内存以存储所有正在进行的多部分上传。

  • 从 10.0.14 版本开始，系统属性 org.apache.juli.AsyncLoggerPollInterval 不再使用。

Tomcat 10.0.x 配置文件差异

从下方方框中选择配置文件、旧版本和新版本，然后点击“查看差异”以查看差异。差异将在新的标签页/窗口中显示。

注意： 如果没有差异，您将看到一个错误页面。

您也可以在工作副本中运行类似于以下的 Git 命令：

git diff 10.0.0 10.0.12 -- conf/