Apache Tomcat 连接器 - 参考指南

JkWorkersFile 指定 mod_jk 查找 worker 定义的位置。有关详细说明，请参阅Worker 文档。

JkWorkersFile     /etc/httpd/conf/workers.properties

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

JkLogFile     /var/log/httpd/mod_jk.log

自 JK 1.2.3（适用于 Apache 2.x）和 JK 1.2.16（适用于 Apache 1.3）起，此功能也可用于管道日志记录。

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 备注表中设置了多条备注。它们大多数仅在与负载均衡器 worker 结合使用时才有用。

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，转发的 URI 将由 Apache 解码。编码字符将被解码，并且像 ".." 这样的显式路径组件将已被解析。这不太符合规范，并且如果您使用前缀 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

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

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

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

JkOptions ForwardDirectories 与 Apache 的 DirectoryIndex 指令结合使用。因此，mod_dir 应该对 Apache 可用，无论是静态还是动态（DSO）加载

当配置 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 Server 的本地地址，而不是远程客户端地址。这可以被 Tomcat 远程地址阀用于仅允许来自已配置 Apache 服务器的连接。

JkOptions     +ForwardLocalAddress

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

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 之间的防火墙悄悄地终止空闲连接，请尝试结合操作系统中适当的 TCP keepalive 值使用 worker 属性 socket_keepalive。

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 的自定义或本地版本，则可以更改 workers 或 URL 前缀等设置。

JkMount 指令将特定的 URL 分配给 Tomcat。通常，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 提供静态内容。webapps 目录必须对 Apache 可访问。

# 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.properties 文件中设置的指令。该指令的参数是 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 和环境变量来控制哪些请求通过哪个 worker 进行转发。这为您提供了更大的灵活性，但结果可能更难理解。如果您混合使用两种定义转发的方式，通常 mod_jk 指令将优先。

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

为了使用 SetEnvIf 或 RewriteRule 控制 worker 以实现更复杂的规则，您可以将环境变量 JK_WORKER_NAME 设置为您选择的目标 worker 的名称。这使您能够以更灵活的方式决定选择的 worker，包括对 cookie 值的依赖。此功能已在 mod_jk 的 1.2.19 版本中添加。此外，您可以将规则扩展附加到 worker 名称。扩展名与 worker 名称之间用分号 ";" 分隔，使用的语法与 uriworkermap.properties 文件中相同。在 worker 名称中支持规则扩展已在 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 可以设置来明确选择负载均衡器 worker 的一个成员。该值必须等于成员的路由属性，如果未使用该属性，则等于成员名称。请注意，只有当会话 ID 和路由在请求中以非标准方式编码时才需要此功能。默认情况下支持使用符合 Java Servlet 规范的方式编码 ID 的粘性会话。此功能自 1.2.33 版本起可用。

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

环境变量 JK_STICKY_IGNORE 可以设置来禁用单个请求的会话粘性。如果变量设置为空字符串或非零数字，会话粘性将被禁用。将其设置为 0 将重置为 worker 配置定义的行为。此功能自 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 无法自动检测到此需求。