状态Worker参考

简介

Tomcat连接器有一种特殊类型的Worker，即所谓的“状态Worker”。状态Worker不将请求转发到Tomcat实例。相反，它允许在运行时检索状态和配置信息，并进一步动态更改许多配置项。这可以通过一个简单的嵌入式Web界面完成。

当与负载均衡Worker一起使用时，状态Worker尤其强大。

本文档不解释状态Worker的HTML用户界面。目前为止，它非常简单，所以直接使用即可。本文档旨在解释状态Worker不那么明显的功能。我们还将全面介绍各种请求参数及其含义，以便您可以将状态Worker纳入您的自动化脚本中。

状态Worker的文档从jk 1.2.20版本开始。

使用模式

操作

状态Worker支持以下操作：

  • list: 列出所有已配置Worker的配置和运行时信息。输出将首先按全局信息（版本数据）分组，然后是负载均衡器信息，之后是AJP Worker信息，最后是图例。对于负载均衡器，将有一个摘要部分，然后是每个成员Worker的详细信息。对于所有Worker，我们还包括URL映射（转发定义）。
  • show: 与list相同，但只显示一个选定Worker的数据。
  • edit: 生成一个表单，用于编辑所选Worker的配置数据。有一种特殊的“edit”子类型，可以轻松地更改负载均衡器所有成员的某个属性，例如它们的激活状态。
  • update: 提交在编辑表单中所做的更改。注意：这些更改不会持久保存到配置文件中。一旦您重启Web服务器，通过状态Worker所做的所有更改都将丢失！另一方面，状态Worker所做的更改将在运行时应用，无需重启Web服务器。
  • reset: 重置Worker的所有运行时统计信息。
  • recover: 标记处于错误状态的负载均衡器成员，以便立即恢复。
  • version: 只显示Web服务器和JK软件的版本信息。
  • dump: 列出原始的Worker配置。注意：该转储将只包含启动时使用的配置。状态Worker自身动态管理界面后来应用的任何更改将不会包含在此转储中。dump操作已在版本1.2.27中添加。

输出格式

对于大多数操作，您可以选择4种输出格式。

  • HTML: 与浏览器交互使用。
  • XML: 主要用于自动化，当您的脚本环境对XML友好时。这种格式具有丰富的结构信息，但不是基于行的，因此您会希望将其与XML工具一起使用。
  • Properties: 这种格式是基于行的格式，符合Java属性文件的规则。大多数结构信息包含在分层键中。对于配置性质的信息，该格式应生成与您在workers.properties中使用的行非常相似的行。它不会生成完整的配置文件！
  • Text: 一种简单的文本输出格式。
“edit”操作仅对HTML输出类型有意义。

用户界面功能

在HTML视图中，有一个通过HTML的meta刷新选项实现的自动刷新功能。一旦您启动自动刷新，除了编辑（edit）、更新（update）和维护（maintain）之外的所有操作，UI都将遵循此设置。即使您在这些操作之间导航，一旦返回到其他操作之一，自动刷新将再次启动。

如果您不感兴趣，HTML页面的许多部分可以最小化。有几个“隐藏”链接，可以折叠部分信息。此功能适用于以下信息块：

  • 图例: 不显示“list”和“show”操作中呈现信息的图例。
  • URI映射: 不显示Worker的URI映射。
  • 负载均衡Worker: 不显示类型为“lb”的Worker。
  • AJP Worker: 不显示类型为ajp的Worker。
  • 均衡器成员: 不显示有关负载均衡器每个成员的详细信息。
  • 负载均衡器配置: 不显示负载均衡器的配置数据。
  • 负载均衡器摘要: 不显示负载均衡器的状态摘要。
  • AJP配置: 不显示AJP Worker负载均衡器成员的配置数据。
最后三个最小化功能已在版本1.2.27中添加。

关于URL映射和虚拟主机的特殊考虑

注意: 从版本1.2.26开始，以下限制已被移除。

Apache模块mod_jk利用了Apache HTTP服务器内部关于虚拟主机的基础设施。这带来的缺点是，状态Worker只能显示其定义所在的虚拟主机的URL映射。它无法访问其他虚拟主机的配置对象。当然，您可以在您使用的任何虚拟主机中定义一个状态Worker。除了URL映射之外，所有显示的信息都将相同，与调用状态Worker的虚拟主机无关。

日志记录

状态Worker将以“info”日志级别将对配置所做的更改记录到常规JK日志文件中。无效请求将以“warn”日志级别记录。如果您想报告一些异常行为，调试（“debug”）甚至跟踪（“trace”）级别的日志文件内容将很有用。

配置

基本配置

状态Worker的基本配置与常规AJP Worker非常相似。您需要为Worker指定一个名称，以及您想映射到它的URL。配置的第一部分在workers.properties文件中进行。我们定义一个名为mystatus，类型为status的Worker。

worker.list=mystatus
worker.mystatus.type=status
然后我们定义一个URL，该URL应映射到此Worker，即我们用于访问状态Worker功能的URL。您可以根据所选的Web服务器，使用mod_jk支持的任何方法。可能性包括uriworkermap.properties中的映射、workers.properties中的额外mount属性，或者Apache HTTP服务器的JkMount。以下是uriworkermap.properties行的一个示例：
/private/admin/mystatus=mystatus
URI模式区分大小写。

正如您将在以下章节中了解到的，状态Worker功能非常强大。您应该使用Web服务器的常规身份验证和授权方法来保护此URL。

您还可以通过使用不同的名称和URL映射来定义状态Worker的多个实例。例如，您可能希望单独配置它们，然后允许特定人群使用它们。

输出自定义

workers.properties条目中有几个属性，允许自定义状态Worker输出的各个方面。

属性css可以设置为样式表的URL。

worker.mystatus.css=/private/admin/static/mystatus.css
当生成HTML输出时，状态Worker将包含此行：
<link rel="stylesheet" type="text/css" href="/private/admin/static/mystatus.css" />
mod_jk发布版中不包含示例样式表，并且默认情况下css属性为空，因此页面中不会包含样式表引用。状态Worker输出页面的HTML代码不包含任何class属性。如果您想贡献样式表或改进HTML布局，请在tomcat开发者邮件列表中联系我们。

properties输出格式可以通过属性prefix进行自定义。状态Worker输出的所有属性名称都将以此前缀开头。默认值是“worker”。

几个属性会影响XML输出格式。属性ns允许设置一个命名空间前缀，该前缀将用于每个状态Worker+元素。默认值是“jk:”。将其设置为“-”将禁用命名空间前缀。

使用xmlns属性，您可以将前缀映射到命名空间URL。默认值是xmlns:jk="https://tomcat.net.cn"。将其设置为“-”将禁用URL输出。

最后，您可以通过属性doctype指定XML文档类型。指定字符串将插入到文档开头，紧跟在XML头之后。默认值为空。

保护访问

我们强烈建议您使用Web服务器内置的访问控制功能来控制对您所选状态Worker URL的访问。尽管如此，状态Worker的两个配置属性仍然有用。属性“read_only”禁用状态Worker的所有可用于更改其他Worker配置或运行时状态的功能。只读状态Worker将不允许访问编辑（edit）、更新（update）、重置（reset）或恢复（recover）操作。默认值是false，即读/写。要启用只读，您需要将其设置为true。

您可以配置两个状态Worker，一个设置为只读并供更广泛的管理员组使用，另一个则提供全部功能，但仅供少数人使用。

worker.list=jk-watch
worker.jk-watch.type=status
worker.jk-watch.read_only=true
worker.jk-watch.mount=/user/status/jk
worker.list=jk-manage
worker.jk-manage.type=status
worker.jk-manage.mount=/admin/status/jk
从版本1.2.21开始，用户还可以通过HTML GUI中的链接，将读/写状态Worker暂时切换到只读模式。用户可以随时将其切换回读/写模式。只有通过“read_only”属性配置为只读的状态Worker才能完全避免应用任何更改。

您可以使用的另一个属性是user。默认情况下，此列表为空，这意味着对用户没有限制。您可以将“user”设置为逗号分隔的用户名列表。如果您的Web服务器配置为在请求中发送用户名，则状态Worker将检查请求中附加的名称是否包含在其“user”列表中。

用户列表可以分散在“user”属性的多个出现中。

默认情况下，用户名匹配区分大小写。从版本1.2.21开始，您可以将属性user_case_insensitive设置为true。然后比较将不区分大小写。

服务可用性评级

对于负载均衡Worker，状态Worker显示一些有趣的概述信息。它将负载均衡器的成员分为“良好”（good）、“不良”（bad）和“降级”（degraded）类别。此功能可与外部升级程序结合使用。根据您的全局系统设计和操作实践，您偏好的分类可能有所不同。

此分类基于Worker的激活状态（active, disabled或stopped），这是一个纯粹的配置状态；以及运行时状态（OK或ERR，可能具有子状态idle, busy, recovering, probing和forced recovery），这仅取决于运行时情况。

运行时子状态具有以下含义：

  • OK (空闲): 自上次均衡器维护以来，此Worker未收到任何请求。默认情况下，均衡器维护每60秒运行一次。Worker应该正常，但由于我们有一段时间没有使用它，所以无法确定。在版本1.2.24之前，此状态被称为N/A。
  • OK (忙碌): 此Worker的所有连接都用于请求。
  • ERROR (恢复中): Worker已处于错误状态一段时间，现在被标记为恢复中。适合此Worker的下一个请求将使用它。
  • ERROR (探测中): 将Worker设置为恢复中后，我们收到了一个适合此Worker的请求。该请求现在正在使用此Worker。
  • ERROR (强制恢复): Worker处于错误状态，但我们没有替代Worker，因此我们继续使用它。

默认情况下，状态Worker将所有激活状态为“active”且运行时状态不为“error”（无子状态）的成员归入“良好”（good）组。“不良”（bad）组由激活状态为“stopped”或运行时状态为“error”（无子状态）的成员组成。

不属于这两个组的Worker被视为“降级”（degraded）。

您可以定义其他规则，用于将Worker分组为良好、不良和降级。属性“good”和“bad”可以由逗号分隔的单个字符列表或点分隔的对填充。每个字符代表可能状态“active”、“disabled”、“stopped”、“ok”、“idle”、“busy”、“recovering”和“error”的首字母。附加状态“probing”和“forced recovery”始终被视为等同于“recovering”。逗号分隔的条目将与逻辑“或”组合，如果您用点组合配置状态和运行时状态，则它们将与逻辑“与”组合。因此，“good”的默认值是“a.o,a.i,a.b,a.r”，而“bad”的默认值是“e,s”。

状态Worker首先尝试与“不良”（bad）定义匹配，如果失败则尝试与“良好”（good）定义匹配，如果两者都找不到匹配项，最终选择“降级”（degraded）。

请求参数

本节旨在帮助您基于JK状态管理接口构建自动化脚本。此接口是稳定的，这意味着我们只期望将来添加更多参数。来自先前版本的现有参数将保留其原始语义。我们还期望XML、Properties和Text输出格式保持稳定。因此，如果您想在自动化脚本中解析状态Worker输出，请使用这些格式。

操作

操作由参数cmd确定。它可以具有“list”、“show”、“edit”、“update”、“reset”、“recover”、“version”和“dump”值。如果您省略cmd参数，将使用默认值“list”。除了“list”、“refresh”、“version”和“dump”之外的所有操作都需要附加参数。

“dump”操作已在版本1.2.27中添加。

输出格式

格式由参数mime确定。它可以具有“html”、“xml”、“txt”和“prop”值。如果您省略mime参数，将使用默认值“html”。“edit”操作（编辑表单）仅对“mime=html”有意义。

Worker选择

对单个Worker操作的动作需要一个或两个附加参数来选择此Worker。参数w包含Worker列表中Worker的名称。如果动作是对负载均衡器的一个成员（子Worker）操作，则参数w包含负载均衡器Worker的名称，而附加参数sw包含子Worker的名称。

自动刷新

在自动刷新期间，参数re包含刷新间隔（秒）。如果您省略此参数，自动刷新将关闭。

隐藏选项

参数opt包含一个已激活选项的位掩码。默认值是0，因此默认情况下没有选项被激活。存在以下选项：

  • 0x0001: 隐藏负载均衡Worker的成员。
  • 0x0002: 隐藏URL映射。
  • 0x0004: 隐藏图例。
  • 0x0008: 隐藏负载均衡Worker。
  • 0x0010: 隐藏AJP Worker。
  • 0x0020: 对于读/写状态Worker，只允许只读操作。
  • 0x0040: 隐藏负载均衡器配置。
  • 0x0080: 隐藏负载均衡器状态摘要。
  • 0x0100: 隐藏AJP和负载均衡器成员Worker的配置。
值0x0040-0x0100已在版本1.2.27中添加。

标准更新操作的数据参数

您可以使用编辑操作，最后点击更新按钮来更改Worker的设置。但您也可以直接调用更新操作。以下请求参数包含您想要更改的配置信息。首先是负载均衡Worker的列表：

  • vlr: 重试次数（数字）
  • vlt: 恢复时间（秒）
  • vlee: 错误升级时间（秒）
  • vlx: 最大回复超时次数（数字）
  • vls: sticky_session（0/f/n/off=关闭，1/t/y/on=开启；不区分大小写）
  • vlf: sticky_session_force（0/f/n/off=关闭，1/t/y/on=开启；不区分大小写）
  • vlm: 方法（0/r="请求数"，1/t="流量"，2/b="繁忙度"，3/s="会话数"，4/s="下一个"；不区分大小写，只使用首字母）
  • vll: 锁（0/o="乐观锁"，1/p="悲观锁"；不区分大小写，只使用首字母）
现在是您可以用来更改负载均衡器成员设置的参数列表：
  • vwa: 激活标志（0/a="active", 1/d="disabled", 2/s="stopped"；不区分大小写，只使用首字母）
  • vwf: 负载均衡因子（整数权重）
  • vwn: 用于粘性会话的路由（字符串）
  • vwr: 定义简单故障转移规则的重定向（字符串）
  • vwc: 域，用于告诉JK您的复制设计（字符串）
  • vwd: 距离，用于表达偏好（整数）
最后是您可以用来更改AJP Worker和AJP负载均衡器成员设置的参数列表：
  • vahst: 主机（字符串）
  • vaprt: 端口（数字）
  • vacpt: 连接池超时（数字）
  • vact: 连接超时（数字）
  • vapt: 预处理超时（数字）
  • vart: 回复超时（数字）
  • var: 重试次数（数字）
  • varo: 恢复选项（数字）
  • vabl: 忙碌限制（数字）
  • vamps: 最大数据包大小（数字）
请注意，更改主机名或端口仅对新连接生效。已建立到旧地址的连接仍将继续使用。尽管如此，此功能仍很有趣，因为您可以为负载均衡器成员提供端口“0”，这些成员将在启动时自动停止。稍后当您知道最终的名称和端口时，可以设置它们，它们将自动激活。

参数前缀字符“v”已在版本1.2.27中添加。AJP Worker设置的更改也已在版本1.2.27中引入。

有关所有参数的详细信息，请参阅workers.properties参考。

负载均衡器成员的方面编辑

您可以使用编辑操作在同一页面上分别编辑负载均衡器或负载均衡器成员的所有设置。如果您想同时编辑负载均衡器所有成员的某个配置方面，这将由参数att触发。该参数的值指示您要编辑的方面。列表与上一节相同，但“vahst”和“vaprt”除外：“vwa”、“vwf”、“vwn”、“vwr”、“vwc”、“vwd”、“vacpt”、“vact”、“vapt”、“vart”、“var”、“varo”、“vabl”和“vamps”。但在这里您需要将名称放入参数att中，而不是将其用作请求参数名称。

所有负载均衡器成员的共同方面的数值将通过名为“val0”、“val1”等的参数给出。