Apache Tomcat Connectors - 網路伺服器操作指南

${tomcat_home} 是 tomcat 的根目錄。您的 Tomcat 安裝應具有下列子目錄

• ${tomcat_home}\conf - 您可以放置各種設定檔
• ${tomcat_home}\webapps - 包含範例應用程式
• ${tomcat_home}\bin - 您可以放置網路伺服器外掛程式

在本文件的所有範例中，${tomcat_home} 將會是 c:\tomcat。工作執行緒定義為接受 IIS 伺服器工作的 tomcat 程序。

IIS 至 Tomcat 轉址器支援

• 執行於任何目前支援的 Windows 版本上的 IIS
• 所有目前支援的 Tomcat 版本

轉址器可能適用於執行於較舊、不受支援的 Windows 版本和/或 Tomcat 上的 IIS，但此類設定不受支援。

重新導向器使用 AJP 協定將要求傳送至 Tomcat 容器。所使用的 AJP 版本為 ajp13。所有目前版本的 Tomcat 都支援 ajp13 協定。其他 servlet 引擎，例如 Jetty 和 JBoss 也支援 ajp13 協定。

ajp12 協定已 棄用，您不應再使用它。ajp14 協定被視為實驗性質。

1. ISAPI 重新導向器是 Microsoft IIS 外掛程式（篩選器 + 擴充功能）。IIS 會載入重新導向器外掛程式，並針對每個收到的要求呼叫其篩選器功能。
2. 然後，篩選器會根據 uriworkermap.properties 內的 URI 路徑清單，測試要求 URL。如果目前的請求與 URI 路徑清單中的某個項目相符，篩選器會將請求傳輸至擴充功能。
3. 擴充功能會收集請求參數，並使用已定義的協定（例如 ajp13）將其轉送至適當的執行緒。
4. 擴充功能會收集來自執行緒的回應，並將其傳回至瀏覽器。

這些說明是根據 Windows Server 2012 R2 撰寫，並已在所有支援的 Windows 作業系統（包括 Windows 11 / Windows Server 2022）中進行測試。

這些安裝說明已使用乾淨且已完全修補的作業系統安裝，並在其中安裝了 Tomcat 9（安裝於 C:\Program Files\Apache Software Foundation\Tomcat 9.0），以及 IIS 加上 ISAPI 延伸模組和篩選器的預設安裝進行測試。在本文件中其餘部分，這稱為 ${tomcat_home}。

1. 建立目錄 ${tomcat_home}\isapi
2. 允許 IIS 程序建立 ISAPI 重導器記錄檔。如果記錄檔要寫入其他目錄，請視需要修改路徑。在命令提示字元中輸入下列內容

   >icacls "C:\Program Files\Apache Software Foundation\Tomcat 9.0\isapi" /grant "IIS APPPOOL\DefaultAppPool":(OI)(CI)M
   

   在啟用使用者帳戶控制 (UAC) 的用戶端作業系統中，必須使用 以系統管理員身分執行 開啟命令提示字元，才能順利完成上述命令。
3. 下載適用於作業系統的 isapi_redirect.dll（32 位元或 64 位元），並將其放置在 ${tomcat_home}\isapi
4. 設定 isapi_redirect.dll 的權限。在 Windows Server 2019 中，似乎需要明確設定此 dll 的權限。在命令提示字元中輸入下列內容

   >icacls "C:\Program Files\Apache Software Foundation\Tomcat 9.0\isapi\isapi_redirect.dll" /grant "Everyone":RX
   

5. 建立 ${tomcat_home}\isapi\isapi_redirect.properties 檔案，以設定 ISAPI 重導器。也可以透過登錄設定進行設定，請見下方。此檔案的內容應為

   extension_uri=/jakarta/isapi_redirect.dll
   log_file=C:\Program Files\Apache Software Foundation\Tomcat 9.0\isapi\isapi_redirect.log
   log_level=info
   worker_file=C:\Program Files\Apache Software Foundation\Tomcat 9.0\isapi\workers.properties
   worker_mount_file=C:\Program Files\Apache Software Foundation\Tomcat 9.0\isapi\uriworkermap.properties
   

   請小心，不要讓 Windows 在檔案中新增 .txt 副檔名。
6. 建立 ${tomcat_home}\isapi\workers.properties 檔案，以設定將請求傳遞到的 Tomcat 執行個體。對於本機上的單一 Tomcat 執行個體，此檔案的內容應為

   worker.list=tomcat01
   worker.tomcat01.type=ajp13
   worker.tomcat01.host=localhost
   worker.tomcat01.port=8009
   

7. 建立 ${tomcat_home}\isapi\uriworkermap.properties 檔案，以設定將哪些請求傳遞到 Tomcat。若要公開範例 Web 應用程式，此檔案的內容應為

   /examples/*=tomcat01
   

8. 使用 IIS 管理主控台，新增一個新的虛擬目錄到 IIS 網站。在乾淨的安裝中，這會是 預設網站。虛擬目錄的名稱必須是 jakarta。其實體路徑應該是您放置 isapi_redirect.dll 的目錄。
9. 在管理主控台中選取新建立的虛擬目錄，然後按兩下 處理常式對應。選取（目前已停用的）ISAPI-dll 項目，然後在動作窗格中按一下 編輯功能權限。在開啟的對話方塊中，選取 執行，讓所有三個權限都選取。按一下 確定，ISAPI-dll 現在應該處於已啟用的狀態。
10. 再次使用 IIS 管理主控台，將 ISAPI 重導器新增為網站的篩選器。選取您的網站，然後按兩下 ISAPI 篩選器。從動作窗格中，按一下 新增...。對於篩選器名稱，請使用 tomcat，而可執行檔應該是 isapi_redirect.dll 的完整路徑。設定完畢後，按一下 確定。
11. 仍使用 IIS 管理主控台，將 ISAPI 重導器設定為允許。選取您的伺服器（不是網站），然後按兩下 ISAPI 和 CGI 限制。從動作窗格中，按一下 新增...。選取 isapi_redirect.dll，新增說明（例如 tomcat），然後選取 允許執行延伸模組路徑，然後按一下 確定。
12. 重新啟動 IIS（停止 + 啟動 IIS 服務）。

這樣就完成了，現在您應該啟動 Tomcat 並要求 IIS 為您提供 /examples 內容。例如，嘗試 https://127.0.0.1/examples/ 並執行一些 Servlet 或 JSP 範例。

如果這無法順利運作，請參閱下方的疑難排解部分，以取得修正問題的協助。

如果 IIS 存取記錄顯示項目，例如 /jakarta/isapi_redirect.dll 而不是 /examples/servlets，則可透過 IIS 管理主控台修正此問題。選取您的伺服器（不是網站），然後按兩下 模組。在 動作 窗格中，按一下 檢視已排序清單...，選取 IsapiFilterModule 並將其向上移動，直到它位於 HttpLoggingModule 上方。

除了使用 isapi_redirector.properties 檔案，也可以透過登錄設定 ISAPI 重新導向器。若要執行此動作，請遵循下列步驟

1. 在登錄中，建立一個名為 "HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0" 的新登錄金鑰
2. 新增一個字串值，其名稱為 extension_uri，其值為 /jakarta/isapi_redirect.dll
3. 新增一個字串值，其名稱為 log_file，其值指向您希望記錄檔所在的位置（例如 c:\tomcat\logs\isapi.log）。
4. 新增一個字串值，其名稱為 log_level，其值為您的記錄層級（可以是 debug、info、error 或 emerg）。
5. 新增一個字串值，其名稱為 worker_file，其值為您的 workers.properties 檔案的完整路徑（例如 c:\tomcat\conf\workers.properties）
6. 新增一個字串值，其名稱為 worker_mount_file，其值為您的 uriworkermap.properties 檔案的完整路徑（例如 c:\tomcat\conf\uriworkermap.properties）

在 64 位元環境中，IIS 應用程式集區應將「啟用 32 位元應用程式」設定為「否」。若要檢查此設定，請在 IIS 管理主控台中選取 應用程式集區，然後按一下滑鼠右鍵，選取您正在使用的集區，並選取 設定應用程式集區預設值...。啟用 32 位元應用程式 可能會在 一般 部分中找到。如果此設定未正確設定，則不會呼叫重新導向器，而 IIS 會傳回 HTTP 404 程式碼。

您必須在 64 位元作業系統上使用 64 位元版本的 ISAPI 重新導向器。如果您嘗試使用 32 位元版本，則會為每個要求取得 HTTP 500 程式碼，因為無法將程式庫載入至 64 位元 IIS。

範例內容有助於驗證您的安裝，但您也需要新增自己的內容。新增新的內容需要執行兩個操作

1. 將內容新增至 Tomcat（在此不討論）。
2. 將內容新增至 ISAPI 重新導向器。

將內容新增至 ISAPI 重新導向器很簡單，您只需要編輯您的 uriworkermap.properties 並新增一行，其外觀如下

/context/*=worker_name

工作人員及其名稱在 workers.properties 中定義。舉例來說，如果您想要新增一個名為「shop」的內容，由名為「tomcat01」的工作人員提供服務，則您應該新增至 uriworkermap.properties 的行將會是

/shop/*=tomcat01

上述內容應該是您讓 IIS 傳遞至 Tomcat 任何對應至 Tomcat 內容（webapp）的 URI 要求所需的全部內容。

如果您的網站非常忙碌（每秒超過 100 個要求，或超過 100 個同時的用戶端連線），有時可能需要讓 IIS 直接提供靜態內容（html、gif、jpeg 等），即使這些檔案是 Tomcat 提供的內容的一部分。允許 IIS 直接提供此類檔案可以避免將要求傳遞給 Tomcat 的重導器所造成的輕微負擔，並可以透過僅使用 Tomcat 處理只有 Tomcat 可以處理的要求（例如，對 JSP 頁面和 Java servlet 的要求）來釋放 Tomcat 的資源。

例如，考慮範例內容中的 html 和 gif 檔案：您可以使用 IIS 直接提供這些檔案；不需要從 Tomcat 程序提供這些檔案。

讓 IIS 提供 Tomcat 內容的一部分的靜態檔案需要下列事項

1. 組態 IIS 以了解 Tomcat 內容
2. 組態重導器以將靜態檔案留給 IIS

將 Tomcat 內容新增到 IIS 需要新增一個涵蓋 Tomcat 內容的新 IIS 虛擬目錄。例如，新增一個涵蓋 c:\tomcat\webapps\examples 目錄的 /example IIS 虛擬目錄。

組態重導器有點困難，您需要指定您希望 Tomcat 處理的確切 URL 路徑模式（通常只有 JSP 檔案和 servlet）。這需要變更 uriworkermap.properties

For the examples context it requires to replace the following line
/examples/*=tomcat01
with the following two lines
/examples/*.jsp=tomcat01
/examples/servlet/*=tomcat01

如您所見，第二個組態比較明確，它實際上指示重導器僅重導到 /examples/servlet/ 下的資源和名稱以 .jsp 結尾的 /examples/ 下的資源的要求。

您甚至可以更明確地提供下列行

/example/servlets/chat=tomcat01

指示重導器將所有 URL 路徑與開頭字串「/example/servlets/chat」相符的要求重導到名為 tomcat01 的工作執行緒。

再次提醒，請注意，允許 IIS 直接存取您的 Tomcat 內容，您可能會繞過 Tomcat 對該內容的保護。因此，您應該在需要時使用對應的 IIS 管理主控台功能在 IIS 層級保護此內容。

特別是，每個 servlet 應用程式（內容）都有名為 WEB-INF 的特殊目錄，其中包含敏感的組態資料和 Java 類別，並且應該始終對網路使用者隱藏。使用 IIS 管理主控台可以保護 WEB-INF 目錄免於使用者存取，但考慮到這是個一般性需求，並且考慮到很容易忘記在 IIS 層級實作此保護，ISAPI 重導器外掛程式會自動為您執行此動作，並且會拒絕任何在 URL 路徑中包含 WEB-INF 的要求。它也會拒絕任何在 URL 路徑中包含 META-INF 的要求。

有時您可能想要使用不同的 Tomcat 程序來提供不同的內容（例如在不同的機器之間分散負載）。若要達成此目標，您需要定義多個工作者，並將每個內容指派給它自己的工作者。

在 workers.properties 檔案中定義其他工作者。此檔案包含兩種類型的項目

# An entry that lists all the workers defined
worker.list=worker1, worker2
# Entries that define the host and port associated with each of these workers
worker.worker1.host=localhost
worker.worker1.port=8009
worker.worker1.type=ajp13
worker.worker2.host=otherhost
worker.worker2.port=8009
worker.worker2.type=ajp13

上述範例定義了兩個工作者，現在我們可以使用這些工作者來提供兩個不同的內容，每個內容都有自己的工作者

example uriworkermap.properties fragment
/examples/*=worker1
/webpages/*=worker2

您會看到 範例 內容由 工作者 1 提供，而 網頁 內容由 工作者 2 提供。

有關在 工作者操作指南 和 worker.properties 組態參考 中使用和組態工作者的更多資訊。

如果存在，請刪除（或移至其他位置）ISAPI 重新導向器記錄檔。

啟動 IIS 服務和 Tomcat。

檢查指定位置是否存在 ISAPI 重新導向器記錄檔。如果找不到，表示 ISAPI 重新導向器尚未正確啟動。這通常是由於組態設定不正確所造成。

• 仔細檢查您的組態是否符合安裝說明，尤其是 ${tomcat_home}\isapi\isapi_redirect.properties 檔案的位置、名稱和內容。
• 如果使用基於登錄的組態，請檢查登錄機碼的路徑、名稱和值。登錄名稱不區分大小寫。
• 檢查為日誌檔案指定的目錄是否存在，以及檔案權限是否已根據安裝說明進行組態。

在您的瀏覽器中呼叫 URL https://127.0.0.1/examples/。URL 中的大小寫很重要。URL 中「localhost」之後的字元必須是小寫。如果頁面無法顯示，請停止 IIS 服務（需要檢視 IIS 日誌檔案）。然後檢查 C:\inetpub\logs\LogFiles\W3SVC1 中 IIS 日誌檔案的最後一行

如果最後一行包含

GET "/examples/ HTTP/1.1" 404

如果最後一行包含類似

GET "/jakarta/isapi_redirect.dll HTTP1.1"

檢查下列事項

• 仔細檢查您的組態是否符合安裝說明，尤其是虛擬目錄的名稱，以及 ${tomcat_home}\isapi\uriworkermap.properties 和 ${tomcat_home}\isapi\workers.properties 檔案的位置、名稱和內容。
如果這些設定正確，ISAPI 重導程式應辨識它應該處理「/examples」內容的請求。

如果瀏覽器顯示 503 錯誤頁面，則表示 ISAPI 重導程式辨識它應該處理請求，但未從 Tomcat 收到及時的回應。檢查下列事項

• 仔細檢查您的組態是否符合安裝說明，尤其是 ${tomcat_home}\isapi\workers.properties 檔案的位置、名稱和內容。
• 檢查 Tomcat 中的 AJP 連接器組態是否與 ${tomcat_home}\isapi\workers.properties 檔案中的組態相符。

如果瀏覽器顯示 500 錯誤頁面，則表示在 IIS 或 ISAPI 重導程式嘗試提供服務時，發生內部錯誤。頁面頂端應該有錯誤的文字說明，頁面尾端則有 8 位元組的十六進位錯誤代碼。最後四位元組應該是與問題相關的標準 Windows 錯誤代碼。

500 錯誤的常見原因是 Windows 建立具有隱藏「.txt」檔案副檔名的組態檔案，而 Windows Explorer 中不會顯示這些檔案。即使其他檔案顯示檔案副檔名，也要仔細檢查以確保 Windows Explorer 已設定為顯示所有檔案的檔案副檔名。

如果錯誤訊息為 在 ISAPI 篩選器「...isapi_redirect.dll」上呼叫 GetFilterVersion 失敗，且程式碼為 0x8007047e，則程式碼會轉換為錯誤程式碼 0x047e 或 1150，表示「指定的程式需要較新版本的 Windows」。這些訊息共同指出 ISAPI redirector 初始化失敗，因為無法讀取組態，可能是無法從 ${tomcat_home}\isapi\isapi_redirect.properties 或登錄中讀取。檢查 ${tomcat_home}\isapi\isapi_redirect.properties 檔案或登錄金鑰的名稱位置和內容，視情況而定。

如果上述設定正確，index.html 頁面應會顯示在您的瀏覽器中。您也應該可以按一下連結來執行一些 Servlet 或 JSP 範例。