主機容器

目錄

簡介

Host 元素表示一個虛擬主機，它是一個伺服器網路名稱（例如「www.mycompany.com」）與 Tomcat 執行的特定伺服器之間的關聯。為了讓客戶端能夠使用其網路名稱連線到 Tomcat 伺服器，此名稱必須註冊在管理您所屬網際網路網域的網域名稱服務 (DNS) 伺服器中 - 如需更多資訊，請聯絡您的網路管理員。

在許多情況下，系統管理員希望將多個網路名稱（例如 www.mycompany.com 和 company.com）與同一個虛擬主機和應用程式關聯。這可以使用下面討論的主機名稱別名功能來完成。

一個或多個 Host 元素會巢狀在 Engine 元素中。在 Host 元素中，您可以巢狀 Context 元素，以取得與此虛擬主機關聯的 Web 應用程式。與每個引擎關聯的主機中，必須有一個主機名稱與該引擎的 defaultHost 屬性相符。

客戶端通常使用主機名稱來識別他們想要連線的伺服器。此主機名稱也包含在 HTTP 要求標頭中。Tomcat 從 HTTP 標頭中擷取主機名稱，並尋找具有相符名稱的 Host。如果找不到相符項，要求會路由到預設主機。預設主機的名稱不必與 DNS 名稱相符（儘管可以），因為任何 DNS 名稱與 Host 元素名稱不符的要求都會路由到預設主機。

以下說明使用變數名稱 $CATALINA_BASE 來指稱大多數相對路徑所解析的基礎目錄。如果您尚未透過設定 CATALINA_BASE 目錄來為多個執行個體組態 Tomcat，則 $CATALINA_BASE 會設定為 $CATALINA_HOME 的值，也就是您安裝 Tomcat 的目錄。

屬性

共用屬性

所有 Host 實作都支援下列屬性

屬性 說明
appBase

此虛擬主機的應用程式基礎目錄。這是可能包含要部署在此虛擬主機上的 Web 應用程式的目錄路徑名稱。您可以指定絕對路徑名稱，或相對於 $CATALINA_BASE 目錄的路徑名稱。請參閱 自動應用程式部署，以取得有關自動辨識和部署 Web 應用程式的詳細資訊。如果未指定，將使用預設值 webapps。

xmlBase

此虛擬主機的XML 基礎目錄。這是可能包含要部署在此虛擬主機上的內容 XML 描述檔的目錄路徑名稱。您可以為此目錄指定絕對路徑名稱，或相對於 $CATALINA_BASE 目錄的路徑名稱。請參閱 自動應用程式部署，以取得有關自動辨識和部署 Web 應用程式的詳細資訊。如果未指定，將使用預設值 conf/<engine_name>/<host_name>。

createDirs

如果設定為 true，Tomcat 會嘗試在啟動階段建立由屬性 appBase 和 xmlBase 定義的目錄。預設值為 true。如果設定為 true，且目錄建立失敗，系統會印出錯誤訊息，但不會停止啟動順序。

autoDeploy

此旗標值表示 Tomcat 是否應在 Tomcat 執行期間定期檢查是否有新的或已更新的 Web 應用程式。如果為 true，Tomcat 會定期檢查 appBase 和 xmlBase 目錄，並部署任何找到的新 Web 應用程式或內容 XML 描述檔。已更新的 Web 應用程式或內容 XML 描述檔會觸發 Web 應用程式的重新載入。預設值為 true。請參閱 自動應用程式部署，以取得詳細資訊。

backgroundProcessorDelay

此值表示在此主機及其子容器（包括所有內容）上呼叫 backgroundProcess 方法之間的延遲（以秒為單位）。如果子容器的延遲值不為負值（表示它們使用自己的處理執行緒），則不會呼叫子容器。將此值設定為正值會導致產生執行緒。在等待指定的時間後，執行緒會在此主機及其所有子容器上呼叫 backgroundProcess 方法。主機會使用背景處理來執行與即時 Web 應用程式部署相關的任務。如果未指定，此屬性的預設值為 -1，表示主機會依賴其父引擎的背景處理設定。

className

要使用的實作的 Java 類別名稱。此類別必須實作 org.apache.catalina.Host 介面。如果未指定，將使用標準值（定義如下）。

deployIgnore

定義在設定 autoDeploy 和 deployOnStartup 時要忽略路徑的正規表示法。這允許您將組態保存在版本控制系統中，例如，不部署剛好位於 appBase 中的 .svn、.git 或其他組態控制系統資料夾。

此正規表示法相對於 appBase。它也已「錨定」，表示比對會針對整個檔案/目錄名稱執行。因此，foo 僅比對名為 foo 的檔案或目錄，但不比對 foo.war、foobar 或 myfooapp。若要比對任何含有「foo」的項目，您可以使用 .*foo.*。

請參閱 自動應用程式部署 以取得更多資訊。

deployOnStartup

此旗標值表示當 Tomcat 啟動時，是否應自動部署此主機的 Web 應用程式。預設為 true。請參閱 自動應用程式部署 以取得更多資訊。

failCtxIfServletStartFails

設為 true，若任何載入時啟動 >=0 的 servlet 啟動失敗，則讓每個子內容啟動失敗。

每個子內容都可能覆寫此屬性。

如果未指定，將使用預設值 false。

legacyAppBase

此虛擬主機的舊版應用程式基礎目錄。這是可能包含要轉換為 Jakarta EE 的 Java EE Web 應用程式的目錄路徑，然後再部署。封裝為 WAR 檔案或放置在此目錄中的 Java EE 應用程式將使用 Apache Tomcart Jakarta EE 遷移工具轉換為 Jakarta EE。轉換將使用預設設定執行。產生的 WAR 或目錄將放置在此虛擬主機設定的 appBase 中。

如果預設設定不適用於應用程式的遷移，則可以手動執行遷移來存取完整的遷移選項。migrate.[sh|bat] 指令碼提供在 $CATALINA_HOME/bin 目錄中以供此目的使用。

您可以指定絕對路徑，或相對於 $CATALINA_BASE 目錄的路徑。如果未指定，將使用預設值 webapps-javaee。

名稱

通常是此虛擬主機的網路名稱，已註冊在您的 網域名稱服務 伺服器中。不論用什麼大小寫指定主機名稱，Tomcat 都會在內部將其轉換成小寫。嵌套在 引擎 中的主機之一，其名稱必須與該引擎的 defaultHost 設定相符。請參閱 主機名稱別名，了解如何將多個網路名稱指派給同一個虛擬主機。名稱不能包含萬用字元，這只在別名中才有效。

startStopThreads

此 主機 將使用此執行緒數目，以平行方式啟動子 內容 元素。如果使用自動部署，將使用同一個執行緒池來部署新的 內容。由於執行緒池在伺服器層級共用，如果有多個主機指定此設定，只有最大值會套用，並用於所有主機，特別值 1 除外。如果未指定，將使用預設值 1。如果使用 1 個執行緒，則會使用目前的執行緒，而不是使用 ExecutorService。

undeployOldVersions

此旗標會決定 Tomcat 是否會在自動部署程序中，檢查使用平行部署已部署的網頁應用程式的舊版本，且如果找到任何舊版本，就會將其移除。此旗標只適用於 autoDeploy 為 true 的情況。如果未指定，將使用預設值 false。

標準實作

主機 的標準實作是 org.apache.catalina.core.StandardHost。它支援下列其他屬性（除了上面列出的共用屬性之外）

屬性 說明
copyXML

如果想要將嵌入在應用程式中的內容 XML 描述子（位於 /META-INF/context.xml）在應用程式部署時複製到 xmlBase，請設定為 true。在後續啟動時，會優先使用已複製的內容 XML 描述子，而不是嵌入在應用程式中的任何內容 XML 描述子，即使嵌入在應用程式中的描述子較新。預設值為 false。請注意，如果 deployXML 為 false，此屬性將不會產生任何作用。

deployXML

如果想要停用剖析嵌入在應用程式中的內容 XML 描述子（位於 /META-INF/context.xml），請設定為 false。重視安全的環境應將此設定為 false，以防止應用程式與容器的設定互動。然後，管理員將負責提供外部內容設定檔，並將其放在 xmlBase 屬性所定義的位置。如果此旗標為 false，且描述子位於 /META-INF/context.xml，且 xmlBase 中沒有描述子，則如果描述子包含必要的設定（例如 RemoteAddrValve），以進行安全的部署，且不應忽略，則內容將無法啟動。預設值為 true，除非啟用安全性管理員，否則預設值為 false。在安全性管理員底下執行時，這可能會在每個網頁應用程式的基礎上啟用，方法是授予網頁應用程式 org.apache.catalina.security.DeployXmlPermission。管理員和主機管理員應用程式預設會獲得此權限，以便在安全性管理員底下執行時，它們可以繼續運作。

errorReportValveClass

此主機使用的錯誤報告閥門的 Java 類別名稱。此閥門的責任是輸出錯誤報告。設定此屬性可自訂 Tomcat 將產生的錯誤頁面外觀。此類別必須實作 `org.apache.catalina.Valve` 介面。如果未指定，預設會使用 `org.apache.catalina.valves.ErrorReportValve` 值。如果設定為空字串，錯誤報告會停用。

unpackWARs

如果要將放置在 `appBase` 目錄中的 Web 應用程式作為 Web 應用程式封存 (WAR) 檔案解壓縮到對應的磁碟目錄結構，請設定為 `true`；如果要直接從 WAR 檔案執行此類 Web 應用程式，請設定為 `false`。預設為 `true`。有關更多資訊，請參閱自動應用程式部署。

注意：如果 Tomcat 擴充 WAR 檔案，它會將檔案 (/META-INF/war-tracking) 新增到解壓縮的目錄結構，它會在 Tomcat 未執行時用來偵測 WAR 檔案的變更。任何此類變更會觸發刪除已擴充目錄，並在 Tomcat 下次啟動時部署已更新的 WAR 檔案。

注意：以設定為 `false` 的選項執行會產生效能損失。為避免顯著的效能損失，應設定 Web 應用程式，使其不需要掃描 Servlet 3.0+ 可插入性功能的類別。使用者可能也希望考慮ExtractingRoot 資源實作。

workDir

此主機的應用程式要使用的暫存目錄路徑名稱。每個應用程式都會有自己的子目錄，可暫時讀寫使用。設定 Context workDir 會覆寫使用主機 workDir 設定。此目錄會透過 servlet context 屬性 (型別為 `java.io.File`)，名稱為 `jakarta.servlet.context.tempdir`，讓 Web 應用程式中的 servlet 可見，如 Servlet 規格中所述。如果未指定，會提供 `$CATALINA_BASE/work` 下方的適當目錄。

巢狀元件

您可以在此 Host 元素內嵌一個或多個 Context 元素，每個元素代表與此虛擬主機關聯的不同 Web 應用程式。

您可以在 Host 元素內嵌對應元素，最多嵌一個下列公用程式元件的執行個體

  • Realm - 設定一個領域，讓其使用者資料庫及其關聯的角色可以在此主機內嵌的所有 Contexts 中共用 (除非被較低層級的 Realm 設定覆寫)。

特殊功能

記錄

主機與 org.apache.catalina.core.ContainerBase.[engine_name].[host_name] 日誌類別相關聯。請注意，括號是名稱的一部分，不要省略它們。

存取記錄

當您執行 Web 伺服器時，通常會產生的一個輸出檔案是存取日誌，它會針對伺服器處理的每個要求產生一行資訊，採用標準格式。Catalina 包含一個可選的 Valve 實作，它可以在 Web 伺服器建立的相同標準格式中建立存取日誌，或採用任何數量的自訂格式。

您可以要求 Catalina 為 Engine、Host 或 Context 處理的所有要求建立存取日誌，方法是巢狀 Valve 元素，如下所示

<Host name="localhost" ...>
  ...
  <Valve className="org.apache.catalina.valves.AccessLogValve"
         prefix="localhost_access_log" suffix=".txt"
         pattern="common"/>
  ...
</Host>

請參閱 存取記錄閥 以取得支援的組態屬性的更多資訊。

自動應用程式部署

如果您使用具有預設設定的標準主機實作，則在 Tomcat 啟動時，appBase 中的應用程式或在 configBase 中具有內容檔案的應用程式會自動部署（deployOnStartup 屬性預設為 true），並在 Tomcat 執行期間偵測到變更時重新載入或重新部署（視情況而定）（autoDeploy 屬性也預設為 true）。

deployOnStartup 和 autoDeploy 會觸發執行完全相同的程式碼，因此行為非常類似。但是，有一個關鍵的差異。當 Tomcat 啟動時，它不知道哪些檔案相同、哪些已變更以及哪些是新的。因此，它將所有檔案都視為新的。當 Tomcat 正在執行時，它可以區分未變更、已修改和新的檔案。這會導致 Tomcat 執行期間修改的檔案與 Tomcat 停止期間修改的檔案之間的行為有些不同。

當您使用自動部署時，存在於主機的 appBase 和/或 configBase 中的相關檔案（Web 應用程式可能有 context.xml 檔案、WAR 和目錄）必須符合預期的 命名慣例。簡而言之，這表示相同 Web 應用程式的檔案必須共用相同的基本名稱。

自動部署程序會使用下列搜尋順序，找出新的或已修改的 Web 應用程式

  1. Web 應用程式在 Host 的 configBase 中有一個 context.xml 檔案。
  2. Web 應用程式在 Host 的 appBase 中有一個 WAR 檔案，而且在掃描 context.xml 檔案期間尚未找出。
  3. Web 應用程式在 Host 的 appBase 中有一個目錄，而且在掃描 context.xml 和/或 WAR 檔案期間尚未找出。

當 autoDeploy 為 true 時，自動部署程序會監控已部署的 Web 應用程式是否有變更。視變更的內容而定，Web 應用程式會重新部署或重新載入。重新部署會建立新的 Web 應用程式，而且如果使用標準的會話管理員，使用者會話不會保留。重新載入會使用現有的 Web 應用程式，但會重新剖析 web.xml 並重新載入所有類別。如果使用標準的會話管理員，使用者會話會持續存在。

使用者可以新增自動部署程序監控的檔案，以進行重新載入（亦即，變更其中一個檔案會觸發 Web 應用程式的重新載入），方法是將 WatchedResources 元素新增至 context.xml 檔案。請參閱 Context 文件，以取得更多詳細資料。

使用自動部署時，XML Context 檔案所定義的 docBase 應該在 appBase 目錄之外。如果不是這樣，可能會遇到部署 Web 應用程式的困難，或者應用程式可能會部署兩次。可以使用 deployIgnore 屬性來避免這種情況。

請注意，如果您在 server.xml 中明確定義 context，您應該關閉自動應用程式部署，或仔細指定 deployIgnore。否則，每個 Web 應用程式都會部署兩次，這可能會導致應用程式出現問題。

設定、新檔案、已變更檔案和已刪除檔案有很多可能的組合。一個單獨的頁面會說明 自動部署程序預期的行為，以應付這些情境中的許多情況。

主機名稱別名

在許多伺服器環境中，網路管理員會設定多個網路名稱（在 網域名稱服務 (DNS) 伺服器中），這些名稱會解析為同一台伺服器的 IP 位址。通常，每個此類網路名稱會在 conf/server.xml 中設定為一個單獨的 Host 元素，每個元素都有其自己的 Web 應用程式組。

不過，在某些情況下，兩個或多個網路名稱應該解析為 相同 的虛擬主機，並執行相同的應用程式組。此情境的常見使用案例是公司網站，使用者應該能夠使用 www.mycompany.com 或 company.com 來存取完全相同的內容和應用程式。

這是透過在 Host 元素內使用一個或多個 Alias 元素來完成的。例如

<Host name="www.mycompany.com" ...>
  ...
  <Alias>mycompany.com</Alias>
  ...
</Host>

為了讓此策略有效，所有相關的網路名稱都必須在您的 DNS 伺服器中註冊，才能解析為執行 Catalina 此執行個體的同一台電腦。

別名也可以使用萬用字元形式（*.domainname），這與 Host 的 name 屬性不同。

生命週期監聽器

如果您已實作需要知道此 Host 何時啟動或停止的 Java 物件，您可以透過在此元素內巢狀 Listener 元素來宣告它。您指定的類別名稱必須實作 org.apache.catalina.LifecycleListener 介面，且會在發生對應的生命週期事件時收到通知。此類別監聽器的組態如下

<Host name="localhost" ...>
  ...
  <Listener className="com.mycompany.mypackage.MyListener" ... >
  ...
</Host>

請注意，監聽器可以有任意數量的其他屬性，這些屬性可以從此元素中組態。屬性名稱會使用標準屬性方法命名模式與對應的 JavaBean 屬性名稱相符。

要求過濾器

您可以要求 Catalina 檢查傳送至周圍 引擎、主機 或 內容 元素的每個傳入要求的 IP 位址或主機名稱。會根據組態的「接受」和/或「拒絕」篩選器檢查遠端位址或名稱，這些篩選器使用 java.util.regex 正規表示法語法定義。來自未接受位置的要求會遭拒絕，並顯示 HTTP「禁止」錯誤。範例篩選器宣告

<Host name="localhost" ...>
  ...
  <Valve className="org.apache.catalina.valves.RemoteHostValve"
         allow=".*\.mycompany\.com|www\.yourcompany\.com"/>
  <Valve className="org.apache.catalina.valves.RemoteAddrValve"
         deny="192\.168\.1\.\d+"/>
  ...
</Host>

請參閱 遠端位址篩選器 和 遠端主機篩選器，以取得關於支援的組態選項的更多資訊。

單一登入

在許多環境中，特別是在入口網站環境中，最好讓使用者只在部署在特定虛擬主機的一組 Web 應用程式上進行一次身分驗證挑戰。這可以透過在這個虛擬主機的 Host 元素內巢狀類似的元素來達成

<Host name="localhost" ...>
  ...
  <Valve className="org.apache.catalina.authenticator.SingleSignOn"/>
  ...
</Host>

單一登入功能根據下列規則運作

  • 為此虛擬主機組態的所有 Web 應用程式都必須共用相同的 領域。實際上，這表示您可以將 Realm 元素巢狀在此 Host 元素（或周圍的 引擎 元素）內，但不可巢狀在其中一個相關 Web 應用程式的 內容 元素內。
  • 只要使用者只存取此虛擬主機上任何 Web 應用程式中的未受保護資源，他們就不會受到身分驗證挑戰。
  • 只要使用者存取與此虛擬主機相關的任何網路應用程式中的受保護資源，就會要求使用者使用目前存取的網路應用程式所定義的登入方式，對自己進行驗證。
  • 經過驗證後，與此使用者相關的角色將會用於所有相關網路應用程式的存取控制決策，而不會要求使用者個別對每個應用程式進行驗證。
  • 只要使用者從一個網路應用程式登出（例如，如果使用基於表單的登入，則會使對應的階段無效），使用者在所有網路應用程式中的階段都會失效。任何後續嘗試存取任何應用程式中的受保護資源，都會要求使用者再次對自己進行驗證。
  • 單一登入功能使用 HTTP cookie 傳輸一個令牌，將每個要求與已儲存的使用者身分相關聯，因此只能在支援 cookie 的用戶端環境中使用。

使用者 Web 應用程式

許多網路伺服器可以自動將從波浪符號（「~」）和使用者名稱開始的要求 URI 對應到伺服器上該使用者家目錄中的目錄（通常稱為 public_html）。您可以在 Catalina 中使用像這樣的特殊Listener 元素來完成相同的事情（在使用 /etc/passwd 檔案來識別有效使用者的 Unix 系統上）

<Host name="localhost" ...>
  ...
  <Listener className="org.apache.catalina.startup.UserConfig"
            directoryName="public_html"
            userClass="org.apache.catalina.startup.PasswdUserDatabase"/>
  ...
</Host>

在未使用 /etc/passwd 的伺服器上，您可以要求 Catalina 考慮在指定基本目錄（例如此範例中的 c:\Homes）中找到的所有目錄，為此指令的目的而被視為「使用者家目錄」

<Host name="localhost" ...>
  ...
  <Listener className="org.apache.catalina.startup.UserConfig"
            directoryName="public_html"
            homeBase="c:\Homes"
            userClass="org.apache.catalina.startup.HomesUserDatabase"/>
  ...
</Host>

如果已為名為 craigmcc 的使用者設定使用者家目錄，則可以透過對類似以下 URL 的要求，從用戶端瀏覽器中看到其內容

http://www.mycompany.com:8080/~craigmcc

成功使用此功能需要考量下列事項

  • 每個使用者網路應用程式都將使用由全域和主機層級預設內容設定所建立的特徵來部署。
  • 包含這個 Listener 元素的執行個體多於一個是合法的。不過，這只會在您想要設定多個「homeBase」目錄的情況下才有用。
  • 執行 Catalina 的作業系統使用者名稱必須有權限讀取每個使用者的網路應用程式目錄及其所有內容。

自訂 context.xml 和 web.xml

您可以針對每個虛擬主機，覆寫從 $CATALINA_BASE 中的 conf/context.xml 和 conf/web.xml 檔案找到的預設值。Tomcat 會在 xmlBase 指定的目錄中尋找名為 context.xml.default 和 web.xml.default 的檔案，並將這些檔案合併到預設檔案中找到的檔案。