Apache Tomcat 10 組態參考 (10.1.23) - Manager 元件

Manager 元件

簡介

Manager 元素表示將用於建立和維護 HTTP 會話（依據關聯的 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 的約束。如果指定了此類篩選器或啟用 `SecurityManager`，`Principal` 類別和後代類別的名稱必須符合該篩選器模式才能復原。
`processExpiresFrequency`	會話過期頻率和相關管理員操作。管理員操作會針對指定的 backgroundProcess 呼叫次數執行一次（亦即，次數越少，檢查會越頻繁）。最小值為 1，預設值為 6。
`secureRandomClass`	延伸 `java.security.SecureRandom` 以用於產生會話 ID 的 Java 類別名稱。如果未指定，預設值為 `java.security.SecureRandom`。
`secureRandomProvider`	用於建立用於產生會話 ID 的 `java.security.SecureRandom` 實例的提供者名稱。如果指定了無效的演算法和/或提供者，管理員將使用平台預設提供者和預設演算法。如果未指定，將使用平台預設提供者。
`secureRandomAlgorithm`	用於建立用於產生會話 ID 的 `java.security.SecureRandom` 實例的演算法名稱。如果指定了無效的演算法和/或提供者，管理員將使用平台預設提供者和預設演算法。如果未指定，將使用 SHA1PRNG 的預設演算法。如果預設演算法不受支援，將使用平台預設值。若要指定應使用平台預設值，請勿設定 secureRandomProvider 屬性，並將此屬性設定為空字串。
`sessionAttributeNameFilter`	用於篩選會在叢集/複製或儲存到任何持久性儲存體中序列化的會話屬性的正規表示式。只有名稱符合此模式的屬性才會序列化。如果模式長度為零或為 `null`，所有屬性都符合分發資格。模式已錨定，因此會話屬性名稱必須完全符合模式。例如，值 `(userName\|sessionHistory)` 將只會分發名稱為 `userName` 和 `sessionHistory` 的兩個會話屬性。如果未指定，將使用預設值 `null`。
`sessionAttributeValueClassNameFilter`	用於過濾將序列化哪些會話屬性以進行叢集/複製或儲存到任何持續性儲存體的正規表示式。只有當值的實作類別名稱符合此模式時，屬性才會被序列化。如果模式長度為零或為 `null`，則所有屬性都符合分發資格。模式已錨定，因此完全限定的類別名稱必須與模式完全相符。如果未指定，則會使用預設值 `null`，除非啟用 `SecurityManager`，否則預設值將為 `java\\.lang\\.(?:Boolean\|Integer\|Long\|Number\|String)\|org\\.apache\\.catalina\\.realm\\.GenericPrincipal\\$SerializablePrincipal\|\\[Ljava.lang.String;`。
`warnOnSessionAttributeFilterFailure`	如果 sessionAttributeNameFilter 或 sessionAttributeValueClassNameFilter 阻擋屬性，是否應以 `WARN` 層級記錄此情況？如果已停用 `WARN` 層級記錄，則會以 `DEBUG` 記錄。此屬性的預設值為 `false`，除非已啟用 `SecurityManager`，否則預設值將為 `true`。

持續性管理員實作

注意：您必須將 org.apache.catalina.session.StandardSession.ACTIVITY_CHECK 或 org.apache.catalina.STRICT_SERVLET_COMPLIANCE 系統屬性設為 true，才能讓持續性管理員正常運作。

Manager 的持續性實作是 org.apache.catalina.session.PersistentManager。除了建立和刪除會話的通常作業外，PersistentManager 還能夠將處於活動狀態（但閒置）的會話交換到持續性儲存機制，以及在 Tomcat 正常重新啟動時儲存所有會話。實際使用的持續性儲存機制是由您選擇的 Store 元素（嵌套在 Manager 元素內）來選取的 - 這是使用 PersistentManager 的必要條件。

除了前面所述的共用屬性外，此 Manager 實作還支援下列屬性。

屬性	說明
`className`	managerClassName
`它具有與上面共用屬性中所述相同的意義。您必須指定 org.apache.catalina.session.PersistentManager 才能使用此管理員實作。`	maxIdleBackup
`maxIdleSwap`	在因閒置而符合換出至磁碟資格之前，一個工作階段可以閒置的最長時間。將此設定為 `-1` 表示工作階段不應僅因閒置而被換出。如果啟用此功能，在此指定的時間間隔應等於或長於為 `maxIdleBackup` 指定的值。預設情況下，此功能已停用。
`minIdleSwap`	在符合換出至磁碟資格以將活動工作階段數量維持在 maxActiveSessions 以下之前，一個工作階段必須閒置的最小時間（以秒為單位）。設定為 `-1` 表示不會換出工作階段以降低活動工作階段數量。如果指定，此值應小於 `maxIdleSwap` 指定的值。預設情況下，此值設定為 `-1`。
`persistAuthentication`	在將工作階段換出至永久儲存時，是否應包含驗證資訊？如果為 `true`，則會保留工作階段的驗證，以便在從永久儲存重新載入（換入）後，工作階段仍保持驗證狀態。如果未指定，將使用預設值 `false`。請注意，會話的 `Principal` 類別及其後代類別都受 sessionAttributeValueClassNameFilter 的約束。如果指定了此類篩選器或啟用 `SecurityManager`，`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`，除非啟用 `SecurityManager`，否則預設值將為 `java\\.lang\\.(?:Boolean\|Integer\|Long\|Number\|String)\|org\\.apache\\.catalina\\.realm\\.GenericPrincipal\\$SerializablePrincipal\|\\[Ljava.lang.String;`。
`warnOnSessionAttributeFilterFailure`	如果 sessionAttributeNameFilter 或 sessionAttributeValueClassNameFilter 阻擋屬性，是否應以 `WARN` 層級記錄此情況？如果已停用 `WARN` 層級記錄，則會以 `DEBUG` 記錄。此屬性的預設值為 `false`，除非已啟用 `SecurityManager`，否則預設值將為 `true`。

若要成功使用 PersistentManager，您必須在其中巢狀一個 <Store> 元素，如下所述。

巢狀元件

所有管理員實作

所有管理員實作都允許巢狀一個 <SessionIdGenerator> 元素。它定義工作階段 ID 產生的行為。所有 SessionIdGenerator 實作都允許下列屬性

屬性	說明
`sessionIdLength`	可以使用 sessionIdLength 屬性變更工作階段 ID 的長度。

持續性管理員實作

如果您使用如上所述的 Persistent Manager 實作，您必須在其中巢狀一個 <Store> 元素，它定義永久資料儲存的特徵。目前有兩種 <Store> 元素實作，具有不同的特徵，如下所述。

基於檔案的儲存

基於檔案的儲存 實作會將換出的工作階段儲存在可設定目錄中的個別檔案（名稱根據工作階段識別碼命名）。因此，隨著活動工作階段數量的增加，您可能會遇到可擴充性問題，這應主要被視為一種輕鬆實驗的方法。

若要設定這項功能，請在您的 <Manager> 元素中新增一個巢狀 <Store>，並使用下列屬性

屬性	說明
`className`	要使用的實作的 Java 類別名稱。此類別必須實作 `org.apache.catalina.Store` 介面。您必須指定 `org.apache.catalina.session.FileStore` 才能使用此實作。
`directory`	絕對或相對（對於此 Web 應用程式的暫時工作目錄）目錄的路徑名稱，其中會寫入個別的階段檔案。如果未指定，則會使用容器指定的暫時工作目錄。

基於資料來源的儲存

基於資料來源的儲存實作會將交換出的階段儲存在資料庫中預先設定的表格中個別的列中，並透過資料來源存取該資料庫。對於大量的交換出階段，此實作的效能會比上述的基於檔案的儲存來得更好。

若要設定這項功能，請在您的 <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 和 Web 應用程式 Context 名稱，格式為 `/Engine/Host/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-INF/web.xml）中包含 <distributable> 元素，讓 Manager 強制執行此限制。

請注意，如果 persistAuthentication 也設定為 true，則會話中存在的 Principal 類別也必須實作 java.io.Serializable 介面，才能讓驗證持續性正常運作。該 Principal 類別的實際類型由應用程式所使用的 Realm 實作決定。由大多數 Realm (JAASRealm 除外) 所實例化的 Tomcat 標準 Principal 類別實作 java.io.Serializable。

StandardManager 所提供的跨重新啟動持續性，比 PersistentManager 所提供的實作更簡單。如果需要穩健且具備生產品質的跨重新啟動持續性，則應將 PersistentManager 與適當的組態搭配使用。

啟用 Session 持續性

如上所述，預設情況下每個 Web 應用程式都已組態標準管理員實作，它可以在重新啟動時執行會話持續性。若要啟用此持續性功能，請為您的 Web 應用程式建立 Context 組態檔案，並在其中加入下列元素 (在此範例中，它會將會話儲存到名為 SESSIONS.ser 的檔案)

<Manager pathname="SESSIONS.ser" />