uriworkermap.properties 組態

簡介

從網路伺服器轉發要求至 tomcat 的方式,可透過定義對應規則來組態。此類規則會將要求對應至工作執行緒。對應中的要求部分由 URI 模式描述,工作執行緒則由其工作執行緒名稱描述。

所謂的 uriworkermap 檔案是一種定義規則的機制,適用於所有網路伺服器。也存在其他網路伺服器專用的組態選項,用於定義規則,這些選項大多會在為個別網路伺服器組態 tomcat connectors 的參考頁面中討論。

檔案名稱通常為 uriworkermap.properties,儘管這可以在網路伺服器中組態。請參閱網路伺服器專用的文件頁面,了解如何啟用 uriworkermap 檔案。

uriworkermap 檔案支援的主要功能為

  • 支援規則檔案中的註解。
  • 精確和萬用字元比對,對應目錄和所有包含內容的捷徑。
  • 排除規則、停用規則和規則優先順序。
  • 規則延伸,修改每個規則的工作執行緒行為。
  • 虛擬主機整合:URI 對應規則可針對每個虛擬主機表示。不過,詳細資訊取決於網路伺服器。
  • 動態重新載入:檔案會定期檢查是否有變更。新版本會自動重新載入,而無需重新啟動網路伺服器。
  • 與狀態工作執行緒整合。
以下各節會更詳細地說明這些面向。

語法

行格式

檔案採用基於行的格式。沒有延續字元,因此每個規則都必須定義在單一行中。每個規則都是一對,包含 URI 模式和工作執行緒名稱,並以等號「=」結合

/myapp=myworker
URI 模式區分大小寫。

註解、空白

包含字元「#」及其後的文字都將被忽略,可用於註解。URI 模式和工作者名稱前後的空白將被移除。以下定義皆為等效

# This is a white space example
/myapp=myworker
  /myapp=myworker
/myapp  =  myworker

URI 模式

URI 模式內可以使用三個特殊字元「*」、「?」和「|」。字元「*」為萬用字元,可比對 URI 中任意數量的任意字元;「?」可比對一個字元。每個 URI 模式都必須以字元「/」、或「*」或「?」開頭,並可選擇加上「!」和「-」修飾詞的任意組合(請參閱下一節)。

# Mapping the URI /myapp1 and everything under /myapp1/:
/myapp1=myworker-a
/myapp1/*=myworker-a
# Mapping all URI which end with a common suffix:
*.jsp=myworker
*.do=myworker
由於第一個情況非常常見,即對應某個位置及其內部所有內容,因此字元「|」提供了一個方便的捷徑
# Mapping the URI /myapp1 and everything under /myapp1/:
/myapp1|/*=myworker-a
模式「X|Y」與兩個對應「X」和「XY」完全等效。

排除、停用和優先順序

排除規則和停用規則

排除規則允許定義 URI 規則的排除項,這些規則會將請求轉發至 Tomcat。如果排除規則比對成功,請求將不會被轉發。這通常用於讓網路伺服器提供靜態內容。如果規則加上字尾「!」,則該規則為排除規則

# Mapping the URI /myapp and everything under /myapp/:
/myapp|/*=myworker
# Exclude the subdirectory static:
!/myapp/static|/*=myworker
# Exclude some suffixes:
!*.html=myworker
排除規則僅會覆寫一般對應規則,如果一般規則和排除規則中的工作者名稱相同。從 JK 的版本 1.2.26 開始,您可以將排除規則套用至任何工作者,方法是在排除規則中使用星號字元「*」作為工作者名稱。排除工作者名稱中不允許有更複雜的模式。
# Mapping the webapps /myapp1 and /myapp2:
/myapp1|/*=myworker1
/myapp2|/*=myworker2
# Exclude the all subdirectories static for all workers:
!/*/static|/*=*
# Exclude some suffixes for all workers:
!*.html=*

如果您的網路伺服器會合併來自不同來源的規則,而您想要停用先前定義的任何規則,則會使用停用規則。由於 uriworkermap 檔案會動態重新載入,因此您可以使用此功能暫時停用請求轉發:如果規則加上字尾「-」,則該規則會被停用

# We are not in maintenance.
# The maintenance rule got defined somewhere else.
-/*=maintenance
排除規則也可以被停用,此時規則會以「-!」開頭。

對應優先順序

最嚴格的 URI 模式會最先套用。更精確地說,URI 模式會依據模式中「/」字元的數量排序(數量最高的優先),數量相同的規則則會依據字串長度排序(最長的優先)。

如果這兩個區別仍然無法區分,則會考慮規則的定義來源。定義在 uriworkermap.properties 中的規則優先,其次是 JkMount(適用於 Apache HTTP Server)定義的規則,以及使用 mount 屬性定義在 workers.properties 中的規則。

所有停用的規則都會被忽略。排除規則會在套用所有一般規則後套用。

對於以下設定衝突,沒有定義的行為:在同一個定義來源中,使用完全相同的 URI 模式,但搭配不同的工作目標。

規則擴充

規則擴充新增於版本 1.2.27,在較早版本中無法使用。

語法

規則擴充是額外的屬性,可以附加到任何規則。它們會新增在規則的結尾,每個擴充之間以分號分隔

# This is an extension example,
# setting a reply_timeout of 1 minute
# only for this mapping.
/myapp=myworker;reply_timeout=60000
#
# This is an example using multiple extensions
/myapp=myloadbalancer;reply_timeout=60000;stopped=member1
透過規則擴充設定的屬性,會永遠覆寫工作人員定義檔案中的衝突設定。

擴充 reply_timeout

擴充 reply_timeout 會為單一對應規則設定回覆逾時時間。

# Setting a reply_timeout of 1 minute
# only for this mapping.
/myapp=myworker;reply_timeout=60000
它會覆寫為工作人員定義的任何 reply_timeout。此擴充允許為工作人員設定合理的預設回覆逾時時間,以及為已知會啟動時間密集工作任務的 URL 設定較寬鬆的回覆逾時時間。如需回覆逾時時間的概括說明,請參閱逾時文件。

擴充 sticky_ignore

擴充 sticky_ignore 會停用單一對應規則的會話黏著性。

# Disable session stickyness
# only for this mapping.
/myapp/loginform.jsp=myworker;sticky_ignore=1
此擴充在使用基於 cookie 的會話黏著性時,有助於最佳化負載平衡。這種情況下,只要使用者保持瀏覽器開啟,任何啟動會話的使用者要求都會傳送至同一個 Tomcat 執行個體,即使使用者已離開使用會話的應用程式部分。例如,當使用者要求登入表單時,您可以設定此環境變數,以確保此初始會話要求會以非黏著性的方式平衡。

此擴充自版本 1.2.33 起提供。

擴充 stateless

擴充 stateless 僅在使用基於會話的負載平衡時有用。這種情況下,通常任何未附帶會話 ID 的要求都會被視為新會話。如果您使用 stateless 擴充標記對應規則,則符合對應規則的要求將不會被視為新會話,即使它們未附帶會話 ID。

# Don't let static content trash our session balancing
/myapp/static/*=myworker;stateless=1
此擴充自版本 1.2.33 起提供。

擴充 active/disabled/stopped

擴充 activedisabledstopped 可用於負載平衡器對應規則中,以將負載平衡器的選定成員設定為特殊啟用狀態。

# Stop forwarding only for member1 of loadbalancer
/myapp=myloadbalancer;stopped=member1
多個成員必須以逗號或空白分隔
# Stop forwarding for member01 and member02 of loadbalancer
# Disable forwarding for member21 and member22 of loadbalancer
/myapp=myloadbalancer;stopped=member01,member02;disabled=member21,member22
有關啟動狀態的精確含義,請參閱 啟動 的說明。

擴充功能 fail_on_status

擴充功能 fail_on_status 可用於任何規則

# Send 503 instead of 404 and 500,
# and if we get a 503 also set the worker to error
/myapp=myworker;fail_on_status=-404,-500,503
多個狀態碼必須以逗號分隔。有關屬性的精確含義,請參閱 fail_on_status 的說明。

擴充功能 use_server_errors

擴充功能 use_server_errors 允許 Web 伺服器傳送錯誤頁面,而不是後端 (例如 Tomcat) 錯誤頁面。這很有用,如果想要傳送自訂錯誤頁面,但這些頁面並非所有 Web 應用程式的部分。然後可以將它們放在 Web 伺服器上。

use_server_errors 的值為正數。傳送至後端的任何要求,如果傳回的 http 狀態碼大於或等於 use_server_errors,則會使用 Web 伺服器針對此狀態碼的錯誤頁面回應給用戶端。

# Use web server error page for all errors
/myapp=myworker;use_server_errors=400
# Use web server error page only for technical errors
/myotherapp=myworker;use_server_errors=500

控制負載平衡器黏著性的擴充功能

擴充功能

  • session_cookie
  • session_path
  • set_session_cookie
  • session_cookie_path
允許定義每個掛載點的負載平衡器工作人員屬性(名稱相同)。請參閱 worker.properties 組態參考 中的說明。

虛擬主機整合

Microsoft IIS 的 ISAPI 重新導向器

使用 Microsoft IIS 的 ISAPI 重新導向器時,可以透過在 URI 模式前面加上虛擬主機資訊,將個別規則限制為特定虛擬主機。規則是 url 必須加上主機名稱作為前綴。

# Use www.foo.org as virtual host
/www.foo.org/myapp/*=myworker
# Use www.bar.org as virtual host
/www.bar.org/myapp/*=myworker
# Normal mapping
/mysecondapp/*=myworker

請注意,/mysecondapp/* 會對應至所有現有的虛擬主機。如果需要防止對某些特定虛擬主機進行對應,則必須使用排除規則

# Make sure the myapp is accessible by all virtual hosts
/myapp/*=myworker
# Disable mapping myapp for www.foo.org virtual host
!/www.foo.org/myapp/*=myworker

Apache HTTP Server 的 mod_jk

對於 Apache HTTP Server,可以為每個虛擬主機定義個別的 uriworkermap 檔案。指令 JkMountFile 可用於主伺服器和每個虛擬主機。如果虛擬主機不使用 JkMountfile,但 JkMountCopy 設為「開啟」,則它會從主伺服器繼承 JkMountFile。如果要讓所有虛擬主機從主伺服器繼承掛載點,可以在主伺服器中將 JkMountCopy 設為「全部」。

動態重新載入

當請求正在處理時,tomcat 連接器會檢查 uriworkermap 檔案的檔案修改時間。為了保持效能損失低,這只會在最後一次檢查發生在至少 n 秒前時才會發生。

對於 Apache HTTP Server,您可以使用指令 JkMountFileReload 來設定間隔「n」,對於 Microsoft IIS,您會使用屬性 worker_mount_reload。預設值為 60 秒。值「0」會關閉重新載入。

如果檔案已變更,它會被完全重新載入。如果存在來自 uriworkermap 檔案以外來源的規則(例如 workers.properties mount 屬性或 Apache HTTP Server 的 JkMount),新的 uriworkermap 檔案會與這些檔案動態合併,就像您重新啟動網路伺服器時一樣。

在版本 1.2.19 之前,重新載入的行為略有不同:它會持續將 uriworkermap 檔案的完整內容新增到規則對應。合併規則是,重複的會被消除,舊規則可以透過在新檔案中將規則定義為已停用而停用。規則永遠不會被刪除。

狀態工作人員整合

狀態工作人員的設定檢視也會顯示各種對應規則。在每個工作人員的設定之後,會列出轉發到此工作人員的規則。清單包含四個欄位

  • 虛擬伺服器的名稱
  • URI 模式,對於已停用的模式加上前綴「-」,對於排除模式加上前綴「!」
  • 規則的類型:Exact 或 Wildchar
  • 以及規則定義的來源:workers.properties 檔案的「工作人員定義」(mount 屬性)、Apache HTTP Server JkMount 及其相關檔案的「JkMount」,最後是 uriworkermap 檔案的「uriworkermap」。

注意:從版本 1.2.26 開始,已移除以下限制。
對於 Apache HTTP Server,有一個重要的細微差別:傳送到狀態工作人員的請求會在某個伺服器(主伺服器或虛擬伺服器)的內容中執行。狀態工作人員只會顯示為此伺服器(主伺服器或虛擬伺服器)定義的對應規則。
在版本 1.2.25 之前,清單包含三個欄位

  • 規則的類型:Exact 或 Wildchar,可能加上前綴 Disabled 或 Unmount(對於排除規則)
  • URI 模式
  • 以及規則定義的來源:workers.properties 檔案的「工作人員定義」(mount 屬性)、Apache HTTP Server JkMount 及其相關檔案的「JkMount」,最後是 uriworkermap 檔案的「uriworkermap」。