uriworkermap.properties 配置

介绍

通过定义映射规则来配置从 Web 服务器到 Tomcat 的请求转发。此类规则将请求映射到工作器。映射的请求部分由 URI 模式描述，工作器由其工作器名称描述。

所谓的 uriworkermap 文件是一种定义规则的机制，适用于所有 Web 服务器。还存在其他 Web 服务器特定的配置选项用于定义规则，这些选项将主要在配置各个 Web 服务器的 Tomcat 连接器的参考页面中讨论。

该文件的名称通常是 uriworkermap.properties，尽管这在 Web 服务器中是可配置的。有关如何启用 uriworkermap 文件，请查阅 Web 服务器特定的文档页面。

uriworkermap 文件支持的主要功能是

  • 支持规则文件中的注释。
  • 精确匹配和通配符匹配，以及映射目录及其所有内容的快捷方式。
  • 排除规则、禁用规则和规则优先级。
  • 规则扩展，根据规则修改工作器行为。
  • 虚拟主机集成：URI 映射规则可以按虚拟主机表达。但具体细节与 Web 服务器相关。
  • 动态重新加载：文件会定期检查是否有更改。新版本会自动重新加载，无需重新启动 Web 服务器。
  • 与状态工作器集成。
以下章节将更详细地描述这些方面。

语法

行格式

该文件采用基于行的格式。没有续行符，因此每条规则都需要定义在单行上。每条规则都是一个由 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。如果排除规则匹配，请求将不会被转发。这通常用于由 Web 服务器提供静态内容。如果规则以 '!' 后缀，则它是一个排除规则。

# 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=*

如果您的 Web 服务器合并了来自不同源的规则，并且您希望禁用以前定义的任何规则，则规则禁用功能就会发挥作用。由于 uriworkermap 文件是动态重新加载的，您可以使用它来暂时禁用请求转发：如果规则以 '-' 后缀，则它被禁用。

# We are not in maintenance.
# The maintenance rule got defined somewhere else.
-/*=maintenance
排除规则也可以被禁用，此时规则以 '-!' 开头。

映射优先级

最严格的 URI 模式优先应用。更准确地说，URI 模式按模式中 '/' 字符的数量排序（数量最多的优先），具有相同数量的规则则按字符串长度排序（最长的优先）。

如果以上两种区分仍然不足，则考虑规则的定义来源。uriworkermap.properties 中定义的规则优先于通过 JkMount（针对 Apache HTTP 服务器）和 workers.properties 中使用 mount 属性定义的规则。

所有禁用的规则都被忽略。排除规则在所有正常规则应用之后应用。

对于以下配置冲突，没有明确的行为：在相同的定义源中使用完全相同的 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

扩展 active、disabled 和 stopped 可用于负载均衡器映射规则中，以将负载均衡器的选定成员设置为特殊的激活状态。

# 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 设置为 'On'，则它会继承主服务器的 JkMountFile。如果您希望所有虚拟主机都继承主服务器的挂载，则可以在主服务器中将 JkMountCopy 设置为 'All'。

动态重新加载

当请求被处理时，Tomcat 连接器会检查 uriworkermap 文件的修改时间。为了将性能开销保持在较低水平，只有当上次检查至少在 n 秒前发生时才会进行此操作。

对于 Apache HTTP Server，您可以使用 JkMountFileReload 指令配置间隔 "n"，对于 Microsoft IIS，您将使用 worker_mount_reload 属性。默认值为 60 秒。值为 "0" 会关闭重新加载。

如果文件发生更改，它将完全重新加载。如果存在来自 uriworkermap 文件以外的其他来源的规则（例如 workers.properties mount 属性或 Apache HTTP Server 的 JkMount），则新的 uriworkermap 文件将与这些规则动态合并，就像您重新启动 Web 服务器时一样。

直到版本 1.2.19，重新加载的行为略有不同：它会持续将 uriworkermap 文件的全部内容添加到规则映射中。合并规则是，重复项被消除，旧规则可以通过在新文件中将规则定义为禁用而被禁用。规则从未被删除。

状态工作器集成

状态工作器的配置视图也显示了各种映射规则。在每个工作器的配置之后，列出了转发到该工作器的规则。列表包含四列

  • 虚拟服务器的名称
  • URI 模式，禁用的模式以 '-' 为前缀，排除的模式以 '!' 为前缀
  • 规则类型：精确匹配或通配符匹配
  • 以及规则定义的来源：workers.properties 文件为 'worker definition' (mount 属性)，Apache HTTP Server JkMount 及其相关项为 'JkMount'，最后 uriworkermap 文件为 'uriworkermap'。

注意：从版本 1.2.26 开始，以下限制已被移除。
对于 Apache HTTP Server，有一个重要的细节：发送到状态工作器的请求在某个服务器（主服务器或虚拟服务器）的上下文中执行。状态工作器将仅显示为该服务器（主服务器或虚拟服务器）定义的映射规则。
直到版本 1.2.25，列表包含三列

  • 规则类型：精确匹配或通配符匹配，可能以 Disabled 或 Unmount（用于排除规则）为前缀
  • URI 模式
  • 以及规则定义的来源：workers.properties 文件为 'worker definition' (mount 属性)，Apache HTTP Server JkMount 及其相关项为 'JkMount'，最后 uriworkermap 文件为 'uriworkermap'。