SSI（服务器端嵌入）

简介

SSI（服务器端嵌入）是一组放在 HTML 页面中的指令，当服务器向客户端访问提供这些页面时，会解释执行这些指令。它们能为已有的 HTML 页面添加动态生成内容，不需要通过 CGI 程序来或其他的动态技术来重新改变整个页面。

如果利用 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 之外的程序。如果使用 Java SecurityManager，它会绕过你在 catalina.policy 中配置的安全策略。

为了使用 SSI servlet，要从 $CATALINA_BASE/conf/web.xml 中去除 SSI servlet 及 servlet 映射配置旁边的 XML 注释。

为了使用 SSI 过滤器，要从 $CATALINA_BASE/conf/web.xml 中去除 SSI 过滤器及过滤器映射配置旁边的 XML 注释。

只有标明为 privileged 的上下文才可以使用 SSI 功能（参看 Context 元素的 privileged 属性）。

Servlet 配置

以下这些 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。

过滤器配置

以下这些过滤器初始化参数可以配置 SSI 过滤器的行为：

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 注释的形式。在将页面发送到客户端之前，解读指令，并用所得结果来替换指令。指令的一般形式为：

这些指令包括：

config  用于设定日期格式以及其他一些 SSI 处理的项目。
echo  将被变量值所取代。
exec 在主机系统上用于运行命令。
include  插入内容。
flastmod  返回文件最后修改的时间。
fsize  返回文件大小。
printenv  返回所有定义变量的列表。
set  为用户自定义变量赋值。
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 servlet 当前能实现下列变量：

变量名	描述
AUTH_TYPE	用于这些用户的验证类型：BASIC、FORM，等等。
CONTENT_LENGTH	从表单传入数据的长度（以字节或字符数）
CONTENT_TYPE	查询数据的 MIME 类型。比如：text/html
DATE_GMT	以格林威治标准时间（GMT）表示的当前时间与日期
DATE_LOCAL	以本地时区表示的当前日期与时间
DOCUMENT_NAME	当前文件名
DOCUMENT_URI	文件的虚拟路径
GATEWAY_INTERFACE	服务器所使用的通用网关接口（CGI）的修订版本，比如：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	用于识别当前会话（如果存在）的令牌