web server apache tomcat11-13-SSI How To

前言

整理这个官方翻译的系列，原因是网上大部分的 tomcat 版本比较旧，此版本为 v11 最新的版本。

开源项目

从零手写实现 tomcat minicat 别称【嗅虎】心有猛虎，轻嗅蔷薇。

系列文章

web server apache tomcat11-01-官方文档入门介绍

web server apache tomcat11-02-setup 启动

web server apache tomcat11-03-deploy 如何部署

web server apache tomcat11-04-manager 如何管理？

web server apache tomcat11-06-Host Manager App -- Text Interface

web server apache tomcat11-07-Realm Configuration

web server apache tomcat11-08-JNDI Resources

web server apache tomcat11-09-JNDI Datasource

web server apache tomcat11-10-Class Loader

...

SSI

Server Side Includes (SSI) 是一种在 HTML 页面中放置的指令，在服务器上评估页面时执行。

它们允许您向现有的 HTML 页面添加动态生成的内容，而无需通过 CGI 程序或其他动态技术提供整个页面。

在 Tomcat 中，当您将 Tomcat 用作 HTTP 服务器并且需要 SSI 支持时，可以添加 SSI 支持。通常在开发期间进行这样的操作，当您不想运行诸如 Apache 等网络服务器时。

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

SSI 支持可作为 servlet 和过滤器提供。您应该使用其中一种来提供 SSI 支持，但不要同时使用两者。

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

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

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

安装

注意 - SSI 指令可用于执行Tomcat JVM 外部的程序。

要使用 SSI servlet，请从 $CATALINA_BASE/conf/web.xml 中删除围绕 SSI servlet 和 servlet-mapping 配置的 XML 注释。

要使用 SSI 过滤器，请从 $CATALINA_BASE/conf/web.xml 中删除围绕 SSI 过滤器和 filter-mapping 配置的 XML 注释。

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

Servlet 配置

有几个 servlet init 参数可用于配置 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。

过滤器配置

有几个过滤器 init 参数可用于配置 SSI 过滤器的行为。

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

指令

通过将 SSI 指令嵌入到由 SSI servlet 处理的 HTML 文档中来调用 Server Side Includes。指令采用 HTML 注释的形式。将指令替换为在将页面发送到客户端之前解释它的结果。指令的一般形式为：

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

指令包括：

config - 用于设置 SSI 错误消息、由 SSI 处理的文件大小和日期格式的 SSI 错误消息。
echo - 将被变量的值替换。
exec - 用于在主机系统上运行命令。
include - 插入内容。
flastmod - 返回文件上次修改的时间。
fsize - 返回文件大小。
printenv - 返回所有已定义变量的列表。
set - 用于将值赋给用户定义的变量。
if、elif、endif、else - 用于创建条件部分。

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

变量

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

SSI servlet 当前实现了以下变量：

（变量名 - 描述）