Host 容器

目录

简介

Host 元素表示一个虚拟主机，它是服务器的网络名称（例如“www.mycompany.com”）与运行 Tomcat 的特定服务器的关联。为了使客户端能够使用其网络名称连接到 Tomcat 服务器，此名称必须在管理您所属 Internet 域的域名服务（DNS）服务器中注册——请联系您的网络管理员获取更多信息。

在许多情况下，系统管理员希望将多个网络名称（例如www.mycompany.com和company.com）与相同的虚拟主机和应用程序关联起来。这可以通过下面讨论的主机名别名功能来实现。

一个或多个Host元素嵌套在一个Engine元素内部。在Host元素内部，您可以嵌套此虚拟主机关联的 Web 应用程序的Context元素。每个Engine关联的Host中，必须有一个Host的名称与该Engine的defaultHost属性匹配。

客户端通常使用主机名来标识他们希望连接的服务器。此主机名也包含在 HTTP 请求头中。Tomcat 从 HTTP 头中提取主机名，并查找名称匹配的Host。如果未找到匹配项，请求将被路由到默认主机。默认主机的名称不必与 DNS 名称匹配（尽管可以），因为任何 DNS 名称与Host元素名称不匹配的请求都将被路由到默认主机。

以下描述使用变量名 $CATALINA_BASE 来指代大多数相对路径所解析的基目录。如果您尚未通过设置 CATALINA_BASE 目录来为 Tomcat 配置多个实例，则 $CATALINA_BASE 将设置为 $CATALINA_HOME 的值，即您安装 Tomcat 的目录。

属性

通用属性

所有 Host 实现都支持以下属性

属性描述
appBase

此虚拟主机的应用程序基目录。这是一个目录的路径名，其中可能包含要部署在此虚拟主机上的 Web 应用程序。您可以指定绝对路径名，或相对于$CATALINA_BASE目录的路径名。有关 Web 应用程序的自动识别和部署的更多信息，请参阅自动应用部署。如果未指定，将使用默认值webapps。

xmlBase

此虚拟主机的XML 基目录。这是一个目录的路径名，其中可能包含要部署在此虚拟主机上的上下文 XML 描述符。您可以为此目录指定绝对路径名，或相对于$CATALINA_BASE目录的路径名。有关 Web 应用程序的自动识别和部署的更多信息，请参阅自动应用部署。如果未指定，将使用默认值conf/<engine_name>/<host_name>。

createDirs

如果设置为true，Tomcat 将在启动阶段尝试创建由appBase和xmlBase属性定义的目录。默认值为true。如果设置为true且目录创建失败，将打印错误消息但不会停止启动序列。

autoDeploy

此标志值指示 Tomcat 是否应在运行时定期检查新的或更新的 Web 应用程序。如果为true，Tomcat 会定期检查appBase和xmlBase目录，并部署找到的任何新 Web 应用程序或上下文 XML 描述符。更新的 Web 应用程序或上下文 XML 描述符将触发 Web 应用程序的重新加载。默认值为true。有关更多信息，请参阅自动应用部署。

backgroundProcessorDelay

此值表示此主机及其子容器（包括所有上下文）调用 backgroundProcess 方法之间的延迟（以秒为单位）。如果子容器的延迟值不为负（这意味着它们正在使用自己的处理线程），则不会调用它们。将其设置为正值将导致生成一个线程。在等待指定的时间后，该线程将在此主机及其所有子容器上调用 backgroundProcess 方法。主机将使用后台处理来执行实时 Web 应用程序部署相关的任务。如果未指定，此属性的默认值为 -1，这意味着主机将依赖于其父引擎的后台处理设置。

className

要使用的实现的 Java 类名。此类必须实现org.apache.catalina.Host接口。如果未指定，将使用标准值（定义如下）。

deployIgnore

一个正则表达式，定义当autoDeploy和deployOnStartup设置为 true 时要忽略的路径。这允许您将配置保存在版本控制系统中（例如），并且不部署.svn、.git或其他可能位于appBase中的配置控制系统文件夹。

此正则表达式是相对于appBase的。它也是锚定的，这意味着匹配是针对整个文件/目录名执行的。因此，foo只匹配名为foo的文件或目录，而不匹配foo.war、foobar或myfooapp。要匹配任何包含“foo”的内容，可以使用.*foo.*。

有关更多信息，请参阅自动应用部署。

deployOnStartup

此标志值指示 Tomcat 启动时是否应自动部署此主机中的 Web 应用程序。默认值为true。有关更多信息，请参阅自动应用部署。

failCtxIfServletStartFails

设置为true以使任何 load-on-startup >=0 的子 servlet 启动失败时，其相应的子上下文启动也失败。

每个子上下文都可以覆盖此属性。

如果未指定，则使用默认值false。

legacyAppBase

此虚拟主机的旧版应用程序基目录。这是一个目录的路径名，其中可能包含要在部署前转换为 Jakarta EE 的 Java EE Web 应用程序。作为 WAR 文件或放置在此目录中的目录打包的 Java EE 应用程序将使用 Apache Tomcat Migration Tool for Jakarta EE 转换为 Jakarta EE。转换将使用默认设置执行。生成的 WAR 或目录将放置在此虚拟主机配置的appBase中。

如果默认设置不适用于应用程序的迁移，可以通过手动执行迁移来访问完整的迁移选项。为此，migrate.[sh|bat]脚本位于$CATALINA_HOME/bin目录中。

您可以指定绝对路径名，或相对于$CATALINA_BASE目录的路径名。如果未指定，将使用默认值webapps-javaee。

name

通常是此虚拟主机的网络名称，如在您的域名服务服务器中注册的那样。无论用于指定主机名的大小写如何，Tomcat 都会在内部将其转换为小写。嵌套在Engine中的 Hosts 之一的名称必须与该 Engine 的defaultHost设置匹配。有关如何将多个网络名称分配给同一虚拟主机的信息，请参阅主机名别名。名称不能包含通配符，通配符仅在 Alias 中有效。

startStopThreads

此Host将用于并行启动子Context元素的线程数。如果使用自动部署，将使用相同的线程池部署新的Context。由于线程池在 Server 级别共享，如果多个 Host 指定此设置，则只有最大值会生效，并用于除特殊值 1 之外的所有情况。如果未指定，将使用默认值 1。如果使用 1 个线程，则将使用当前线程而不是ExecutorService。

undeployOldVersions

此标志决定 Tomcat 作为自动部署过程的一部分，是否会检查使用并行部署的旧的、未使用的 Web 应用程序版本，如果发现任何此类版本，则将其删除。此标志仅在autoDeploy为true时适用。如果未指定，将使用默认值false。

标准实现

Host 的标准实现是 org.apache.catalina.core.StandardHost。它支持以下附加属性（除了上面列出的通用属性）

属性描述
copyXML

如果希望将嵌入在应用程序中（位于/META-INF/context.xml）的上下文 XML 描述符在应用程序部署时复制到xmlBase，请将其设置为true。在后续启动时，复制的上下文 XML 描述符将优先于嵌入在应用程序中的任何上下文 XML 描述符，即使嵌入在应用程序中的描述符是更新的。默认值为false。请注意，如果deployXML为false，此属性将不起作用。

deployXML

如果您想禁用解析嵌入在应用程序中（位于/META-INF/context.xml）的上下文 XML 描述符，请将其设置为false。有安全意识的环境应将其设置为false，以防止应用程序与容器的配置进行交互。管理员将负责提供外部上下文配置文件，并将其放置在由xmlBase属性定义的位置。如果此标志为false，且描述符位于/META-INF/context.xml，并且xmlBase中不存在描述符，那么如果描述符包含安全部署所需的配置（例如 RemoteAddrValve），并且不应被忽略，则上下文将无法启动。默认值为true。

errorReportValveClass

此 Host 将使用的错误报告 Valve 的 Java 类名。此 Valve 的职责是输出错误报告。设置此属性允许自定义 Tomcat 将生成的错误页面的外观。此类必须实现org.apache.catalina.Valve接口。如果未指定，默认将使用org.apache.catalina.valves.ErrorReportValve。如果设置为空字符串，则错误报告将被禁用。

unpackWARs

如果希望将放置在appBase目录中的 Web 应用程序归档（WAR）文件解压为相应的磁盘目录结构，请将其设置为true；设置为false则直接从 WAR 文件运行此类 Web 应用程序。默认值为true。有关更多信息，请参阅自动应用部署。

注意：如果 Tomcat 展开 WAR 文件，它将在解压的目录结构中添加一个文件（/META-INF/war-tracking），Tomcat 使用该文件来检测 Tomcat 未运行时 WAR 文件中的更改。任何此类更改都将触发在 Tomcat 下次启动时删除展开的目录并部署更新的 WAR 文件。

注意：将此选项设置为false运行将导致性能损失。为避免显著的性能损失，应将 Web 应用程序配置为不需要对 Servlet 3.0+ 可插拔功能进行类扫描。用户可能还希望考虑ExtractingRoot Resources 实现。

workDir

此 Host 应用程序将使用的临时目录路径名。每个应用程序将拥有自己的子目录，用于临时读写。配置 Context 的 workDir 将覆盖 Host 的 workDir 配置。根据 Servlet 规范的描述，此目录将通过名为jakarta.servlet.context.tempdir的 servlet 上下文属性（类型为java.io.File）对 Web 应用程序中的 servlets 可见。如果未指定，将提供$CATALINA_BASE/work下的一个合适目录。

嵌套组件

您可以将一个或多个Context元素嵌套在此Host元素内部，每个元素代表一个与此虚拟主机关联的不同 Web 应用程序。

您可以通过在此Host元素内部嵌套相应的元素来嵌套最多一个以下实用程序组件实例

  • Realm - 配置一个 Realm，该 Realm 将允许其用户数据库及其关联的角色在嵌套在此 Host 内部的所有Contexts之间共享（除非被较低级别的Realm配置覆盖）。

特殊功能

日志记录

一个主机与org.apache.catalina.core.ContainerBase.[engine_name].[host_name]日志类别关联。请注意，方括号是名称的一部分，不要省略它们。

访问日志

当您运行 Web 服务器时，通常生成的一个输出文件是访问日志，它以标准格式为服务器处理的每个请求生成一行信息。Catalina 包含一个可选的Valve实现，该实现可以以 Web 服务器创建的相同标准格式或任何数量的自定义格式创建访问日志。

您可以通过嵌套一个如下所示的Valve元素，要求 Catalina 为由Engine、Host或Context处理的所有请求创建访问日志

<Host name="localhost" ...>
  ...
  <Valve className="org.apache.catalina.valves.AccessLogValve"
         prefix="localhost_access_log" suffix=".txt"
         pattern="common"/>
  ...
</Host>

有关支持的配置属性的更多信息，请参阅访问日志 Valve。

自动应用部署

如果您使用具有默认设置的标准Host实现，则当 Tomcat 启动时（deployOnStartup属性默认为true），appBase 中的应用程序或configBase中的上下文文件会自动部署；当 Tomcat 运行时检测到更改时，它们会自动重新加载或重新部署（视情况而定）（autoDeploy属性也默认为true）。

deployOnStartup和autoDeploy触发执行完全相同的代码，因此行为非常相似。但是，有一个关键区别。当 Tomcat 启动时，它不知道哪些文件是相同的、哪些已更改、哪些是新的。因此，它将所有文件都视为新文件。当 Tomcat 运行时，它可以区分未更改、已修改和新文件。这导致在 Tomcat 运行时修改文件与在 Tomcat 停止时修改文件之间存在一些行为差异。

当您使用自动部署时，存在于Host的appBase和/或configBase中的相关文件（一个 Web 应用程序可能有一个 context.xml 文件、一个 WAR 和一个目录）必须符合预期的命名约定。简而言之，这意味着同一个 Web 应用程序的文件必须共享相同的基本名称。

自动部署过程使用以下搜索顺序识别新的和/或修改的 Web 应用程序

  1. 在 Host 的configBase中找到 context.xml 文件的 Web 应用程序。
  2. 在 Host 的appBase中找到 WAR 文件，且在扫描 context.xml 文件期间尚未被识别的 Web 应用程序。
  3. 在 Host 的appBase中找到目录，且在扫描 context.xml 和/或 WAR 文件期间尚未被识别的 Web 应用程序。

当autoDeploy为true时，自动部署过程将监控已部署的 Web 应用程序的更改。根据具体更改内容，Web 应用程序将进行重新部署或重新加载。重新部署涉及创建新的 Web 应用程序，如果使用标准会话管理器，用户会话将不会保留。重新加载使用现有 Web 应用程序，但会重新解析 web.xml 并重新加载任何类。如果使用标准会话管理器，用户会话将持久化。

用户可以通过向 context.xml 文件添加WatchedResources元素，来将文件添加到自动部署过程监控以进行重新加载的文件列表中（即，这些文件中的任何更改都会触发 Web 应用程序的重新加载）。有关更多详细信息，请参阅Context文档。

使用自动部署时，XML Context 文件定义的docBase应位于appBase目录之外。如果不是这种情况，可能会遇到部署 Web 应用程序的困难，或者应用程序可能会部署两次。可以使用deployIgnore属性来避免这种情况。

请注意，如果您在 server.xml 中显式定义了上下文，则可能应该关闭自动应用程序部署或仔细指定deployIgnore。否则，Web 应用程序将各被部署两次，这可能会给应用程序带来问题。

存在许多可能的设置组合、新文件、更改文件和删除文件。一个单独的页面描述了在许多这些场景中自动部署过程的预期行为。

主机名别名

在许多服务器环境中，网络管理员配置了多个网络名称（在域名服务 (DNS) 服务器中），它们都解析到同一服务器的 IP 地址。通常，每个此类网络名称都将作为conf/server.xml中的一个单独的Host元素进行配置，每个元素都拥有自己的一组 Web 应用程序。

然而，在某些情况下，希望两个或更多网络名称解析到同一个虚拟主机，运行相同的应用程序集。这种情况的一个常见用例是企业网站，用户希望能够使用www.mycompany.com或company.com访问完全相同的内容和应用程序。

这可以通过在您的Host元素内部嵌套一个或多个Alias元素来实现。例如

<Host name="www.mycompany.com" ...>
  ...
  <Alias>mycompany.com</Alias>
  ...
</Host>

为了使此策略有效，所有涉及的网络名称必须在您的 DNS 服务器中注册，以解析到运行此 Catalina 实例的同一台计算机。

与Host的name属性不同，Alias 也可以使用通配符形式（*.domainname）。

生命周期监听器

如果您实现了需要在Host启动或停止时知晓的 Java 对象，可以通过在此元素内部嵌套一个Listener元素来声明它。您指定的类名必须实现org.apache.catalina.LifecycleListener接口，它将收到相应生命周期事件的通知。此类监听器的配置如下所示

<Host name="localhost" ...>
  ...
  <Listener className="com.mycompany.mypackage.MyListener" ... >
  ...
</Host>

请注意，一个 Listener 可以有任意数量的附加属性，这些属性可以从此元素中配置。属性名称使用标准属性方法命名模式与相应的 JavaBean 属性名称匹配。

请求过滤器

您可以要求 Catalina 检查每个传入请求的 IP 地址或主机名，这些请求指向其周围的Engine、Host或Context元素。远程地址或名称将根据配置的“accept”和/或“deny”过滤器进行检查，这些过滤器使用java.util.regex正则表达式语法定义。来自未接受位置的请求将被拒绝，并返回 HTTP“Forbidden”错误。示例过滤器声明

<Host name="localhost" ...>
  ...
  <Valve className="org.apache.catalina.valves.RemoteHostValve"
         allow=".*\.mycompany\.com|www\.yourcompany\.com"/>
  <Valve className="org.apache.catalina.valves.RemoteAddrValve"
         deny="192\.168\.1\.\d+"/>
  ...
</Host>

有关支持的配置选项的更多信息，请参阅远程地址过滤器和远程主机过滤器。

单点登录

在许多环境中，特别是在门户环境中，希望用户只需在特定虚拟主机上部署的一组 Web 应用程序中进行一次身份验证。这可以通过在虚拟主机的 Host 元素内部嵌套一个类似这样的元素来实现

<Host name="localhost" ...>
  ...
  <Valve className="org.apache.catalina.authenticator.SingleSignOn"/>
  ...
</Host>

单点登录功能根据以下规则运行

  • 为该虚拟主机配置的所有 Web 应用程序必须共享同一个Realm。实际上，这意味着您可以将 Realm 元素嵌套在此 Host 元素（或其外部的Engine元素）内部，但不能嵌套在其中一个相关 Web 应用程序的Context元素内部。
  • 只要用户只访问此虚拟主机上任何 Web 应用程序中的非受保护资源，他们就不会被要求进行身份验证。
  • 一旦用户访问与此虚拟主机关联的任何Web 应用程序中的受保护资源，用户将被要求使用当前正在访问的 Web 应用程序定义的登录方法进行身份验证。
  • 一旦通过身份验证，与此用户关联的角色将用于所有相关 Web 应用程序的访问控制决策，而无需用户单独对每个应用程序进行身份验证。
  • 一旦用户从一个 Web 应用程序注销（例如，如果使用基于表单的登录，通过使相应会话失效），用户在所有Web 应用程序中的会话都将失效。任何后续尝试访问任何应用程序中的受保护资源都将要求用户重新进行身份验证。
  • 单点登录功能使用 HTTP cookie 传输一个令牌，该令牌将每个请求与保存的用户身份关联起来，因此它只能在支持 cookie 的客户端环境中使用。

用户 Web 应用程序

许多 Web 服务器可以自动将以波浪号字符（“~”）和用户名开头的请求 URI 映射到该用户主目录中的目录（通常命名为public_html）。您可以通过在 Catalina 中使用一个特殊的Listener元素来实现相同的功能，如下所示（在使用/etc/passwd文件识别有效用户的 Unix 系统上）

<Host name="localhost" ...>
  ...
  <Listener className="org.apache.catalina.startup.UserConfig"
            directoryName="public_html"
            userClass="org.apache.catalina.startup.PasswdUserDatabase"/>
  ...
</Host>

在不使用/etc/passwd的服务器上，您可以要求 Catalina 将指定基本目录中找到的所有目录（例如本例中的c:\Homes）视为“用户主”目录，以实现此指令的目的

<Host name="localhost" ...>
  ...
  <Listener className="org.apache.catalina.startup.UserConfig"
            directoryName="public_html"
            homeBase="c:\Homes"
            userClass="org.apache.catalina.startup.HomesUserDatabase"/>
  ...
</Host>

如果已为名为craigmcc的用户设置了用户主目录，则其内容将通过向类似以下 URL 发出请求而对客户端浏览器可见

http://www.mycompany.com:8080/~craigmcc

成功使用此功能需要考虑以下事项

  • 每个用户 Web 应用程序将以全局和主机级别默认上下文设置建立的特征进行部署。
  • 包含多个此 Listener 元素实例是合法的。但是，这仅在您想要配置多个“homeBase”目录的情况下才有用。
  • 执行 Catalina 的操作系统用户名必须对每个用户 Web 应用程序目录及其所有内容具有读取权限。

自定义 context.xml 和 web.xml

您可以覆盖$CATALINA_BASE中每个虚拟主机的conf/context.xml和conf/web.xml文件中的默认值。Tomcat 将在xmlBase指定的目录中查找名为context.xml.default和web.xml.default的文件，并将这些文件合并到默认文件中找到的文件中。