主机容器
目录
简介
Host 元素表示一个虚拟主机，它是服务器的网络名称（例如“www.mycompany.com”）与 Tomcat 正在运行的特定服务器的关联。为了让客户端能够使用其网络名称连接到 Tomcat 服务器，此名称必须注册在管理您所属 Internet 域的域名服务（DNS）服务器中——请联系您的网络管理员以获取更多信息。
在许多情况下，系统管理员希望将多个网络名称（例如 www.mycompany.com 和 company.com）与同一个虚拟主机和应用程序关联。这可以使用下面讨论的主机名称别名功能来完成。
一个或多个 Host 元素嵌套在 Engine 元素内。在 Host 元素内，您可以嵌套 Context 元素，用于与此虚拟主机关联的 Web 应用程序。与每个引擎关联的主机中，恰好一个主机必须具有与该引擎的 defaultHost 属性匹配的名称。
客户端通常使用主机名来标识他们希望连接到的服务器。此主机名也包含在 HTTP 请求头中。Tomcat 从 HTTP 头中提取主机名，并查找具有匹配名称的 Host。如果找不到匹配项，则请求将路由到默认主机。默认主机的名称不必与 DNS 名称匹配（尽管可以匹配），因为任何 DNS 名称与 Host 元素的名称不匹配的请求都将路由到默认主机。
以下描述使用变量名称 $CATALINA_BASE 来引用大多数相对路径所解析的基础目录。如果您尚未通过设置 CATALINA_BASE 目录来为多个实例配置 Tomcat，则 $CATALINA_BASE 将被设置为 $CATALINA_HOME 的值，即您已将 Tomcat 安装到的目录。
属性
通用属性
Host 的所有实现都支持以下属性
| 属性 | 说明 |
|---|---|
appBase |
此虚拟主机的应用程序基础目录。这是可能包含要在此虚拟主机上部署的 Web 应用程序的目录的路径名。您可以指定绝对路径名，或相对于 |
xmlBase |
此虚拟主机的XML 基础目录。这是可能包含要在此虚拟主机上部署的上下文 XML 描述符的目录的路径名。您可以为此目录指定绝对路径名，或相对于 |
createDirs |
如果设置为 |
autoDeploy |
此标志值指示 Tomcat 在运行时是否应定期检查新的或更新的 Web 应用程序。如果为 |
backgroundProcessorDelay |
此值表示此主机及其子容器（包括所有上下文）上 backgroundProcess 方法调用之间的延迟（以秒为单位）。如果子容器的延迟值不是负值（这意味着它们使用自己的处理线程），则不会调用子容器。将此值设置为正值将导致生成一个线程。在等待指定的时间后，该线程将在该主机及其所有子容器上调用 backgroundProcess 方法。主机将使用后台处理来执行与实时 Web 应用程序部署相关的任务。如果未指定，此属性的默认值为 -1，这意味着主机将依赖其父引擎的后台处理设置。 |
className |
要使用的实现的 Java 类名称。此类必须实现 |
deployIgnore |
当设置 此正则表达式相对于 有关更多信息，请参见自动应用程序部署。 |
deployOnStartup |
此标志值指示当 Tomcat 启动时是否应自动部署此主机的 Web 应用程序。默认值为 |
failCtxIfServletStartFails |
设置为 每个子上下文都可以覆盖此属性。 如果未指定，将使用默认值 |
legacyAppBase |
此虚拟主机的旧版应用程序基础目录。这是可能包含要部署前转换为 Jakarta EE 的 Java EE Web 应用程序的目录的路径名。打包为 WAR 文件或放置在此目录中的目录的 Java EE 应用程序将使用 Apache Tomcart Jakarta EE 迁移工具转换为 Jakarta EE。转换将使用默认设置执行。生成的 WAR 或目录将放置在此虚拟主机配置的 如果默认设置不适用于应用程序的迁移，可以通过手动执行迁移来访问全部迁移选项。为此目的， 您可以指定绝对路径名或相对于 |
名称 |
通常是此虚拟主机的网络名称，在您的域名服务服务器中注册。无论用于指定主机名的形式如何，Tomcat 都将内部将其转换为小写。嵌套在 引擎 中的一个主机必须具有与该引擎的 |
startStopThreads |
此主机将使用的线程数，以并行启动子 上下文 元素。如果使用自动部署，将使用相同的线程池部署新的 上下文。由于线程池在服务器级别共享，因此如果多个主机指定此设置，则仅应用最大值，并将其用于除特殊值 1 之外的所有值。如果未指定，将使用默认值 1。如果使用 1 个线程，则将使用当前线程，而不是使用 |
undeployOldVersions |
此标志确定 Tomcat 是否作为自动部署过程的一部分，将检查使用并行部署部署的 Web 应用程序的旧的、未使用的版本，并在发现任何版本时将其删除。此标志仅在 |
标准实现
Host 的标准实现是 org.apache.catalina.core.StandardHost。它支持以下附加属性（除了上面列出的常见属性之外）
| 属性 | 说明 |
|---|---|
copyXML |
如果希望将嵌入在应用程序中的上下文 XML 描述符（位于 |
deployXML |
如果要禁用解析嵌入在应用程序中的上下文 XML 描述符（位于 |
errorReportValveClass |
此主机将使用的错误报告阀的 Java 类名。此阀的职责是输出错误报告。设置此属性允许自定义 Tomcat 将生成的错误页面的外观。此类必须实现 |
unpackWARs |
如果希望将放置在 注意：如果 Tomcat 扩展 WAR 文件，它将在解压后的目录结构中添加一个文件（ 注意：将此选项设置为 |
workDir |
此主机上应用程序要使用的临时目录的路径名。每个应用程序都有自己的子目录，可临时读写。配置 Context workDir 将覆盖 Host workDir 配置的使用。此目录将通过名为 |
嵌套组件
您可以在此 Host 元素中嵌套一个或多个 Context 元素，每个元素都代表与此虚拟主机关联的不同 Web 应用程序。
您最多可以嵌套一个以下实用组件的实例，方法是在 Host 元素中嵌套一个相应元素
特殊功能
日志记录
主机与 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。
自动应用程序部署
如果您使用的是具有默认设置的标准主机实现，则在 Tomcat 启动时，appBase 中的应用程序或在 configBase 中具有上下文文件的应用程序将自动部署（deployOnStartup 属性默认为 true），并在 Tomcat 运行时检测到更改时重新加载或重新部署（视情况而定）（autoDeploy 属性也默认为 true）。
deployOnStartup 和 autoDeploy 触发执行完全相同的代码，因此行为非常相似。但是，有一个关键区别。当 Tomcat 启动时，它不知道哪些文件是相同的，哪些已被更改，哪些是新的。因此，它将所有文件视为新的。当 Tomcat 正在运行时，它可以区分未更改、已修改和新文件。这导致了 Tomcat 运行时修改的文件和 Tomcat 停止时修改的文件之间的行为差异。
当您使用自动部署时，存在于主机的 appBase 和/或 configBase 中的相关文件（Web 应用程序可能具有 context.xml 文件、WAR 和目录）必须符合预期的 命名约定。简而言之，这意味着同一 Web 应用程序的文件必须共享相同的基本名称。
自动部署过程使用以下搜索顺序识别新的和/或修改的 Web 应用程序
- 在主机的 configBase 中具有 context.xml 文件的 Web 应用程序。
- 在主机的 appBase 中具有 WAR 文件且在扫描 context.xml 文件期间尚未识别的 Web 应用程序。
- 在主机的 appBase 中具有目录且在扫描 context.xml 和/或 WAR 文件期间尚未识别的 Web 应用程序。
当 autoDeploy 为 true 时，自动部署过程将监视已部署的 Web 应用程序的更改。根据具体更改的内容，Web 应用程序将重新部署或重新加载。重新部署涉及创建新的 Web 应用程序，并且如果使用标准会话管理器，则不会保留用户会话。重新加载使用现有的 Web 应用程序，但重新解析 web.xml 并重新加载所有类。如果使用标准会话管理器，则会保留用户会话。
用户可以通过向 context.xml 文件添加 WatchedResources 元素，将自动部署过程监视用于重新加载的文件添加到其中（即，对其中一个文件的任何更改都会触发 Web 应用程序的重新加载）。有关更多详细信息，请参阅 上下文 文档。
在使用自动部署时，由 XML 上下文 文件定义的 docBase 应位于 appBase 目录之外。如果不是这种情况，则可能会遇到部署 Web 应用程序的困难，或者该应用程序可能会被部署两次。可以使用 deployIgnore 属性来避免这种情况。
请注意，如果您在 server.xml 中显式定义上下文，则可能应该关闭自动应用程序部署或仔细指定 deployIgnore。否则，每个 Web 应用程序都将被部署两次，这可能会给应用程序带来问题。
有很多可能的设置组合、新文件、已更改文件和已删除文件。一个单独的页面描述了 自动部署过程在许多此类场景中的预期行为。
主机名称别名
在许多服务器环境中，网络管理员在域名服务(DNS)服务器中配置了多个网络名称，这些网络名称解析为同一服务器的 IP 地址。通常，每个此类网络名称都将配置为 conf/server.xml 中一个单独的主机元素，每个元素都有自己的一组 Web 应用程序。
但是，在某些情况下，需要两个或多个网络名称解析为相同的虚拟主机，运行同一组应用程序。此方案的一个常见用例是公司网站，用户可以使用 www.mycompany.com 或 company.com 访问完全相同的内容和应用程序。
这是通过利用主机元素内部嵌套的一个或多个别名元素来完成的。例如
<Host name="www.mycompany.com" ...>
...
<Alias>mycompany.com</Alias>
...
</Host>为了使此策略有效，所有涉及的网络名称都必须在您的 DNS 服务器中注册，以解析为运行 Catalina 此实例的同一台计算机。
与主机的名称属性不同，别名也可以使用通配符形式 (*.domainname)。
生命周期侦听器
如果您已实现了一个 Java 对象，该对象需要知道此主机何时启动或停止，则可以通过在此元素内部嵌套侦听器元素来声明它。您指定的类名必须实现 org.apache.catalina.LifecycleListener 接口，并且它将收到有关相应生命周期事件发生的通知。此类侦听器的配置如下所示
<Host name="localhost" ...>
...
<Listener className="com.mycompany.mypackage.MyListener" ... >
...
</Host>请注意，侦听器可以具有任意数量的其他属性，可以从该元素配置这些属性。属性名称使用标准属性方法命名模式与相应的 JavaBean 属性名称匹配。
请求过滤器
您可以要求 Catalina 检查针对周围引擎、主机或上下文元素的每个传入请求的 IP 地址或主机名。将根据使用 java.util.regex 正则表达式语法定义的已配置“接受”和/或“拒绝”筛选器检查远程地址或名称。来自未接受位置的请求将被拒绝，并显示 HTTP“禁止”错误。示例筛选器声明
<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 元素嵌套在此 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
您可以覆盖每个虚拟主机的 conf/context.xml 和 conf/web.xml 文件中找到的 $CATALINA_BASE 的默认值。Tomcat 将在 xmlBase 指定的目录中查找名为 context.xml.default 和 web.xml.default 的文件，并将这些文件合并到默认文件中找到的文件中。