uriworkermap.properties 配置

简介

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

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

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

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 Server）和在 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 服务器的 mod_jk

对于 Apache HTTP 服务器，可以为每个虚拟主机定义单独的 uriworkermap 文件。指令 JkMountFile 可用于主服务器和每个虚拟主机。如果虚拟主机不使用 JkMountfile，但 JkMountCopy 设置为“On”，则它将从主服务器继承 JkMountFile。如果希望所有 vhost 从主服务器继承挂载点，则可以在主服务器中将 JkMountCopy 设置为“All”。

动态重新加载

在处理请求时，tomcat 连接器会检查 uriworkermap 文件的文件修改时间。为了保持低性能损失，只有在最后一次检查发生在至少 n 秒之前时才会发生这种情况。

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

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

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

状态工作程序集成

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

  • 虚拟服务器的名称
  • URI 模式，对于禁用的模式以“ - ”为前缀，对于排除模式以“ ! ”为前缀
  • 规则的类型：Exact 或 Wildchar
  • 规则定义的来源：workers.properties 文件（挂载属性）的“工作程序定义”，Apache HTTP Server JkMount 及其相关项的“JkMount”，最后是 uriworkermap 文件的“uriworkermap”。

注意：从 1.2.26 版本开始，已取消以下限制。
对于 Apache HTTP Server，有一个重要的细微差别：发送到状态工作程序的请求在某个服务器（主服务器或虚拟服务器）的上下文中执行。状态工作程序只会显示为此服务器（主服务器或虚拟服务器）定义的映射规则。
在 1.2.25 版本之前，该列表包含三列

  • 规则的类型：Exact 或 Wildchar，最终以 Disabled 或 Unmount（对于排除规则）为前缀
  • URI 模式
  • 规则定义的来源：workers.properties 文件（挂载属性）的“工作程序定义”，Apache HTTP Server JkMount 及其相关项的“JkMount”，最后是 uriworkermap 文件的“uriworkermap”。