Mercurial > hg > nginx-site
view xml/ru/docs/http/ngx_http_ssi_module.xml @ 3099:9cfda14d0109 default tip
freenginx-1.27.4
author | Maxim Dounin <mdounin@mdounin.ru> |
---|---|
date | Tue, 03 Sep 2024 13:15:18 +0300 |
parents | 5cacd6fffade |
children |
line wrap: on
line source
<?xml version="1.0"?> <!-- Copyright (C) Igor Sysoev Copyright (C) Nginx, Inc. --> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Модуль ngx_http_ssi_module" link="/ru/docs/http/ngx_http_ssi_module.html" lang="ru" rev="12"> <section id="summary"> <para> Модуль <literal>ngx_http_ssi_module</literal> — это фильтр, обрабатывающий команды SSI (Server Side Includes) в проходящих через него ответах. На данный момент список поддерживаемых команд SSI неполон. </para> </section> <section id="example" name="Пример конфигурации"> <para> <example> location / { ssi on; ... } </example> </para> </section> <section id="directives" name="Директивы"> <directive name="ssi"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>off</default> <context>http</context> <context>server</context> <context>location</context> <context>if в location</context> <para> Разрешает или запрещает обработку команд SSI в ответах. </para> </directive> <directive name="ssi_last_modified"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>off</default> <context>http</context> <context>server</context> <context>location</context> <appeared-in>1.5.1</appeared-in> <para> Позволяет сохранить поле заголовка <header>Last-Modified</header> исходного ответа во время обработки SSI для лучшего кэширования ответов. </para> <para> По умолчанию поле заголовка удаляется, так как содержимое ответа изменяется во время обработки и может содержать динамически созданные элементы или части, которые изменились независимо от исходного ответа. </para> </directive> <directive name="ssi_min_file_chunk"> <syntax><literal>размер</literal></syntax> <default>1k</default> <context>http</context> <context>server</context> <context>location</context> <para> Задаёт минимальный <value>размер</value> частей ответа, хранящихся на диске, начиная с которого имеет смысл посылать их с помощью <link doc="ngx_http_core_module.xml" id="sendfile"/>. </para> </directive> <directive name="ssi_silent_errors"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>off</default> <context>http</context> <context>server</context> <context>location</context> <para> Разрешает не выводить строку “<literal>[an error occurred while processing the directive]</literal>”, если во время обработки SSI произошла ошибка. </para> </directive> <directive name="ssi_types"> <syntax><value>mime-тип</value> ...</syntax> <default>text/html</default> <context>http</context> <context>server</context> <context>location</context> <para> Разрешает обработку команд SSI в ответах с указанными MIME-типами в дополнение к “<literal>text/html</literal>”. Специальное значение “<literal>*</literal>” соответствует любому MIME-типу (0.8.29). </para> </directive> <directive name="ssi_value_length"> <syntax><value>длина</value></syntax> <default>256</default> <context>http</context> <context>server</context> <context>location</context> <para> Задаёт максимальную длину значений параметров в SSI-командах. </para> </directive> </section> <section id="commands" name="Команды SSI"> <para> Общий формат команд SSI такой: <example> <!--# команда параметр1=значение1 параметр2=значение2 ... --> </example> </para> <para> Поддерживаются следующие команды: <list type="tag"> <tag-name><literal>block</literal></tag-name> <tag-desc> Описывает блок, который можно использовать как заглушку в команде <literal>include</literal>. Внутри блока могут быть другие команды SSI. Параметр команды: <list type="tag"> <tag-name><literal>name</literal></tag-name> <tag-desc> имя блока. </tag-desc> </list> Пример: <example> <!--# block name="one" --> заглушка <!--# endblock --> </example> </tag-desc> <tag-name><literal>config</literal></tag-name> <tag-desc> Задаёт некоторые параметры, используемые при обработке SSI, а именно: <list type="tag"> <tag-name><literal>errmsg</literal></tag-name> <tag-desc> строка, выводящаяся при ошибке во время обработки SSI. По умолчанию выводится такая строка: <example> [an error occurred while processing the directive] </example> </tag-desc> <tag-name><literal>timefmt</literal></tag-name> <tag-desc> строка формата, передаваемая функции <c-func>strftime</c-func> для вывода даты и времени. По умолчанию используется такой формат: <example> "%A, %d-%b-%Y %H:%M:%S %Z" </example> Для вывода времени в секундах подходит формат “<literal>%s</literal>”. </tag-desc> </list> </tag-desc> <tag-name><literal>echo</literal></tag-name> <tag-desc> Выводит значение переменной. Параметры команды: <list type="tag"> <tag-name><literal>var</literal></tag-name> <tag-desc> имя переменной. </tag-desc> <tag-name><literal>encoding</literal></tag-name> <tag-desc> способ кодирования. Возможны три значения — <literal>none</literal>, <literal>url</literal> и <literal>entity</literal>. По умолчанию используется <literal>entity</literal>. </tag-desc> <tag-name><literal>default</literal></tag-name> <tag-desc> нестандартный параметр, задающий строку, которая выводится, если переменная не определена. По умолчанию выводится строка “<literal>(none)</literal>”. Команда <example> <!--# echo var="name" default="<emphasis>нет</emphasis>" --> </example> заменяет такую последовательность команд: <example> <!--# if expr="$name" --><!--# echo var="name" --><!--# else --><emphasis>нет</emphasis><!--# endif --> </example> </tag-desc> </list> </tag-desc> <tag-name><literal>if</literal></tag-name> <tag-desc> Выполняет условное включение. Поддерживаются следующие команды: <example> <!--# if expr="..." --> ... <!--# elif expr="..." --> ... <!--# else --> ... <!--# endif --> </example> На данный момент поддерживается только один уровень вложенности. Параметр команды: <list type="tag"> <tag-name><literal>expr</literal></tag-name> <tag-desc> выражение. В выражении может быть: <list type="bullet"> <listitem> проверка существования переменной: <example> <!--# if expr="$name" --> </example> </listitem> <listitem> сравнение переменной с текстом: <example> <!--# if expr="$name = <value>text</value>" --> <!--# if expr="$name != <value>text</value>" --> </example> </listitem> <listitem> сравнение переменной с регулярным выражением: <example> <!--# if expr="$name = /<value>text</value>/" --> <!--# if expr="$name != /<value>text</value>/" --> </example> </listitem> </list> Если в <value>text</value> встречаются переменные, то производится подстановка их значений. В регулярном выражении можно задать позиционные и именованные выделения, а затем использовать их через переменные, например: <example> <!--# if expr="$name = /(.+)@(?P<domain>.+)/" --> <!--# echo var="1" --> <!--# echo var="domain" --> <!--# endif --> </example> </tag-desc> </list> </tag-desc> <tag-name><literal>include</literal></tag-name> <tag-desc> Включает в ответ результат другого запроса. Параметры команды: <list type="tag"> <tag-name><literal>file</literal></tag-name> <tag-desc> задаёт включаемый файл, например: <example> <!--# include file="footer.html" --> </example> </tag-desc> <tag-name><literal>virtual</literal></tag-name> <tag-desc> задаёт включаемый запрос, например: <example> <!--# include virtual="/remote/body.php?argument=value" --> </example> Несколько запросов, указанных на одной странице и обрабатываемых проксируемыми или FastCGI/uwsgi/SCGI/gRPC-серверами, работают параллельно. Если нужна последовательная обработка, следует воспользоваться параметром <literal>wait</literal>. </tag-desc> <tag-name><literal>stub</literal></tag-name> <tag-desc> нестандартный параметр, задающий имя блока, содержимое которого будет выведено, если тело ответа на включаемый запрос пустое или если при исполнении запроса произошла ошибка, например: <example> <!--# block name="one" -->&nbsp;<!--# endblock --> <!--# include virtual="/remote/body.php?argument=value" stub="one" --> </example> Содержимое замещающего блока обрабатывается в контексте включаемого запроса. </tag-desc> <tag-name><literal>wait</literal></tag-name> <tag-desc> нестандартный параметр, указывающий, нужно ли ждать полного исполнения данного запроса, прежде чем продолжать выполнение SSI, например: <example> <!--# include virtual="/remote/body.php?argument=value" wait="yes" --> </example> </tag-desc> <tag-name id="ssi_include_set"><literal>set</literal></tag-name> <tag-desc> нестандартный параметр, указывающий, что удачный результат выполнения запроса нужно записать в заданную переменную, например: <example> <!--# include virtual="/remote/body.php?argument=value" set="one" --> </example> Максимальный размер ответа задаётся директивой <link doc="ngx_http_core_module.xml" id="subrequest_output_buffer_size"/> (1.13.10): <example> location /remote/ { subrequest_output_buffer_size 64k; ... } </example> До версии 1.13.10 в переменные можно было записать только результаты ответов, полученные через модули <link doc="ngx_http_proxy_module.xml">ngx_http_proxy_module</link>, <link doc="ngx_http_memcached_module.xml">ngx_http_memcached_module</link>, <link doc="ngx_http_fastcgi_module.xml">ngx_http_fastcgi_module</link> (1.5.6), <link doc="ngx_http_uwsgi_module.xml">ngx_http_uwsgi_module</link> (1.5.6) и <link doc="ngx_http_scgi_module.xml">ngx_http_scgi_module</link> (1.5.6). Максимальный размер ответа задавался при помощи директив <link doc="ngx_http_proxy_module.xml" id="proxy_buffer_size"/>, <link doc="ngx_http_memcached_module.xml" id="memcached_buffer_size"/>, <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_buffer_size"/>, <link doc="ngx_http_uwsgi_module.xml" id="uwsgi_buffer_size"/> и <link doc="ngx_http_scgi_module.xml" id="scgi_buffer_size"/>. </tag-desc> </list> </tag-desc> <tag-name><literal>set</literal></tag-name> <tag-desc> Присваивает значение переменной. Параметры команды: <list type="tag"> <tag-name><literal>var</literal></tag-name> <tag-desc> имя переменной. </tag-desc> <tag-name><literal>value</literal></tag-name> <tag-desc> значение переменной. Если в присваиваемом значении есть переменные, то производится подстановка их значений. </tag-desc> </list> </tag-desc> </list> </para> </section> <section id="variables" name="Встроенные переменные"> <para> Модуль <literal>ngx_http_ssi_module</literal> поддерживает две встроенные переменные: <list type="tag"> <tag-name id="var_date_local"><var>$date_local</var></tag-name> <tag-desc> текущее время в локальной временной зоне. Формат задаётся командой <literal>config</literal> с параметром <literal>timefmt</literal>. </tag-desc> <tag-name id="var_date_gmt"><var>$date_gmt</var></tag-name> <tag-desc> текущее время в GMT. Формат задаётся командой <literal>config</literal> с параметром <literal>timefmt</literal>. </tag-desc> </list> </para> </section> </module>