Apache Tomcat^®

Apache Tomcat 7.0.x 需要 Java 6 或更高版本。Apache Tomcat 6.0.x 需要 Java 5。

Apache Tomcat 7 支持 Java Servlet 3.0、JavaServer Pages 2.2、Expression Language 2.2 和 WebSocket 1.1 规范。各规范版本之间的更改可在每个规范文档的“变更”附录中找到。

在使用通配符导入语法的 JSP 页面中，Servlet API 中新增的类可能与 Web 应用程序中的类发生冲突。例如，如果包 "a" 包含类 Part，则以下 JSP 页面在 Tomcat 7 中将无法编译。

<%@page import="a.*"%>
<% Part page = new Part(); %>

这是因为 javax.servlet.http.* 的隐式导入和 a.* 的显式导入将提供在 Servlet 3.0 中添加的类 Part 的冲突定义。解决方案是使用显式导入，import="a.Part"。

所有使用正则表达式的配置选项现在都需要一个正则表达式（使用 java.util.regex），而不是逗号分隔或分号分隔的表达式列表。

这涉及到以下内容：

• RemoteAddrFilter、RemoteHostFilter 过滤器 和 RemoteAddrValve、RemoteHostValve 阀门 中的 allow 和 deny 属性；
• 在 RemoteIpFilter、RemoteIpValve 中的 internalProxies、trustedProxies 属性；
• ReplicationValve 中的 filter 属性；
• HTTP 连接器 中的 restrictedUserAgents、noCompressionUserAgents 属性。

请注意，单独的正则表达式可以使用“|”运算符（或）进行连接。使用“|”在当前版本和更早的 Tomcat 版本中都有效。

XML 上下文描述符（META-INF/context.xml 文件）不再从已部署的 WAR 文件和目录复制到主机的 xmlBase。通过将 Host 元素的 copyXML 属性设置为 true，可以启用默认的 Tomcat 6 行为。

在 7.0.12 到 7.0.47（含）版本中，位于主机 appBase 之外的 WAR 文件不会被解压，无论 Host 的 unpackWARs 设置为何值。请注意，此解压功能仅在 7.0.48 及更高版本中支持。参见问题 51294。

Manager 应用程序在 Tomcat 7 及更高版本中进行了重构，并且一些 URL 已更改。现在，所有用于访问 Manager 应用程序的 URL 都应以以下选项之一开头：

• <ContextPath>/html 用于 HTML GUI
• <ContextPath>/text 用于文本界面
• <ContextPath>/jmxproxy 用于 JMX 代理
• <ContextPath>/status 用于状态页面

请注意，文本界面的 URL 已从“<ContextPath>”更改为“<ContextPath>/text”。

使用 Manager 应用程序所需的角色从单一的 manager 角色更改为以下四个角色。您需要分配访问所需功能的一个或多个角色。

• manager-gui - 允许访问 HTML GUI 和状态页面
• manager-script - 允许访问文本界面和状态页面
• manager-jmx - 允许访问 JMX 代理和状态页面
• manager-status - 仅允许访问状态页面

HTML 界面受 CSRF 保护，但文本和 JMX 界面不受保护。为了保持 CSRF 保护：

• 具有 manager-gui 角色的用户不应被授予 manager-script 或 manager-jmx 角色。
• 如果 Manager 应用程序通过浏览器由具有 manager-script 或 manager-jmx 角色的用户访问（例如，用于测试文本或 JMX 界面，因为这些界面旨在用于工具而非人类），则之后必须关闭所有浏览器窗口以终止会话。

roles 命令已从 Manager 应用程序中删除，因为它在默认配置下不起作用，并且大多数 Realm 不支持提供角色列表。

Host Manager 应用程序在 Tomcat 7 及更高版本中进行了重构，并且一些 URL 已更改。现在，所有用于访问 Host Manager 应用程序的 URL 都应以以下选项之一开头：

• <ContextPath>/html 用于 HTML GUI
• <ContextPath>/text 用于文本界面

请注意，文本界面的 URL 已从“<ContextPath>”更改为“<ContextPath>/text”。

使用 Host Manager 应用程序所需的角色已从单一的 admin 角色更改为以下两个角色。您需要分配访问所需功能的一个或多个角色。

• admin-gui - 允许访问 HTML GUI 和状态页面
• admin-script - 允许访问文本界面和状态页面

HTML 界面受 CSRF 保护，但文本界面不受保护。为了保持 CSRF 保护：

• 具有 admin-gui 角色的用户不应被授予 admin-script 角色。
• 如果 Host Manager 应用程序通过浏览器由具有 admin-script 角色的用户访问（例如，用于测试文本界面，因为此界面旨在用于工具而非人类），则之后必须关闭所有浏览器窗口以终止会话。

会话管理器进行了一些更改，以提高会话生成和销毁的性能，包括会话 ID 生成的更改。会话 ID 生成的更改利用了 java.secure.SecureRandom 自会话 ID 生成首次编写以来的改进。配置更改如下：

• Manager 的 randomClass 属性已更改为 secureRandomClass，并且提供的类必须扩展 java.secure.SecureRandom。
• 添加了两个新属性 secureRandomAlgorithm 和 secureRandomProvider，以启用 SecureRandom 实现的选择。
• algorithm 属性已被移除
• entropy 属性已被移除

java.secure.SecureRandom 的一个已知问题是其初始化需要熵源提供一些随机数据。对于某些熵源实现，可能需要一些时间来收集足够的随机数据。如果会话 ID 生成器的初始化时间过长（超过 100 毫秒），将记录一条诊断消息。例如：

日期 org.apache.catalina.util.SessionIdGenerator createSecureRandom
信息：使用 [SHA1PRNG] 创建用于会话 ID 生成的 SecureRandom 实例耗时 [406] 毫秒。

可以通过定义系统属性来更改 JRE 使用的熵源。例如：
-Djava.security.egd=file:/dev/./urandom

上述值中的“/./”字符是为了解决 JRE 问题 #6202721。

随着 Servlet 3.0 规范中 SessionCookieConfig 的添加，为了减少配置和代码复杂性，一些会话 Cookie 配置选项已被移除。

• Connector.emptySessionPath：此属性已移除。通过在全局 context.xml 中（在 CATALINA_BASE/conf/context.xml 中）配置 sessionCookiePath="/" 可以获得等效效果。
• org.apache.catalina.SESSION_COOKIE_NAME 系统属性：此属性已移除。通过为全局 context.xml（在 CATALINA_BASE/conf/context.xml 中）配置 sessionCookieName 属性可以获得等效效果。
• org.apache.catalina.SESSION_PARAMETER_NAME 系统属性：此属性已移除。通过为全局 context.xml（在 CATALINA_BASE/conf/context.xml 中）配置 sessionCookieName 属性可以获得等效效果。
• Context.disableURLRewriting：此属性已移除。通过在 Web 应用程序或全局 CATALINA_BASE/conf/web.xml 文件中配置 session-config/tracking-mode 元素可以获得等效效果。

Tomcat 7 中的会话和 SSO Cookie 默认发送 HttpOnly 标志，以指示浏览器阻止 JavaScript 访问这些 Cookie。这被认为更安全，但会阻止 JavaScript 访问 Cookie 的值。此功能可以通过 Context 元素上的 useHttpOnly 属性进行控制。（此功能也在 Tomcat 6.0 的最新版本中实现，但默认关闭。可以通过在 Web 应用程序或全局 CATALINA_BASE/conf/context.xml 文件中的 Context 元素上设置 useHttpOnly="true" 来启用此功能）。

Tomcat 默认不再接受不符合规范的仅有名称的 Cookie。但是，已添加一个新的系统属性 org.apache.tomcat.util.http.ServerCookie.ALLOW_NAME_ONLY，可用于接受仅有名称的 Cookie。

如果 Cookie 值或路径包含需要引用（根据 RFC2109 规范）的字符，则在发送到客户端之前，Cookie 将自动从“版本 0”Cookie 转换为“版本 1”Cookie，并且这些值将被双引号括起来。需要引用哪些字符由多个 系统属性 控制，例如 org.apache.tomcat.util.http.ServerCookie.FWD_SLASH_IS_SEPARATOR。已知 Internet Explorer 在处理“版本 1”Cookie 时存在问题。（Bug 57872）。

用于访问 SSL 会话 ID 的自定义请求属性 javax.servlet.request.ssl_session 已被弃用，取而代之的是 Servlet 规范中定义的新标准请求属性 javax.servlet.request.ssl_session_id。对自定义属性的支持将在 Tomcat 8 中移除。

为确保 Comet 在安全管理器下能正常工作，Comet 类已从 org.apache.catalina 包移动到 org.apache.catalina.comet 包。使用 Comet 的代码需要更新并重新编译，以反映新的包名。

XML 验证的配置已简化。xmlValidation 和 xmlNamespaceAware 属性已从 Host 元素中移除。这些属性，以及 tldValidation 和 tldNamespaceAware，现在按 Context 元素设置。默认值（每个属性均为 false）未更改。但是，根据 Servlet 规范的要求，如果系统属性 org.apache.catalina.STRICT_SERVLET_COMPLIANCE 设置为 true，XML 验证和命名空间感知将默认启用。

org.apache.catalina.STRICT_SERVLET_COMPLIANCE 系统属性已被修改，以对其效果提供更大的控制。现在，每个行为更改都由一个专用的系统属性控制。默认行为不变。org.apache.catalina.STRICT_SERVLET_COMPLIANCE 系统属性现在控制是否对其他系统属性使用符合规范的默认值。即使 org.apache.catalina.STRICT_SERVLET_COMPLIANCE 为 true，设置单个系统属性也将始终优先。

org.apache.coyote.MAX_TRAILER_SIZE 已被移除，并由 Connector 的 maxTrailerSize 属性取代。

Servlet 3.0 规范定义了如何将应用程序的 web.xml 文件与 Web 片段和注解结合。作为实现这些规则的结果，定义服务器范围默认值的全局 conf/web.xml 文件的处理方式发生了变化。

一个显著的区别是，全局 conf/web.xml 中定义的过滤器现在遵循 Web 应用程序中定义的过滤器，而不是在其之前。有关澄清，请参阅问题 51754 和 52138。

欢迎文件处理已更改，以遵循 Servlet 3.0 规范中的澄清。如果您的欢迎文件列表包含由 Servlet 处理的文件（如 *.jsp），您可能会观察到行为变化。请参阅 Context 上的 resourceOnlyServlets 选项。

Servlet 3.0 规范要求的注解扫描可能会影响 Web 应用程序的启动时间，并增加加载扫描类所需的内存。请注意，根据 Servlet EG 的澄清，即使使用 Servlet 2.4 及更早版本规范的应用程序也会被扫描。请参阅问题 53619 以及用户邮件列表上的相关讨论。

有几种方法可以解决这个问题。建议的方法是将那些不需要注解扫描的应用程序标记出来。这可以通过在应用程序的 WEB-INF/web.xml 中执行以下步骤来完成：

• 更新 web-app 元素以指示 Web 应用程序正在使用规范版本 3.0。您可以从默认的 conf/web.xml 文件中复制 version、xsi:schemaLocation、xmlns 和 xmlns:xsi 属性的值。
• 将 metadata-complete="true" 属性添加到 web-app 元素。
• 添加一个空的 <absolute-ordering /> 元素。

metadata-complete 属性从 Servlet 2.5 规范开始支持。absolute-ordering 元素需要 Servlet 3.0。

第二种方法是配置 JarScanner 组件以根据 JAR 文件的名称忽略某些文件。这通常在 conf/catalina.properties 文件中配置。有关详细信息，请参阅配置参考的系统属性章节中 jarsToSkip 属性的文档。从 Tomcat 7.0.30 开始，可以单独配置哪些 JAR 用于 Servlet 3.0 扫描（扫描注解和 Web 应用程序片段）、TLD 扫描（标签库）或两者都被跳过。Tomcat 的后续版本可能会提供更好的方式来控制此功能。

TLD 处理已进行了多项改进。除了为提高一致性和减少重复而进行的一些内部重构之外，还有一些功能改进。这些改进包括：

• 标签文件中的 EL 处理现在与为该标签文件声明的 JSP 版本保持一致。
• JSP 规范 JSP.7.3.1 节的要求现已强制执行，TLD 文件不允许放置在 WEB-INF/lib 或 WEB-INF/classes 中。

虽然 Tomcat 7 内部 API 与 Tomcat 6 大致兼容，但在细节层面存在许多更改，并且它们不具备二进制兼容性。与 Tomcat 内部交互的自定义组件开发人员应查阅相关 API 的 JavaDoc。

特别值得注意的是：

• 所有组件都扩展的 Lifecycle 接口的标准实现。
• 泛型的使用。
• 使用 Context 名称而不是 Context 路径作为 Host 中 Context 的唯一标识符。

JspServlet 的初始化参数，用于控制性能优化之一，已从 genStrAsCharArray 重命名为 genStringAsCharArray，现在与 Apache Ant 的 Jasper 任务中相关属性的名称保持一致。

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

• 从 7.0.51 开始，Web 应用程序类加载器现在比系统类加载器具有更高的类加载优先级。

• 从 7.0.63 开始，连接器上 maxPostSize 属性值 0 的含义已更改为表示零限制，而不是无限制，以便与 maxSavePostSize 对齐，并使其更直观。

  参考：HTTP 连接器，AJP 连接器。

• 从 7.0.100 开始，AJP 连接器的默认监听 地址 更改为环回地址，而不是所有地址。

  参考：AJP 连接器。

• 从 7.0.100 开始，AJP 连接器的 requiredSecret 属性已被弃用，并由 secret 属性取代。

  参考：AJP 连接器。

• 从 7.0.100 开始，secretRequired 属性已添加到 AJP 连接器中。如果设置为 true（默认值），AJP 连接器将不会启动，除非已指定 secret。

  参考：AJP 连接器。

• 从 7.0.100 开始，allowedRequestAttributesPattern 属性已添加到 AJP 连接器中。带有无法识别属性的请求现在将被 403 阻止。

  参考：AJP 连接器。

将 Apache Tomcat 实例从 Tomcat 7 的一个版本升级到另一个版本时，尤其是在 $CATALINA_HOME 和 $CATALINA_BASE 使用不同位置的情况下，必须确保配置文件中的任何更改（例如新属性和默认值的更改）作为升级的一部分应用。为了帮助识别这些更改，可以使用下面的表单来查看不同 Tomcat 7 版本之间配置文件的差异。

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

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

您还可以在工作副本中执行类似于以下的 Git 命令

git diff 7.0.0 7.0.80 -- conf/