Apache Tomcat 10

• 简介
• 安装
• Servlet 配置
• 过滤器配置
• 指令
• 变量

SSI（服务器端包含）是放置在 HTML 页面中的指令，在服务器提供页面时进行评估。它们允许您向现有的 HTML 页面添加动态生成的内容，而无需通过 CGI 程序或其他动态技术提供整个页面。

在 Tomcat 中，当使用 Tomcat 作为您的 HTTP 服务器并且您需要 SSI 支持时，可以添加 SSI 支持。通常，这在开发过程中完成，当您不想运行像 Apache 这样的 Web 服务器时。

Tomcat SSI 支持实现与 Apache 相同的 SSI 指令。有关使用 SSI 指令的信息，请参阅 Apache SSI 简介。

SSI 支持以 Servlet 和过滤器两种形式提供。您应该使用其中一种来提供 SSI 支持，而不是同时使用两者。

基于 Servlet 的 SSI 支持是通过类 org.apache.catalina.ssi.SSIServlet 实现的。传统上，此 Servlet 映射到 URL 模式 "*.shtml"。

基于 Filter 的 SSI 支持是通过类 org.apache.catalina.ssi.SSIFilter 实现的。传统上，此 Filter 映射到 URL 模式 "*.shtml"，但它也可以映射到 "*"，因为它会根据 MIME 类型选择性地启用/禁用 SSI 处理。contentType 初始化参数允许您将 SSI 处理应用于 JSP 页面、JavaScript 或您希望的任何其他内容。

默认情况下，Tomcat 中禁用 SSI 支持。

注意 - SSI 指令可用于执行 Tomcat JVM 外部的程序。如果您使用的是 Java SecurityManager，这将绕过您在 catalina.policy 中的安全性策略配置。

要使用 SSI Servlet，请从 $CATALINA_BASE/conf/web.xml 中的 SSI Servlet 和 Servlet 映射配置周围的 XML 注释中删除注释。

要使用 SSI Filter，请从 $CATALINA_BASE/conf/web.xml 中的 SSI Filter 和 Filter 映射配置周围的 XML 注释中删除注释。

只有标记为特权的上下文才能使用 SSI 功能（请参阅 Context 元素的特权属性）。

有几个 Servlet 初始化参数可用于配置 SSI Servlet 的行为。

• buffered - 此 Servlet 的输出是否应被缓冲？(0=false, 1=true) 默认值为 0 (false)。
• debug - 此 Servlet 记录的消息的调试详细级别。默认值为 0。
• expires - 包含 SSI 指令的页面过期前的秒数。默认行为是针对每个请求评估所有 SSI 指令。
• isVirtualWebappRelative - "虚拟" SSI 指令路径是否应解释为相对于上下文根目录，而不是服务器根目录？默认值为 false。
• inputEncoding - 如果无法从资源本身确定，则应假定用于 SSI 资源的编码。默认值为默认平台编码。
• outputEncoding - 用于 SSI 处理结果的编码。默认值为 UTF-8。
• allowExec - exec 命令是否已启用？默认值为 false。

有几个 Filter 初始化参数可用于配置 SSI Filter 的行为。

• contentType - 在应用 SSI 处理之前必须匹配的正则表达式模式。在创建自己的模式时，请不要忘记 MIME 内容类型后面可能跟有可选的字符集，形式为 "mime/type; charset=set"，您必须考虑这一点。默认值为 "text/x-server-parsed-html(;.*)?"。
• debug - 此 Servlet 记录的消息的调试详细级别。默认值为 0。
• expires - 包含 SSI 指令的页面过期前的秒数。默认行为是针对每个请求评估所有 SSI 指令。
• isVirtualWebappRelative - "虚拟" SSI 指令路径是否应解释为相对于上下文根目录，而不是服务器根目录？默认值为 false。
• allowExec - exec 命令是否已启用？默认值为 false。

服务器端包含是通过在 HTML 文档中嵌入 SSI 指令来调用的，该文档的类型将由 SSI Servlet 处理。指令采用 HTML 注释的形式。在将页面发送到客户端之前，指令将被解释结果替换。指令的一般形式为

<!--#directive [param=value] -->

这些指令是

• config - <!--#config errmsg="Error occurred" sizefmt="abbrev" timefmt="%B %Y" --> 用于设置 SSI 错误消息，以及 SSI 处理日期和文件大小的格式。
  所有选项都是可选的，但至少要使用一个。可用的选项如下：
  errmsg - 用于 SSI 错误的错误消息
  sizefmt - 在 fsize 指令中用于大小的格式
  timefmt - 在 flastmod 指令中用于时间戳的格式
  
• echo - <!--#echo var="VARIABLE_NAME" encoding="entity" --> 将被变量的值替换。
  可选的 encoding 参数指定要使用的编码类型。有效值为 entity（默认）、url 或 none。注意：使用除 entity 以外的编码可能会导致安全问题。
• exec - <!--#exec cmd="file-name" --> 用于在主机系统上运行命令。
• exec - <!--#exec cgi="file-name" --> 这与 include virtual 指令的作用相同，实际上不会执行任何命令。
• include - <!--#include file="file-name" --> 插入内容。路径相对于使用此指令的文档进行解释，并且不是相对于上下文根目录或服务器根目录的“虚拟”路径。
• include - <!--#include virtual="file-name" --> 插入内容。路径被解释为“虚拟”路径，它相对于上下文根目录或服务器根目录（取决于 isVirtualWebappRelative 参数）。
• flastmod - <!--#flastmod file="filename.shtml" --> 返回文件最后修改的时间。路径相对于使用此指令的文档进行解释，并且不是相对于上下文根目录或服务器根目录的“虚拟”路径。
• flastmod - <!--#flastmod virtual="filename.shtml" --> 返回文件最后修改的时间。路径被解释为“虚拟”路径，它相对于上下文根目录或服务器根目录（取决于 isVirtualWebappRelative 参数）。
• fsize - <!--#fsize file="filename.shtml" --> 返回文件的大小。路径相对于使用此指令的文档进行解释，并且不是相对于上下文根目录或服务器根目录的“虚拟”路径。
• fsize - <!--#fsize virtual="filename.shtml" --> 返回文件的大小。路径被解释为“虚拟”路径，它相对于上下文根目录或服务器根目录（取决于 isVirtualWebappRelative 参数）。
• printenv - <!--#printenv --> 返回所有已定义变量的列表。
• set - <!--#set var="foo" value="Bar" --> 用于将值分配给用户定义的变量。
• if elif endif else - 用于创建条件部分。例如

  <!--#config timefmt="%A" -->
  <!--#if expr="$DATE_LOCAL = /Monday/" -->
  <p>Meeting at 10:00 on Mondays</p>
  <!--#elif expr="$DATE_LOCAL = /Friday/" -->
  <p>Turn in your time card</p>
  <!--#else -->
  <p>Yoga class at noon.</p>
  <!--#endif -->

有关使用 SSI 指令的更多信息，请参阅 Apache SSI 简介。

SSI 变量通过 jakarta.servlet.ServletRequest 对象上的请求属性实现，并不限于 SSI servlet。以“java.”、“javax.”、“sun” 或“org.apache.catalina.ssi.SSIMediator.” 开头的变量是保留的，不能使用。

SSI servlet 目前实现以下变量