Apache Tomcat Connectors - 参考指南

JkWorkersFile 指定 mod_jk 查找工作进程定义的位置。请参阅 工作进程文档 以获取详细说明。

JkWorkersFile     /etc/httpd/conf/workers.properties

JkLogFile 指定 mod_jk 放置其日志文件的位置。

JkLogFile     /var/log/httpd/mod_jk.log

自 Apache 2.x 的 JK 1.2.3 和 Apache 1.3 的 JK 1.2.16 以来，此功能也可用于管道日志记录

JkLogFile     "|/usr/bin/rotatelogs /var/log/httpd/mod_jk.log 86400"

JkLogLevel 设置日志级别

• info 日志将包含标准 mod_jk 活动（默认）。
• warn 日志将包含非致命错误报告。
• error 日志还将包含错误报告。
• debug 日志将包含有关 mod_jk 活动的所有信息
• trace 日志将包含有关 mod_jk 活动的所有跟踪信息

JkLogLevel    info

info 应为正常操作的默认选择。

JkLogStampFormat 将配置 mod_jk 日志文件中找到的日期/时间格式。有关详细信息，请参见上文。

JkLogStampFormat "[%Y-%m-%d %H:%M:%S.%Q] "

您可以使用 Apache 标准模块 mod_log_config 记录 mod_jk 信息。该模块在 Apache 注释表中设置了多个注释。其中大多数仅与负载平衡器工作进程结合使用时才有用。

LogFormat     "%h %l %u %t \"%r\" %>s %b %{JK_WORKER_NAME}n %{JK_LB_FIRST_NAME}n \
               %{JK_LB_FIRST_BUSY}n %{JK_LB_LAST_NAME}n %{JK_LB_LAST_BUSY}n" mod_jk_log
CustomLog     logs/access_log     mod_jk_log

你还可以将请求协议记录在 mod_jk 日志文件中，而不是访问日志中。不推荐这样做，这主要是一个向后兼容性功能。指令 JkRequestLogFormat 将配置此协议的格式。它在每个虚拟主机基础上进行配置和启用。要为虚拟主机启用请求记录，只需添加一个 JkRequestLogFormat 配置。格式字符串的语法类似于 Apache LogFormat 命令，以下是可用请求日志格式选项的列表

JkRequestLogFormat     "%w %V %T"

JkOptions 指令允许你设置许多转发选项，这些选项将启用 (+) 或禁用 (-) 以下选项。如果没有任何前导符号，则将启用选项。

以下四个选项 +ForwardURIxxx 互斥。其中需要一个，不允许使用负号前缀。自 1.2.24 版本以来，默认值为“ForwardURIProxy”。在 1.2.23 版本中为“ForwardURICompatUnparsed”，在 1.2.22 版本之前为“ForwardURICompat”。你可以通过启用其他两个选项之一来关闭默认值。除非你有非常充分的理由更改它，否则你应该将其保留为默认值。

所有选项都从全局服务器继承到虚拟主机。支持启用（加号选项）和禁用（减号选项）的选项以以下方式继承
options(vhost) = plus_options(global) - minus_options(global) + plus_options(vhost) - minus_options(vhost)

使用 JkOptions ForwardURIProxy，转发 URI 将在 Apache 中处理后并转发到 Tomcat 之前部分重新编码。这将与 mod_rewrite 的本地 URL 操作和 URL 编码的会话 ID 兼容。

JkOptions     +ForwardURIProxy

使用 JkOptions ForwardURICompatUnparsed，转发 URI 将未解析。它符合规范且安全。它将始终转发原始请求 URI，因此使用 mod_rewrite 重写 URI 然后转发重写的 URI 将不起作用。

JkOptions     +ForwardURICompatUnparsed

使用 JkOptions ForwardURICompat，Apache 将解码转发 URI。将解码编码字符，并且显式路径组件（如“..”）将已解析。这不太符合规范，并且如果你正在使用前缀 JkMount，则不安全。此选项允许在转发之前使用 mod_rewrite 重写 URI。

JkOptions     +ForwardURICompat

使用 JkOptions ForwardURIEscaped，转发 URI 将是 ForwardURICompat 使用的 URI 的编码形式。显式路径组件（如“..”）将已解析。这将无法与 URL 编码的会话 ID 结合使用，但它允许在转发之前使用 mod_rewrite 重写 URI。

JkOptions     +ForwardURIEscaped

JkOptions RejectUnsafeURI 将阻止所有包含百分号“%”或反斜杠“\”的 URL（在解码之后）。

大多数 Web 应用程序不会使用此类 URL。通过使用 RejectUnsafeURI 选项，您可以阻止几种众所周知的 URL 编码攻击。默认情况下，此选项未设置。

您还可以使用功能更强大但稍显复杂的 mod_rewrite 实现此类检查。

JkOptions     +RejectUnsafeURI

自 1.2.44 起，JkOptions CollapseSlashesAll 已弃用，如果使用，将被忽略。

自 1.2.44 起，JkOptions CollapseSlashesUnmount 已弃用，如果使用，将被忽略。

自 1.2.44 起，JkOptions CollapseSlashesNone 已弃用，如果使用，将被忽略。

JkOptions ForwardDirectories 与 Apache 的 DirectoryIndex 指令结合使用。因此，mod_dir 应该以静态或动态 (DSO) 的方式供 Apache 使用。

配置 DirectoryIndex 时，Apache 将为指令中指定的每个本地 URL 创建子请求，以确定是否存在匹配的本地文件（通过对文件进行 stat 来完成此操作）。

如果 ForwardDirectories 设置为 false（默认值），并且 Apache 找不到任何匹配的文件，Apache 将提供目录的内容（如果指令 Options 为该目录指定了 Indexes）或 403 Forbidden 响应（如果指令 Options 未为该目录指定 Indexes）。

如果 ForwardDirectories 设置为 true，并且 Apache 找不到任何匹配的文件，请求将被转发到 Tomcat 以进行解析。在 Apache 由于各种原因无法在文件系统上看到索引文件时，将使用此功能：Tomcat 在不同的计算机上运行、JSP 文件已预编译等。

请注意，本地可见文件将优先于仅对 Tomcat 可见的文件（即如果 Apache 可以看到该文件，则将提供该文件）。如果 Tomcat 通常提供多种类型的文件，这一点非常重要，例如 Velocity 页面和 JSP 页面。

JkOptions     +ForwardDirectories

设置 JkOptions ForwardLocalAddress，您要求 mod_jk 发送 Apache HTTP 服务器的本地地址，而不是远程客户端地址。Tomcat 远程地址阀门可以使用此功能来仅允许来自已配置 Apache 服务器的连接。

JkOptions     +ForwardLocalAddress

设置 JkOptions ForwardPhysicalAddress，您要求 mod_jk 将物理对等 TCP IP 地址作为客户端地址发送。默认情况下，mod_jk 使用 Web 服务器提供的逻辑地址。例如，模块 mod_remoteip 将逻辑 IP 地址设置为客户端 IP，该 IP 由 X-Forwarded-For 标头中的代理转发。

JkOptions     +ForwardPhysicalAddress

JkOptions FlushPackets，您要求 mod_jk 在从 Tomcat 收到每个 AJP 数据包块后刷新 Apache 的连接缓冲区。此选项可能会对 Apache 和 Tomcat 造成严重的性能损失，因为写入操作执行的频率比通常需要的要高（即：在每个响应的末尾）。

JkOptions     +FlushPackets

JkOptions FlushHeader，您要求 mod_jk 在从 Tomcat 收到响应头后刷新 Apache 的连接缓冲区。

JkOptions     +FlushHeader

JkOptions DisableReuse，您要求 mod_jk 在使用连接后立即关闭连接。通常，mod_jk 使用持久连接并池化空闲连接以在需要将新请求发送到 Tomcat 时重用它们。

使用此选项会对 Apache 和 Tomcat 造成严重的性能损失。仅在无法解决的网络问题的情况下才将其作为最后手段使用。如果 Apache 和 Tomcat 之间的防火墙会静默关闭空闲连接，请尝试将 worker 属性 socket_keepalive 与操作系统中适当的 TCP 保活值结合使用。

JkOptions     +DisableReuse

JkOptions ForwardKeySize，当使用 ajp13 时，您要求 mod_jk 也转发 Servlet API 2.3 所需的 SSL 密钥大小。当 servlet 引擎为 Tomcat 3.2.x 时，不应设置此标志（默认情况下启用）。

JkOptions     +ForwardKeySize

JkOptions ForwardSSLCertChain，当使用 ajp13 时，您要求 mod_jk 转发 SSL 证书链（默认情况下关闭）。Mod_jk 仅将 SSL_CLIENT_CERT 传递给 AJP 连接器。对于自签名证书或直接由根 CA 证书签名的证书，这不是问题。但是，有大量由中间 CA 证书签名的证书，这是一个重大问题：servlet 将无法自行验证客户端证书。通过 AJP 连接器将 SSL_CLIENT_CERT_CHAIN 传递给 Tomcat 可以修复此错误。
此指令仅从 1.2.22 版本开始存在。

JkOptions     +ForwardSSLCertChain

指令 JkEnvVar 允许您将环境变量从 Apache 服务器转发到 Tomcat 引擎。您可以将默认值作为指令的第二个参数添加。如果未明确给出默认值，则仅当在运行时设置变量时才会发送该变量。
可以在 Tomcat 端通过请求属性 request.getAttribute(attributeName) 检索变量。请注意，通过 JkEnvVar 发送的变量不会列在 request.getAttributeNames() 中。
这些变量从全局服务器继承到虚拟主机。

JkEnvVar     SSL_CLIENT_V_START     undefined

如果您已创建自定义或本地版本的 mod_jk.conf-local（如上所述），则可以更改设置，例如 worker 或 URL 前缀。

JkMount 指令为 Tomcat 分配特定的 URL。通常，JkMount 指令的结构为

JkMount [URL prefix] [Worker name]

# send all requests ending in .jsp to worker1
JkMount /*.jsp worker1
# send all requests ending /servlet to worker1
JkMount /*/servlet/ worker1
# send all requests jsp requests to files located in /otherworker will go worker2
JkMount /otherworker/*.jsp worker2

您可以在 httpd.conf 文件的顶级或 <VirtualHost> 部分中使用 JkMount 指令。

JkUnMount 指令与 JkMount 相反，它会阻止访问特定的 URL。其目的是能够从已装载的上下文中过滤出特定的内容类型。以下示例装载了 /servlet/* 上下文，但不会提供属于该上下文的任何 .gif 文件。

# send all requests ending with /servlet to worker1
JkMount /servlet/* worker1
# do not send requests ending with .gif to worker1
JkUnMount /servlet/*.gif worker1

JkUnMount 优先于 JkMount 指令，这意味着 JK 会先尝试装载，然后检查是否存在由 JkUnMount 定义的排除项。只有当 JkMount 和 JkUnMount 中的 worker 名称相同，JkUnMount 才会覆盖 JkMount。

以下示例将阻止所有 .gif 文件，尽管有针对它们的 JkMount

# do not send requests ending with .gif to worker1
JkUnMount /*.gif worker1
# The .gif files will not be mounted cause JkUnMount takes
# precedence over JkMount directive
JkMount /servlet/*.gif worker1

从 JK 1.2.26 版本开始，您可以通过在 JkUnMount 中使用星号字符 '*' 作为 worker 名称，将 JkUnMount 应用于任何 worker。JkUnMount worker 名称中不允许出现更复杂的模式。

# Mapping the webapps myapp1 and myapp2:
/myapp1/*=worker1
/myapp2/*=worker2
# Exclude the all subdirectories static for all workers:
!/*/static/*=*
# Exclude some suffixes for all workers:
!*.html=*

JkAutoAlias 指令会自动将 Webapp 上下文目录别名到 Apache 文档空间中。它使 Apache 能够提供静态上下文，而 Tomcat 提供动态上下文。此指令用于方便起见，这样您不必为 Tomcat 的 webapp 目录中的每个应用程序目录放置 Apache Alias 指令。出于安全原因，强烈建议默认情况下使用 JkMount 将所有请求传递给 Tomcat，并使用 JkUnMount 明确排除由 Apache 提供的静态内容。还应注意，由 Apache 提供的内容将绕过应用程序的 web.xml 中定义的任何安全约束。该指令仅适用于具有单个路径元素且没有版本标记的上下文的简单情况。它不支持

• ROOT 上下文（即 .../webapps/ROOT）
• 多级上下文（例如 .../webapps/foo#bar）
• 并行部署（例如 .../webapps/foo##v00.05.12）

# enter the full path to the tomcat webapps directory
JkAutoAlias /opt/tomcat/webapps

以下示例演示了如何使用 Tomcat 提供动态上下文，并使用 Apache 提供静态上下文。Apache 必须能够访问 webapps 目录。

# enter the full path to the tomcat webapps directory
JkAutoAlias /opt/tomcat/webapps

# Mount 'examples' directory. It's physical location
# is assumed to be in the /opt/tomcat/webapps/examples
# ajp13w is a worker defined in the workers.properties
JkMount /examples/* ajp13w

# Unmount desired static content from examples webapp.
# This content will be served by the Apache directly.
JkUnMount /*.gif ajp13w

请注意，您可以在 httpd.conf 中为每个虚拟主机设置一个 JkAutoAlias 指令

JkWorkerProperty 是 JK 1.2.7 版本中提供的新指令。它是一种方便的方法，用于设置通常在 workers.propeties 文件中设置的指令。该指令的参数是 workers.properties 文件中的原始行。

# Just like workers.properties but exact line is prefixed
# with JkWorkerProperty

# Minimal jk configuration
JkWorkerProperty worker.list=ajp13w
JkWorkerProperty worker.ajp13w.type=ajp13
JkWorkerProperty worker.ajp13w.host=localhost
JkWorkerProperty worker.ajp13w.port=8009   

JkMountFile 是 JK 1.2.9 版本中提供的一项新指令。它用于在运行时动态更新装入点。当装入文件发生更改时，JK 将重新加载其内容。

# Load mount points

JkMountFile conf/uriworkermap.properties

如果装入点 URI 以感叹号“！”开头，则它会像 JkUnMount 一样定义一个排除项。如果装入点 URI 以减号“-”开头，则仅禁用装入点。可以通过删除减号并等待 JkMountFile 重新加载来重新启用已禁用的装入点。可以通过添加减号前缀来禁用排除项。

# Sample uriworkermap.properties file

/examples/*=ajp13w
# Do not map .gif files
!/*.gif=ajp13w
# Make jsp examples initially disabled  
-/examples/jsp/*=ajp13w

在运行时，您可以更改此文件的内容。例如，删除减号将启用先前禁用的 URI 映射。您可以在运行时添加任意数量的新条目，以反映新部署的应用程序。Apache 将在 60 秒间隔内重新加载文件并更新装入点。

无法通过动态重新加载删除条目，但您可以禁用或排除映射。

除了 mod_jk 特定的指令外，您还可以使用 SetHandler 和环境变量来控制通过哪个工作进程转发请求。这为您提供了更大的灵活性，但结果可能更难理解。如果您混合使用这两种定义转发的方式，通常 mod_jk 指令会获胜。

SetHandler jakarta-servlet 强制由 mod_jk 处理请求。例如，您可以在 Location 块中或在 Apache 2.2 及更高版本中使用 SetHandler，也可以在 RewriteRule 中使用。

为了使用 SetEnvIf 或 RewriteRule 控制工作进程以制定更复杂的规则，您可以将环境变量 JK_WORKER_NAME 设置为您选择的目标工作进程的名称。这使您能够以更灵活的方式决定所选工作进程，包括依赖于 cookie 值。此功能已添加到 mod_jk 的 1.2.19 版本中。此外，您还可以将规则扩展名附加到工作进程名称。扩展名通过分号“；”与工作进程名称分隔，使用与 uriworkermap.properties 文件中相同的语法。在工作进程名称中支持规则扩展名已添加到 1.2.33 版本中。

为了使用 JK_WORKER_NAME 之外的其他变量，您可以通过 JkWorkerIndicator 指令设置此变量的名称。

您还可以通过设置环境变量 no-jk 来定义 mod_jk 转发的排除项。

# Automatically map all encoded urls
<Location *;jsessionid=>
  SetHandler jakarta-servlet
  SetEnv JK_WORKER_NAME my_worker
</Location>

# Map all subdirs to workers via naming rule
# and exclude static content.
<Location /apps/>
  SetHandler jakarta-servlet
  SetEnvIf REQUEST_URI ^/apps/([^/]*)/ JK_WORKER_NAME=$1
  SetEnvIf REQUEST_URI ^/apps/([^/]*)/static no-jk
</Location>

环境变量允许根据请求属性（例如请求 URI、标头值或 cookie）覆盖 mod_jk 的默认行为。这可以使用 SetEnvIf 或 RewriteRule 指令来完成。

可以设置环境变量 JK_ROUTE 来明确选择负载平衡器工作进程的成员。该值必须等于成员的 route 属性，或者如果未使用该属性，则等于成员名称。请注意，仅当会话 ID 和路由在请求中以非标准方式编码时才需要这样做。默认情况下，支持使用 Java Servlet 兼容方式对 ID 进行编码的粘性。此功能自 1.2.33 版本起可用。

可以设置环境变量 JK_REPLY_TIMEOUT 来动态定义答复超时。该值必须以毫秒为单位给出。此功能自 1.2.27 版本起可用。

可以设置环境变量 JK_STICKY_IGNORE 来禁用单个请求的会话粘性。如果该变量被设置为一个空字符串或一个非零数字，则会话粘性将被禁用。将其设置为 0 将重置为由工作进程配置定义的行为。此功能自 1.2.33 版本起可用。

使用基于 Cookie 的会话粘性时，此功能可用于优化负载平衡。在这种情况下，只要用户保持浏览器处于打开状态，则由启动会话的用户发出的任何请求都将发送到同一 Tomcat 实例，即使用户离开了使用会话的应用程序部分。例如，当用户请求登录表单时，您可以设置此环境变量，以确保此初始会话请求以非粘性方式进行平衡。

环境变量 JK_STATELESS 可用于提高基于会话的平衡方法 Session 和 Next 的负载平衡。在这种情况下，通常任何不带会话 ID 的请求都算作新会话。如果在没有会话 ID 的情况下检索静态内容，则这可能会出现问题。如果您为请求设置环境变量 JK_STATELESS，则即使请求不带会话 ID，也不会将该请求算作新会话。此功能自版本 1.2.33 起提供。

可以设置环境变量 JK_IGNORE_CL 以强制忽略请求 Content-Length 标头（如果存在）。然后，mod_jk 将流式传输请求正文，直到 Web 服务器指示已读取完整正文。不会向后端发送 Content-Length 标头。此功能自版本 1.2.41 起提供。

此功能可用于使 mod_jk 与更改请求正文大小的过滤器兼容。其中一个过滤器是 mod_deflate，当用于对使用 gzip 编码正文的请求正文进行解压缩时。在这种情况下，mod_jk 默认会转发截断的正文，因为它从 Web 服务器获取了错误的正文大小。告知 mod_jk 忽略 Content-Length 标头将导致将所有可从 Web 服务器读取的请求正文数据流式传输到后端。

您应该仅为实际需要 JK_IGNORE_CL 环境变量的请求设置该变量。遗憾的是，mod_jk 无法自动检测到此需求。