SSI 使用方法

目录

简介

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

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

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

SSI 支持以 Servlet 和 Filter 的形式提供。您应该使用其中一个来提供 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 外部的程序。

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

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

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

Servlet 配置

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

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

Filter 配置

有几个 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 当前实现了以下变量：

变量名 描述
AUTH_TYPE 用于此用户的认证类型：BASIC、FORM 等。
CONTENT_LENGTH 从表单传递的数据长度（字节或字符数）。
CONTENT_TYPE 查询数据的 MIME 类型，例如 "text/html"。
DATE_GMT 当前格林威治标准时间日期和时间
DATE_LOCAL 当前本地时区日期和时间
DOCUMENT_NAME 当前文件
DOCUMENT_URI 文件的虚拟路径
GATEWAY_INTERFACE 如果启用，服务器使用的通用网关接口版本：“CGI/1.1”。
HTTP_ACCEPT 客户端可以接受的 MIME 类型列表。
HTTP_ACCEPT_ENCODING 客户端可以接受的压缩类型列表。
HTTP_ACCEPT_LANGUAGE 客户端可以接受的语言列表。
HTTP_CONNECTION 客户端连接的管理方式：“Close”或“Keep-Alive”。
HTTP_HOST 客户端请求的网站。
HTTP_REFERER 客户端链接来源文档的 URL。
HTTP_USER_AGENT 客户端用于发出请求的浏览器。
LAST_MODIFIED 当前文件的最后修改日期和时间
PATH_INFO 传递给 Servlet 的额外路径信息。
PATH_TRANSLATED 变量 PATH_INFO 给出的路径的翻译版本。
QUERY_STRING URL 中“?”后面的查询字符串。
QUERY_STRING_UNESCAPED 未解码的查询字符串，其中所有 shell 元字符都用“\”转义。
REMOTE_ADDR 发出请求的用户的远程 IP 地址。
REMOTE_HOST 发出请求的用户的远程主机名。
REMOTE_PORT 发出请求的用户的远程 IP 地址的端口号。
REMOTE_USER 用户的认证名称。
REQUEST_METHOD 信息请求发出的方法：“GET”、“POST”等。
REQUEST_URI 客户端最初请求的网页。
SCRIPT_FILENAME 当前网页在服务器上的位置。
SCRIPT_NAME 网页名称。
SERVER_ADDR 服务器的 IP 地址。
SERVER_NAME 服务器的主机名或 IP 地址。
SERVER_PORT 服务器接收请求的端口。
SERVER_PROTOCOL 服务器使用的协议。例如：“HTTP/1.1”。
SERVER_SOFTWARE 响应客户端请求的服务器软件的名称和版本。
UNIQUE_ID 如果已建立会话，用于标识当前会话的令牌。