Apache Tomcat 11 配置参考 (11.0.8) - Manager 组件

Manager 组件

简介

Manager 元素代表用于创建和维护关联 Web 应用程序请求的 *会话管理器*。

Manager 元素可以嵌套在 Context 组件中。如果未包含此元素，将自动创建一个默认的 Manager 配置，这足以满足大多数要求，— 有关此配置的详细信息，请参阅下面的 *标准 Manager 实现*。

属性

通用属性

所有 Manager 实现都支持以下属性

属性	描述
`className`	要使用的实现的 Java 类名。此类必须实现 `org.apache.catalina.Manager` 接口。如果未指定，将使用标准值（定义如下）。
`maxActiveSessions`	此 Manager 将创建的最大活动会话数，或 `-1`（默认值）表示无限制。当达到限制时，任何创建新会话的尝试（例如通过 `HttpServletRequest.getSession()` 调用）都将因 `IllegalStateException` 而失败。
`notifyAttributeListenerOnUnchangedValue`	如果向会话添加了一个属性，并且该属性已以相同名称存在于会话中，那么是否会通知任何 `HttpSessionAttributeListener` 该属性已被替换。如果未指定，将使用默认值 `true`。
`notifyBindingListenerOnUnchangedValue`	如果向会话添加了一个属性，并且该属性已以相同名称存在于会话中，且该属性实现了 `HttpSessionBindingListener`，那么是否会通知监听器该属性已解绑并再次绑定。如果未指定，将使用默认值 `false`。
`sessionActivityCheck`	如果此值为 `true`，Tomcat 将跟踪每个会话的活动请求数。在判断会话是否有效时，任何至少有一个活动请求的会话都将始终被视为有效。如果 `org.apache.catalina.STRICT_SERVLET_COMPLIANCE` 设置为 `true`，则此设置的默认值为 `true`，否则默认值为 `false`。
`sessionLastAccessAtStart`	如果此值为 `true`，会话的最后访问时间将从上一个请求的开始时计算。如果为 `false`，会话的最后访问时间将从上一个请求的结束时计算。这也会影响空闲时间的计算方式。如果 `org.apache.catalina.STRICT_SERVLET_COMPLIANCE` 设置为 `true`，则此设置的默认值为 `true`，否则默认值为 `false`。

标准实现

Tomcat 提供了两种用于 Manager 的标准实现 — 默认实现存储活动会话，而可选实现将已换出的活动会话（除了在 Tomcat 重启时保存会话外）存储在通过使用适当的嵌套 Store 元素选择的存储位置。

标准 Manager 实现

Manager 的标准实现是 org.apache.catalina.session.StandardManager。它支持以下附加属性（除了上面列出的通用属性）

属性	描述
`pathname`	会话状态在应用程序重启后（如果可能）将保存在其中的文件的绝对路径或相对路径（相对于此 Context 的工作目录）。默认值为 null。有关更多信息，请参阅跨重启持久化。通过将此属性设置为非空字符串可以启用此持久化功能。
`persistAuthentication`	在应用程序重启时保留会话状态时，是否应包含认证信息？如果为 `true`，则会话的认证信息将被保留，以便应用程序重启后会话仍保持认证状态。如果未指定，将使用默认值 `false`。有关更多信息，请参阅跨重启持久化。请注意，会话的 `Principal` 类及其子孙类都受 sessionAttributeValueClassNameFilter 约束。如果指定了此类过滤器，则 `Principal` 类及其子孙类的名称必须与该过滤器模式匹配才能被恢复。
`processExpiresFrequency`	会话过期及相关 Manager 操作的频率。Manager 操作将根据指定的 backgroundProcess 调用次数（即，次数越少，检查越频繁）进行一次。最小值为 1，默认值为 6。
`secureRandomClass`	用于生成会话 ID 的、扩展 `java.security.SecureRandom` 的 Java 类名。如果未指定，默认值为 `java.security.SecureRandom`。
`secureRandomProvider`	用于创建生成会话 ID 的 `java.security.SecureRandom` 实例的提供者名称。如果指定了无效的算法和/或提供者，Manager 将使用平台默认提供者和默认算法。如果未指定，将使用平台默认提供者。
`secureRandomAlgorithm`	用于创建生成会话 ID 的 `java.security.SecureRandom` 实例的算法名称。如果指定了无效的算法和/或提供者，Manager 将使用平台默认提供者和默认算法。如果未指定，将使用默认算法 SHA1PRNG。如果不支持默认算法，将使用平台默认算法。要指定使用平台默认算法，请不要设置 secureRandomProvider 属性，并将此属性设置为空字符串。
`sessionAttributeNameFilter`	一个正则表达式，用于过滤哪些会话属性将序列化用于集群/复制或存储到任何持久化存储中。只有当属性名称与此模式匹配时，才会序列化该属性。如果模式长度为零或 `null`，则所有属性都符合分发条件。该模式是固定的，因此会话属性名称必须完全匹配该模式。例如，值 `(userName\|sessionHistory)` 将仅分发名为 `userName` 和 `sessionHistory` 的两个会话属性。如果未指定，将使用默认值 `null`。
`sessionAttributeValueClassNameFilter`	一个正则表达式，用于过滤哪些会话属性将序列化用于集群/复制或存储到任何持久化存储中。只有当属性值的实现类名与此模式匹配时，才会序列化该属性。如果模式长度为零或 `null`，则所有属性都符合分发条件。该模式是固定的，因此完全限定类名必须完全匹配该模式。如果未指定，将使用默认值 `null`。
`warnOnSessionAttributeFilterFailure`	如果 sessionAttributeNameFilter 或 sessionAttributeValueClassNameFilter 阻止了某个属性，是否应将其以 `WARN` 级别记录？如果 `WARN` 级别日志记录被禁用，则将以 `DEBUG` 级别记录。此属性的默认值为 `false`。

持久化 Manager 实现

注意： 必须将 org.apache.catalina.session.StandardSession.ACTIVITY_CHECK 或 org.apache.catalina.STRICT_SERVLET_COMPLIANCE 系统属性设置为 true，持久化管理器才能正常工作。

Manager 的持久化实现是 org.apache.catalina.session.PersistentManager。除了创建和删除会话的常规操作外，PersistentManager 还能将会话（处于活动但空闲状态）换出到持久化存储机制中，以及在 Tomcat 正常重启时保存所有会话。实际使用的持久化存储机制是通过在 Manager 元素内嵌套一个 Store 元素来选择的——这是使用 PersistentManager 所必需的。

此 Manager 实现支持以下属性，以及前面描述的通用属性。

属性	描述
`className`	其含义与上述通用属性中描述的相同。您必须指定 `org.apache.catalina.session.PersistentManager` 才能使用此管理器实现。
`maxIdleBackup`	会话最后访问以来，在有资格被持久化到会话存储之前的时间间隔（秒），或 `-1` 以禁用此功能。默认情况下，此功能是禁用的。
`maxIdleSwap`	会话因不活动而有资格被交换到磁盘之前的最大空闲时间。将其设置为 `-1` 表示会话不会仅因不活动而被换出。如果启用此功能，则此处指定的时间间隔应等于或长于为 `maxIdleBackup` 指定的值。默认情况下，此功能是禁用的。
`minIdleSwap`	会话必须空闲的最小时间（秒），之后才有资格被交换到磁盘以将会话活跃数保持在 maxActiveSessions 以下。设置为 `-1` 表示会话不会为了减少活跃会话数而被换出。如果指定，此值应小于 `maxIdleSwap` 指定的值。默认情况下，此值设置为 `-1`。
`persistAuthentication`	将会话换出到持久化存储时，是否应包含认证信息？如果为 `true`，则会话的认证信息将被保留，以便从持久化存储重新加载（换入）后会话仍保持认证状态。如果未指定，将使用默认值 `false`。请注意，会话的 `Principal` 类及其子孙类都受 sessionAttributeValueClassNameFilter 约束。如果指定了此类过滤器，则 `Principal` 类及其子孙类的名称必须与该过滤器模式匹配才能被恢复。
`processExpiresFrequency`	它与上述 `org.apache.catalina.session.StandardManager` 类中描述的含义相同。
`saveOnRestart`	当 Tomcat 关闭并重新启动（或此应用程序重新加载时）时，是否应持久化并重新加载所有会话？默认情况下，此属性设置为 `true`。
`secureRandomClass`	它与上述 `org.apache.catalina.session.StandardManager` 类中描述的含义相同。
`secureRandomProvider`	它与上述 `org.apache.catalina.session.StandardManager` 类中描述的含义相同。
`secureRandomAlgorithm`	它与上述 `org.apache.catalina.session.StandardManager` 类中描述的含义相同。
`sessionAttributeNameFilter`	一个正则表达式，用于过滤哪些会话属性将序列化用于集群/复制或存储到任何持久化存储中。只有当属性名称与此模式匹配时，才会序列化该属性。如果模式长度为零或 `null`，则所有属性都符合分发条件。该模式是固定的，因此会话属性名称必须完全匹配该模式。例如，值 `(userName\|sessionHistory)` 将仅分发名为 `userName` 和 `sessionHistory` 的两个会话属性。如果未指定，将使用默认值 `null`。
`sessionAttributeValueClassNameFilter`	一个正则表达式，用于过滤哪些会话属性将序列化用于集群/复制或存储到任何持久化存储中。只有当属性值的实现类名与此模式匹配时，才会序列化该属性。如果模式长度为零或 `null`，则所有属性都符合分发条件。该模式是固定的，因此完全限定类名必须完全匹配该模式。如果未指定，将使用默认值 `null`。
`warnOnSessionAttributeFilterFailure`	如果 sessionAttributeNameFilter 或 sessionAttributeValueClassNameFilter 阻止了某个属性，是否应将其以 `WARN` 级别记录？如果 `WARN` 级别日志记录被禁用，则将以 `DEBUG` 级别记录。此属性的默认值为 `false`。

为了成功使用 PersistentManager，您必须在其内部嵌套一个 <Store> 元素，如下所述。

嵌套组件

所有 Manager 实现

所有 Manager 实现都允许嵌套一个 <SessionIdGenerator> 元素。它定义了会话 ID 生成的行为。所有 SessionIdGenerator 实现都允许以下属性

属性	描述
`sessionIdLength`	会话 ID 的长度可以通过 sessionIdLength 属性进行更改。

持久化 Manager 实现

如果您正在使用上述 *持久化 Manager 实现*，您必须在其内部嵌套一个 <Store> 元素，该元素定义了持久化数据存储的特性。目前有两种 <Store> 元素实现可用，它们具有不同的特性，如下所述。

基于文件的存储 (File Based Store)

*基于文件的存储*实现将换出的会话保存在可配置目录中的独立文件（根据会话标识符命名）中。因此，随着活动会话数量的增加，您可能会遇到可伸缩性问题，这主要应被视为一种简单的实验手段。

要配置此项，请在您的 <Manager> 元素中嵌套一个 <Store> 元素，并包含以下属性

属性	描述
`className`	要使用的实现的 Java 类名。此类必须实现 `org.apache.catalina.Store` 接口。您必须指定 `org.apache.catalina.session.FileStore` 才能使用此实现。
`directory`	写入单个会话文件的目录的绝对路径或相对路径（相对于此 Web 应用程序的临时工作目录）。如果未指定，则使用容器分配的临时工作目录。

基于数据源的存储 (Data source Based Store)

*基于数据源的存储*实现将换出的会话保存在通过数据源访问的数据库中预配置表的单个行中。对于大量换出的会话，此实现将比上述基于文件的存储表现出更好的性能。

要配置此项，请在您的 <Manager> 元素中嵌套一个 <Store> 元素，并包含以下属性

属性	描述
`className`	要使用的实现的 Java 类名。此类必须实现 `org.apache.catalina.Store` 接口。您必须指定 `org.apache.catalina.session.DataSourceStore` 才能使用此实现。
`dataSourceName`	JDBC DataSource 工厂的 JNDI 资源名称。由于此代码使用预编译语句，您可能需要配置池化预编译语句，如JNDI 资源操作指南中所示。
`localDataSource`	这允许存储使用为 Context 定义的 DataSource，而不是全局 DataSource。如果未指定，默认值为 `false`：使用全局 DataSource。
`sessionAppCol`	指定会话表中包含数据库列的名称，该列包含格式为 `/Engine/Host/Context` 的 Engine、Host 和 Web 应用程序 Context 名称。如果未指定，将使用默认值 `app`。
`sessionDataCol`	指定会话表中包含数据库列的名称，该列包含已换出会话所有会话属性的序列化形式。列类型必须接受二进制对象（通常称为 BLOB）。如果未指定，将使用默认值 `data`。
`sessionIdCol`	指定会话表中包含数据库列的名称，该列包含已换出会话的会话标识符。列类型必须接受至少包含 Tomcat 创建的会话标识符（通常为 32 个字符）数量的字符数据。如果未指定，将使用默认值 `id`。
`sessionLastAccessedCol`	指定会话表中包含数据库列的名称，该列包含此会话的 `lastAccessedTime` 属性。列类型必须接受 Java `long`（64 位）。如果未指定，将使用默认值 `maxinactive`。
`sessionMaxInactiveCol`	指定会话表中包含数据库列的名称，该列包含此会话的 `maxInactiveInterval` 属性。列类型必须接受 Java `integer`（32 位）。如果未指定，将使用默认值 `maxinactive`。
`sessionTable`	用于存储已换出会话的数据库表的名称。此表必须至少包含由此元素其他属性配置的数据库列。如果未指定，将使用默认值 `tomcat$sessions`。
`sessionValidCol`	指定会话表中包含数据库列的名称，该列包含一个标志，指示此已换出会话是否仍然有效。列类型必须接受单个字符。如果未指定，将使用默认值 `valid`。

在首次尝试使用数据源存储之前，您必须创建用于存储已换出会话的表。详细的 SQL 命令因您使用的数据库而异，但通常需要类似这样的脚本

create table tomcat_sessions (
  session_id     varchar(100) not null primary key,
  valid_session  char(1) not null,
  max_inactive   int not null,
  last_access    bigint not null,
  app_name       varchar(255),
  session_data   mediumblob,
  KEY kapp_name(app_name)
);

注意：上述 SQL 命令没有使用表或列的默认名称，因此需要配置数据源存储以反映这一点。

特殊功能

跨重启持久化

每当 Apache Tomcat 正常关闭并重新启动，或触发应用程序重新加载时，标准 Manager 实现将尝试将所有当前活动会话序列化到通过 pathname 属性定位的磁盘文件中。所有这些保存的会话随后将在应用程序重新加载完成时被反序列化并激活（假设它们在此期间没有过期）。

为了成功恢复会话属性的状态，所有此类属性**必须**实现 java.io.Serializable 接口。您可以通过在 Web 应用程序部署描述符 (`/WEB-INF/web.xml`) 中包含 <distributable> 元素来强制 Manager 执行此限制。

请注意，如果 persistAuthentication 也设置为 true，会话中存在的 Principal 类也**必须**实现 java.io.Serializable 接口，以便认证持久化正常工作。该 Principal 类的实际类型由与应用程序一起使用的 Realm 实现决定。Tomcat 的标准 Principal 类（除了 JAASRealm 外，大多数 Realm 实例化）实现了 java.io.Serializable。

由 StandardManager 提供的跨重启持久化是比 PersistentManager 提供的更简单的实现。如果需要健壮的、生产质量的跨重启持久化，则应使用适当配置的 PersistentManager。

启用会话持久化

如上所述，每个 Web 应用程序默认都配置了标准 Manager 实现，该实现可以执行跨重启的会话持久化。要启用此持久化功能，请为您的 Web 应用程序创建一个 Context 配置文件，并在其中添加以下元素（在此示例中，它会将会话保存到名为 SESSIONS.ser 的文件中）

<Manager pathname="SESSIONS.ser" />