Apache Tomcat Connectors - Web 服务器指南

${tomcat_home} 是 tomcat 的根目录。您的 Tomcat 安装应具有以下子目录

• ${tomcat_home}\conf - 您可以在其中放置各种配置文件
• ${tomcat_home}\webapps - 包含示例应用程序
• ${tomcat_home}\bin - 您放置 Web 服务器插件的位置

在本文档的所有示例中，${tomcat_home} 将为 c:\tomcat。工作进程被定义为接受 IIS 服务器工作的 tomcat 进程。

IIS 到 Tomcat 重定向器支持

• 在任何当前受支持的 Windows 版本上运行的 IIS
• 所有当前受支持的 Tomcat 版本

重定向器可能适用于在较旧的、不受支持的 Windows 版本和/或 Tomcat 上运行的 IIS，但此类配置不受支持。

重定向器使用 AJP 协议将请求发送到 Tomcat 容器。使用的 AJP 版本是 ajp13。所有当前版本的 Tomcat 都支持 ajp13 协议。其他 servlet 引擎（如 Jetty 和 JBoss）也支持 ajp13 协议。

ajp12 协议已被弃用，您不再应该使用它。ajp14 协议被认为是实验性的。

1. ISAPI 重定向器是一个 Microsoft IIS 插件（过滤器 + 扩展）。IIS 加载重定向器插件并为每个传入请求调用其过滤器函数。
2. 然后，过滤器根据 uriworkermap.properties 中保存的 URI 路径列表测试请求 URL。如果当前请求与 URI 路径列表中的某个条目匹配，则过滤器将请求传输到扩展。
3. 扩展收集请求参数并使用定义的协议（如 ajp13）将它们转发到适当的工作程序。
4. 扩展收集来自工作程序的响应并将其返回给浏览器。

这些说明是基于 Windows Server 2012 R2 编写的，并已在所有受支持的 Windows 操作系统（包括 Windows 11 / Windows Server 2022）上进行了测试。

这些安装说明已在干净的、完全修补的操作系统安装上使用 IIS 加上 ISAPI 扩展和过滤器的默认安装进行了测试，Tomcat 9 安装在 C:\Program Files\Apache Software Foundation\Tomcat 9.0 中。在本文档的其余部分中，这称为 ${tomcat_home}。

1. 创建目录 ${tomcat_home}\isapi
2. 允许 IIS 进程创建 ISAPI 重定向器日志文件。如果要将日志文件写入其他目录，请根据需要修改路径。在命令提示符下输入以下内容

   >icacls "C:\Program Files\Apache Software Foundation\Tomcat 9.0\isapi" /grant "IIS APPPOOL\DefaultAppPool":(OI)(CI)M
   

   在启用了用户帐户控制 (UAC) 的客户端操作系统上，必须使用以管理员身份运行打开命令提示符才能成功完成上述命令。
3. 为您的操作系统下载合适的（32 位或 64 位）isapi_redirect.dll，并将其放置在 ${tomcat_home}\isapi 中
4. 设置 isapi_redirect.dll 的权限。在 Windows Server 2019 上，似乎需要明确设置此 dll 的权限。在命令提示符下输入以下内容

   >icacls "C:\Program Files\Apache Software Foundation\Tomcat 9.0\isapi\isapi_redirect.dll" /grant "Everyone":RX
   

5. 创建 ${tomcat_home}\isapi\isapi_redirect.properties 文件以配置 ISAPI 重定向器。配置也可以通过注册表设置执行 - 参见下文。此文件的内容应为

   extension_uri=/jakarta/isapi_redirect.dll
   log_file=C:\Program Files\Apache Software Foundation\Tomcat 9.0\isapi\isapi_redirect.log
   log_level=info
   worker_file=C:\Program Files\Apache Software Foundation\Tomcat 9.0\isapi\workers.properties
   worker_mount_file=C:\Program Files\Apache Software Foundation\Tomcat 9.0\isapi\uriworkermap.properties
   

   小心，不要让 Windows 向文件添加 .txt 扩展名。
6. 创建 ${tomcat_home}\isapi\workers.properties 文件以配置将请求传递到的 Tomcat 实例。对于本地计算机上的单个 Tomcat 实例，此文件的内容应为

   worker.list=tomcat01
   worker.tomcat01.type=ajp13
   worker.tomcat01.host=localhost
   worker.tomcat01.port=8009
   

7. 创建 ${tomcat_home}\isapi\uriworkermap.properties 文件以配置将哪些请求传递到 Tomcat。要公开示例 Web 应用程序，此文件的内容应为

   /examples/*=tomcat01
   

8. 使用 IIS 管理控制台，向您的 IIS 网站添加一个新的虚拟目录。在全新安装中，这将是 默认网站。虚拟目录的名称必须是 jakarta。它的物理路径应该是您放置 isapi_redirect.dll 的目录。
9. 在管理控制台中选择新创建的虚拟目录，然后双击 处理程序映射。选择（当前已禁用）ISAPI-dll 条目，然后在操作窗格中单击 编辑功能权限。在打开的对话框中，选择 执行，以便选中所有三个权限。单击 确定，ISAPI-dll 现在应处于已启用状态。
10. 再次使用 IIS 管理控制台，将 ISAPI 重定向器添加为网站的筛选器。选择您的网站，然后双击 ISAPI 筛选器。从操作窗格中，单击 添加...。对于筛选器名称，使用 tomcat，可执行文件应为 isapi_redirect.dll 的完整路径。配置完成后，单击 确定。
11. 仍然使用 IIS 管理控制台，将 ISAPI 重定向器配置为允许。选择您的服务器（不是网站），然后双击 ISAPI 和 CGI 限制。从操作窗格中，单击 添加...。选择 isapi_redirect.dll，添加描述（例如 tomcat），然后选择 允许扩展路径执行，然后单击 确定。
12. 重新启动 IIS（停止 + 启动 IIS 服务）。

就这样，您现在应该启动 Tomcat 并要求 IIS 为您提供 /examples 上下文。例如，尝试 https://127.0.0.1/examples/ 并执行一些 Servlet 或 JSP 示例。

如果此操作不成功，请参阅下面的故障排除部分以获取有关纠正此问题的帮助。

如果 IIS 访问日志显示诸如 /jakarta/isapi_redirect.dll 而不是 /examples/servlets 的条目，则可以通过 IIS 管理控制台更正此问题。选择您的服务器（不是网站），然后双击 模块。在 操作 窗格中，单击 查看已排序列表...，选择 IsapiFilterModule 并向上移动它，直到它位于 HttpLoggingModule 之上。

除了使用 isapi_redirector.properties 文件之外，还可以通过注册表配置 ISAPI 重定向器。为此，请按照以下步骤操作

1. 在注册表中，创建一个名为 “HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0” 的新注册表项
2. 添加一个名为 extension_uri 的字符串值，其值为 /jakarta/isapi_redirect.dll
3. 添加一个名为 log_file 的字符串值，其值指向你希望日志文件所在的位置（例如 c:\tomcat\logs\isapi.log）。
4. 添加一个名为 log_level 的字符串值，其值为日志级别（可以是 debug、info、error 或 emerg）。
5. 添加一个名为 worker_file 的字符串值，其值为 workers.properties 文件的完整路径（例如 c:\tomcat\conf\workers.properties）
6. 添加一个名为 worker_mount_file 的字符串值，其值为 uriworkermap.properties 文件的完整路径（例如 c:\tomcat\conf\uriworkermap.properties）

在 64 位环境中，IIS 应用程序池的“启用 32 位应用程序”应设置为“False”。要检查此设置，请在 IIS 管理控制台中选择“应用程序池”，然后右键单击你正在使用的池并选择“设置应用程序池默认值...”。“启用 32 位应用程序”可能位于“常规”部分中。如果此设置未正确配置，则不会调用重定向器，并且 IIS 将返回 HTTP 代码 404。

你必须在 64 位操作系统上使用 64 位版本的 ISAPI 重定向器。如果你尝试使用 32 位版本，你将为每个请求收到 HTTP 代码 500，因为无法将该库加载到 64 位 IIS 中。

示例上下文可用于验证你的安装，但你还需要添加你自己的上下文。添加新上下文需要执行两个操作

1. 将上下文添加到 Tomcat（此处未讨论）。
2. 将上下文添加到 ISAPI 重定向器。

将上下文添加到 ISAPI 重定向器很简单，你只需编辑 uriworkermap.properties 并添加如下所示的一行

/context/*=worker_name

工作器及其名称在 workers.properties 中定义。例如，如果你想添加一个名为“shop”的上下文，由名为“tomcat01”的工作器提供服务，则你应该添加到 uriworkermap.properties 中的行将是

/shop/*=tomcat01

以上应该是 IIS 传递给 Tomcat 任何与 Tomcat 上下文（webapp）相对应的 URI 的任何请求所需的所有内容。

如果您的网站非常繁忙（每秒超过 100 个请求，或超过 100 个同时客户端连接），有时可能希望 IIS 直接提供静态内容（html、gif、jpeg 等），即使这些文件是 Tomcat 提供的上下文的一部分。允许 IIS 直接提供此类文件可以避免将请求通过重定向器传递给 Tomcat 的小开销，并且可以通过仅使用它来处理只有 Tomcat 可以处理的请求（例如，对 JSP 页面和 java servlet 的请求）来释放 Tomcat。

例如，考虑 examples 上下文中的 html 和 gif 文件：您可以使用 IIS 直接提供这些文件；无需从 Tomcat 进程中提供它们。

让 IIS 提供属于 Tomcat 上下文的一部分的静态文件需要以下内容

1. 配置 IIS 以了解 Tomcat 上下文
2. 配置重定向器以保留 IIS 的静态文件

向 IIS 添加 Tomcat 上下文需要添加一个新的 IIS 虚拟目录，该目录涵盖 Tomcat 上下文。例如，添加一个涵盖 c:\tomcat\webapps\examples 目录的 /example IIS 虚拟目录。

配置重定向器有点困难，您需要指定您希望 Tomcat 处理的确切 URL 路径模式（通常只有 JSP 文件和 servlet）。这需要更改 uriworkermap.properties

For the examples context it requires to replace the following line
/examples/*=tomcat01
with the following two lines
/examples/*.jsp=tomcat01
/examples/servlet/*=tomcat01

正如您所见，第二个配置更为明确，它实际上指示重定向器仅重定向对 /examples/servlet/ 下资源的请求和以 .jsp 结尾的 /examples/ 下资源的请求。

您甚至可以更明确地提供如下行

/example/servlets/chat=tomcat01

指示重定向器将 URL 路径与前导字符串 "/example/servlets/chat" 匹配的所有请求重定向到名为 tomcat01 的工作程序。

再次提醒，通过允许 IIS 直接访问 Tomcat 上下文的内容，您可能会绕过 Tomcat 对该内容的保护。因此，如有需要，您应使用相应的 IIS 管理控制台功能在 IIS 级别保护此内容。

特别是，每个 Servlet 应用程序（上下文）都有一个名为 WEB-INF 的特殊目录，其中包含敏感的配置数据和 Java 类，并且应始终对 Web 用户隐藏。使用 IIS 管理控制台可以保护 WEB-INF 目录免遭用户访问，但考虑到这是一个通用要求，并且考虑到很容易忘记在 IIS 级别实施此保护，ISAPI 重定向器插件会自动为您执行此操作，并且会拒绝任何在 URL 路径中包含 WEB-INF 的请求。它还将拒绝任何在 URL 路径中包含 META-INF 的请求。

有时您可能希望使用不同的 Tomcat 进程来处理不同的上下文（例如，在不同的计算机之间分摊负载）。要实现此目标，您需要定义多个工作程序，并将每个上下文分配给其自己的工作程序。

在 workers.properties 文件中定义其他工作程序。此文件包含两类条目

# An entry that lists all the workers defined
worker.list=worker1, worker2
# Entries that define the host and port associated with each of these workers
worker.worker1.host=localhost
worker.worker1.port=8009
worker.worker1.type=ajp13
worker.worker2.host=otherhost
worker.worker2.port=8009
worker.worker2.type=ajp13

上述示例定义了两个工作程序，现在我们可以使用这些工作程序来处理两个不同的上下文，每个上下文都有自己的工作程序

example uriworkermap.properties fragment
/examples/*=worker1
/webpages/*=worker2

正如您所见，examples 上下文由 worker1 处理，而 webpages 上下文由 worker2 处理。

有关在 工作程序操作指南 和 worker.properties 配置参考 中使用和配置工作程序的更多信息。

如果存在，请删除（或移动到其他位置）ISAPI 重定向器日志文件。

启动 IIS 服务和 Tomcat。

检查指定位置是否存在 ISAPI 重定向器日志文件。如果未找到，则表明 ISAPI 重定向器未正确启动。这通常是由不正确的配置设置引起的。

• 仔细检查您的配置是否符合安装说明，特别是 ${tomcat_home}\isapi\isapi_redirect.properties 文件的位置、名称和内容。
• 如果使用基于注册表配置，请检查注册表项的路径、名称和值。注册表名称不区分大小写。
• 检查为日志文件指定目录是否存在，以及文件权限是否已按照安装说明进行配置。

在浏览器中调用 URL https://127.0.0.1/examples/。URL 中的大小写很重要。URL 中“localhost”后面的字符必须是小写。如果页面无法显示，请停止 IIS 服务（查看 IIS 日志文件需要）。然后检查 C:\inetpub\logs\LogFiles\W3SVC1 中找到的 IIS 日志文件中的最后一行

如果最后一行包含

GET "/examples/ HTTP/1.1" 404

如果最后一行包含类似内容

GET "/jakarta/isapi_redirect.dll HTTP1.1"

检查以下内容

• 仔细检查您的配置是否符合安装说明，特别是虚拟目录的名称以及 ${tomcat_home}\isapi\uriworkermap.properties 和 ${tomcat_home}\isapi\workers.properties 文件的位置、名称和内容。
如果这些设置正确，ISAPI 重定向器应该识别出它应该处理 "/examples" 上下文的请求。

如果浏览器显示 503 错误页面，则 ISAPI 重定向器识别出它应该处理请求，但未从 Tomcat 及时收到响应。检查以下内容

• 根据安装说明仔细检查配置，特别是位置、名称和 ${tomcat_home}\isapi\workers.properties 文件。
• 检查 Tomcta 中的 AJP 连接器配置是否与 ${tomcat_home}\isapi\workers.properties 文件中的配置相匹配。

如果浏览器显示 500 错误页面，则在尝试提供请求时，IIS 或 ISAPI 重定向器中发生了内部错误。页面顶部应该有错误的文本描述，页面末尾应该有 8 位十六进制错误代码。最后四位数字应该是与问题关联的标准 Windows 错误代码。

500 错误的常见原因是 Windows 创建了具有隐藏的 ".txt" 文件扩展名的配置文件，这些文件不会显示在 Windows 资源管理器中。即使其他文件显示了文件扩展名，也请仔细检查以确保 Windows 资源管理器配置为显示所有文件的文件扩展名。

如果错误消息是 在 ISAPI 筛选器 "...isapi_redirect.dll" 上调用 GetFilterVersion 失败，并且代码是 0x8007047e，则该代码转换为错误代码 0x047e 或 1150，即“指定程序需要较新版本的 Windows”。这些内容共同表明 ISAPI 重定向器的初始化失败，因为无法读取配置 - 无论是从 ${tomcat_home}\isapi\isapi_redirect.properties 还是从注册表中读取。根据需要检查 ${tomcat_home}\isapi\isapi_redirect.properties 文件或注册表项的名称位置和内容。

如果上述设置正确，index.html 页面应显示在浏览器中。您还应该能够单击链接来执行一些 Servlet 或 JSP 示例。