Mercurial > hg > nginx-site
view xml/ru/docs/http/ngx_http_fastcgi_module.xml @ 302:df728215db07
Documented "proxy_cache_lock", "proxy_cache_lock_timeout",
"fastcgi_cache_lock", and "fastcgi_cache_lock_timeout".
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Thu, 29 Dec 2011 15:36:38 +0000 |
parents | 2f318fe954ec |
children | 86732337c730 |
line wrap: on
line source
<?xml version="1.0"?> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Модуль ngx_http_fastcgi_module" link="/ru/docs/http/ngx_http_fastcgi_module.html" lang="ru"> <section id="summary"> <para> Модуль <literal>ngx_http_fastcgi_module</literal> позволяет передавать запросы FastCGI-серверу. </para> </section> <section id="example" name="Пример конфигурации"> <para> <example> location / { fastcgi_pass localhost:9000; fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name; fastcgi_param QUERY_STRING $query_string; fastcgi_param REQUEST_METHOD $request_method; fastcgi_param CONTENT_TYPE $content_type; fastcgi_param CONTENT_LENGTH $content_length; } </example> </para> </section> <section id="directives" name="Директивы"> <directive name="fastcgi_buffer_size"> <syntax><value>размер</value></syntax> <default>4k|8k</default> <context>http</context> <context>server</context> <context>location</context> <para> Задаёт <value>размер</value> буфера, в который будет читаться первая часть ответа, получаемого от FastCGI-сервера. В этой части ответа находится, как правило, небольшой заголовок ответа. По умолчанию размер буфера равен размеру одного буфера в директиве <link id="fastcgi_buffers"/>, однако его можно сделать меньше. </para> </directive> <directive name="fastcgi_buffers"> <syntax><value>число</value> <value>размер</value></syntax> <default>8 4k|8k</default> <context>http</context> <context>server</context> <context>location</context> <para> Задаёт <value>число</value> и <value>размер</value> буферов для одного соединения, в которые будет читаться ответ, получаемый от FastCGI-сервера. По умолчанию размер одного буфера равен размеру страницы. В зависимости от платформы это или 4K, или 8K. </para> </directive> <directive name="fastcgi_cache"> <syntax><value>зона</value> | <literal>off</literal></syntax> <default>off</default> <context>http</context> <context>server</context> <context>location</context> <para> Задаёт зону для кэширования. Одна и та же зона может использоваться в нескольких местах. Параметр <literal>off</literal> запрещает кэширование, унаследованное с предыдущего уровня конфигурации. </para> </directive> <directive name="fastcgi_cache_bypass"> <syntax><value>строка</value> ...</syntax> <default/> <context>http</context> <context>server</context> <context>location</context> <para> Задаёт условия, при которых ответ не будет браться из кэша. Если значение хотя бы одного из строковых параметров непустое и не равно “0”, то ответ не берётся из кэша: <example> fastcgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment; fastcgi_cache_bypass $http_pragma $http_authorization; </example> Можно использовать совместно с директивой <link id="fastcgi_no_cache"/>. </para> </directive> <directive name="fastcgi_cache_key"> <syntax><value>строка</value></syntax> <default/> <context>http</context> <context>server</context> <context>location</context> <para> Задаёт ключ для кэширования, например, <example> fastcgi_cache_key localhost:9000$request_uri; </example> </para> </directive> <directive name="fastcgi_cache_lock"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>off</default> <context>http</context> <context>server</context> <context>location</context> <para> Если включено, одновременно только одному запросу будет позволено заполнить новый элемент кэша, идентифицируемый согласно директиве <link id="fastcgi_cache_key"/>, передав запрос на FastCGI-сервер. Остальные запросы этого же элемента будут либо ожидать появления ответа в кэше, либо освобождения блокировки этого элемента, в течение времени, заданного директивой <link id="fastcgi_cache_lock_timeout"/>. </para> </directive> <directive name="fastcgi_cache_lock_timeout"> <syntax><value>время</value></syntax> <default>5s</default> <context>http</context> <context>server</context> <context>location</context> <para> Задаёт таймаут для <link id="fastcgi_cache_lock"/>. </para> </directive> <directive name="fastcgi_cache_min_uses"> <syntax><value>число</value></syntax> <default>1</default> <context>http</context> <context>server</context> <context>location</context> <para> Задаёт <value>число</value> запросов, после которого ответ будет закэширован. </para> </directive> <directive name="fastcgi_cache_path"> <syntax> <value>путь</value> [<literal>levels</literal>=<value>уровни</value>] <literal>keys_zone</literal>=<value>имя</value>:<value>размер</value> [<literal>inactive</literal>=<value>время</value>] [<literal>max_size</literal>=<value>размер</value>]</syntax> <default/> <context>http</context> <para> Задаёт путь и другие параметры кэша. Данные кэша хранятся в файлах. Ключом и именем файла в кэше является результат функции MD5 от проксированного URL. Параметр <literal>levels</literal> задаёт уровни иерархии кэша, например, при использовании <example> fastcgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m; </example> имена файлов в кэше будут такого вида: <example> /data/nginx/cache/<emphasis>c</emphasis>/<emphasis>29</emphasis>/b7f54b2df7773722d382f4809d650<emphasis>29c</emphasis> </example> </para> <para> Кэшируемый ответ сначала записывается во временный файл, а потом этот файл переименовывается. Начиная с версии 0.8.9, временные файлы и кэш могут располагаться на разных файловых системах, но нужно учитывать, что в этом случае вместо дешёвой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если кэш будет находиться на той же файловой системе, что и каталог с временными файлами, задаваемый директивой <link id="fastcgi_temp_path"/> для данного location. </para> <para> Кроме того, все активные ключи и информация о данных хранятся в разделяемой памяти — зоне, <value>имя</value> и <value>размер</value> которой задаются параметром <literal>keys_zone</literal>. Если к данным кэша не обращаются в течение времени, заданного параметром <literal>inactive</literal>, то данные удаляются, независимо от их свежести. По умолчанию <literal>inactive</literal> равен 10 минутам. </para> <para> Специальный процесс “cache manager” следит за максимальным размером кэша, заданным параметром <literal>max_size</literal>, и при превышении его размеров удаляет самые невостребованные данные. </para> </directive> <directive name="fastcgi_cache_use_stale"> <syntax> <literal>error</literal> | <literal>timeout</literal> | <literal>invalid_header</literal> | <literal>updating</literal> | <literal>http_500</literal> | <literal>http_503</literal> | <literal>http_404</literal> | <literal>off</literal> ...</syntax> <default>off</default> <context>http</context> <context>server</context> <context>location</context> <para> Определяет, в каких случаях можно использовать устаревший закэшированный ответ, если при работе с FastCGI-сервером возникла ошибка. Параметры директивы совпадают с параметрами директивы <link id="fastcgi_next_upstream"/>. Кроме того, дополнительный параметр <literal>updating</literal> разрешает использовать устаревший закэшированный ответ, если на данный момент он уже обновляется. </para> </directive> <directive name="fastcgi_cache_valid"> <syntax>[<value>код</value> ...] <value>время</value></syntax> <default/> <context>http</context> <context>server</context> <context>location</context> <para> Задаёт время кэширования для разных кодов ответа. Например, директивы <example> fastcgi_cache_valid 200 302 10m; fastcgi_cache_valid 404 1m; </example> задают время кэширования 10 минут для ответов с кодами 200 и 302, и 1 минуту для ответов с кодом 404. </para> <para> Если указано только <value>время</value> кэширования, <example> fastcgi_cache_valid 5m; </example> то кэшируются только ответы 200, 301 и 302. </para> <para> Кроме того, можно кэшировать любые ответы с помощью параметра <literal>any</literal>: <example> fastcgi_cache_valid 200 302 10m; fastcgi_cache_valid 301 1h; fastcgi_cache_valid any 1m; </example> </para> </directive> <directive name="fastcgi_connect_timeout"> <syntax><value>время</value></syntax> <default>60s</default> <context>http</context> <context>server</context> <context>location</context> <para> Задаёт таймаут для установления соединения с FastCGI-сервером. Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд. </para> </directive> <directive name="fastcgi_hide_header"> <syntax><value>поле</value></syntax> <default/> <context>http</context> <context>server</context> <context>location</context> <para> По умолчанию nginx не передаёт клиенту поля заголовка <header>Status</header> и <header>X-Accel-...</header> из ответа FastCGI-сервера. Директива <literal>fastcgi_hide_header</literal> задаёт дополнительные поля, которые не будут передаваться. Если же передачу полей нужно разрешить, можно воспользоваться директивой <link id="fastcgi_pass_header"/>. </para> </directive> <directive name="fastcgi_ignore_client_abort"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>off</default> <context>http</context> <context>server</context> <context>location</context> <para> Определяет, закрывать ли соединение с FastCGI-сервером в случае, если клиент закрыл соединение, не дождавшись ответа. </para> </directive> <directive name="fastcgi_ignore_headers"> <syntax><value>поле</value> ...</syntax> <default/> <context>http</context> <context>server</context> <context>location</context> <para> Запрещает обработку некоторых полей заголовка из ответа FastCGI-сервера. В директиве можно указать поля <header>X-Accel-Redirect</header>, <header>X-Accel-Expires</header>, <header>X-Accel-Limit-Rate</header> (1.1.6), <header>X-Accel-Buffering</header> (1.1.6), <header>X-Accel-Charset</header> (1.1.6), <header>Expires</header>, <header>Cache-Control</header> и <header>Set-Cookie</header> (0.8.44). </para> </directive> <directive name="fastcgi_index"> <syntax><value>имя</value></syntax> <default/> <context>http</context> <context>server</context> <context>location</context> <para> Задаёт имя файла, который при создании переменной <var>$fastcgi_script_name</var> будет добавляться после URI, если URI заканчивается слэшом. Например, при таких настройках <example> fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name; </example> и запросе “<literal>/page.php</literal>” параметр <literal>SCRIPT_FILENAME</literal> будет равен “<literal>/home/www/scripts/php/page.php</literal>”, а при запросе “<literal>/</literal>”— “<literal>/home/www/scripts/php/index.php</literal>”. </para> </directive> <directive name="fastcgi_intercept_errors"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>off</default> <context>http</context> <context>server</context> <context>location</context> <para> Определяет, передавать ли клиенту ответы FastCGI-сервера с кодом больше либо равным 400, или же перенаправлять их на обработку nginx'у с помощью директивы <link doc="ngx_http_core_module.xml" id="error_page"/>. </para> </directive> <directive name="fastcgi_next_upstream"> <syntax> <literal>error</literal> | <literal>timeout</literal> | <literal>invalid_header</literal> | <literal>http_500</literal> | <literal>http_503</literal> | <literal>http_404</literal> | <literal>off</literal> ...</syntax> <default>error timeout</default> <context>http</context> <context>server</context> <context>location</context> <para> Определяет, в каких случаях запрос будет передан следующему серверу: <list type="tag"> <tag-name><literal>error</literal></tag-name> <tag-desc>произошла ошибка соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера;</tag-desc> <tag-name><literal>timeout</literal></tag-name> <tag-desc>произошёл таймаут во время соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера;</tag-desc> <tag-name><literal>invalid_header</literal></tag-name> <tag-desc>сервер вернул пустой или неверный ответ;</tag-desc> <tag-name><literal>http_500</literal></tag-name> <tag-desc>сервер вернул ответ с кодом 500;</tag-desc> <tag-name><literal>http_503</literal></tag-name> <tag-desc>сервер вернул ответ с кодом 503;</tag-desc> <tag-name><literal>http_404</literal></tag-name> <tag-desc>сервер вернул ответ с кодом 404;</tag-desc> <tag-name><literal>off</literal></tag-name> <tag-desc>запрещает передачу запроса следующему серверу.</tag-desc> </list> </para> <para> Необходимо понимать, что передача запроса следующему серверу возможна только при условии, что клиенту ещё ничего не передавалось. То есть, если ошибка или таймаут возникли в середине передачи ответа, то исправить это уже невозможно. </para> </directive> <directive name="fastcgi_no_cache"> <syntax><value>строка</value> ...</syntax> <default/> <context>http</context> <context>server</context> <context>location</context> <para> Задаёт условия, при которых ответ не будет сохраняться в кэш. Если значение хотя бы одного из строковых параметров непустое и не равно “0”, то ответ не будет сохранён: <example> fastcgi_no_cache $cookie_nocache $arg_nocache$arg_comment; fastcgi_no_cache $http_pragma $http_authorization; </example> Можно использовать совместно с директивой <link id="fastcgi_cache_bypass"/>. </para> </directive> <directive name="fastcgi_param"> <syntax> <value>параметр</value> <value>значение</value> [<literal>if_not_empty</literal>]</syntax> <default/> <context>http</context> <context>server</context> <context>location</context> <para> Задаёт <value>параметр</value>, который будет передаваться FastCGI-серверу. В качестве значения можно использовать текст, переменные и их комбинации. Директивы наследуются с предыдущего уровня при условии, что на данном уровне не описаны свои директивы <literal>fastcgi_param</literal>. </para> <para> Ниже приведён пример минимально необходимых параметров для PHP: <example> fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name; fastcgi_param QUERY_STRING $query_string; </example> </para> <para> Параметр <literal>SCRIPT_FILENAME</literal> используется в PHP для определения имени скрипта, а в параметре <literal>QUERY_STRING</literal> передаются параметры запроса. </para> <para> Если скрипты обрабатывают запросы <literal>POST</literal>, то нужны ещё три параметра: <example> fastcgi_param REQUEST_METHOD $request_method; fastcgi_param CONTENT_TYPE $content_type; fastcgi_param CONTENT_LENGTH $content_length; </example> </para> <para> Если PHP был собран с параметром конфигурации <literal>--enable-force-cgi-redirect</literal>, то нужно передавать параметр <literal>REDIRECT_STATUS</literal> со значением “200”: <example> fastcgi_param REDIRECT_STATUS 200; </example> </para> <para> Если директива указана с <literal>if_not_empty</literal> (1.1.11), то такой параметр с пустым значением передаваться на сервер не будет: <example> fastcgi_param HTTPS $https if_not_empty; </example> </para> </directive> <directive name="fastcgi_pass"> <syntax><value>адрес</value></syntax> <default/> <context>location</context> <context>if в location</context> <para> Задаёт адрес FastCGI-сервера. Адрес может быть указан в виде доменного имени или адреса, и порта, например, <example> fastcgi_pass localhost:9000; </example> или в виде пути UNIX-сокета: <example> fastcgi_pass unix:/tmp/fastcgi.socket; </example> </para> <para> Если доменному имени соответствует несколько адресов, то все они будут использоваться по очереди (round-robin). И, кроме того, адрес может быть <link doc="ngx_http_upstream_module.xml">группой серверов</link>. </para> </directive> <directive name="fastcgi_pass_header"> <syntax><value>поле</value></syntax> <default/> <context>http</context> <context>server</context> <context>location</context> <para> Разрешает передавать от FastCGI-сервера клиенту <link id="fastcgi_hide_header">запрещённые для передачи</link> поля заголовка. </para> </directive> <directive name="fastcgi_read_timeout"> <syntax><value>время</value></syntax> <default>60s</default> <context>http</context> <context>server</context> <context>location</context> <para> Задаёт таймаут при чтении ответа FastCGI-сервера. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени FastCGI-сервер ничего не передаст, соединение закрывается. </para> </directive> <directive name="fastcgi_send_timeout"> <syntax><value>время</value></syntax> <default>60s</default> <context>http</context> <context>server</context> <context>location</context> <para> Задаёт таймаут при передаче запроса FastCGI-серверу. Таймаут устанавливается не на всю передачу запроса, а только между двумя операциями записи. Если по истечении этого времени FastCGI-сервер не примет новых данных, соединение закрывается. </para> </directive> <directive name="fastcgi_split_path_info"> <syntax><value>regex</value></syntax> <default/> <context>location</context> <para> Задаёт регулярное выражение, выделяющее значение для переменной <var>$fastcgi_path_info</var>. Регулярное выражение должно иметь два выделения, из которых первое становится значением переменной <var>$fastcgi_script_name</var>, а второе—значением переменной <var>$fastcgi_path_info</var>. Например, при таких настройках <example> location ~ ^(.+\.php)(.*)$ { fastcgi_split_path_info ^(.+\.php)(.*)$; fastcgi_param SCRIPT_FILENAME /path/to/php$fastcgi_script_name; fastcgi_param PATH_INFO $fastcgi_path_info; </example> и запросе “<literal>/show.php/article/0001</literal>” параметр <literal>SCRIPT_FILENAME</literal> будет равен “<literal>/path/to/php/show.php</literal>”, а параметр <literal>PATH_INFO</literal>—“<literal>/article/0001</literal>”. </para> </directive> <directive name="fastcgi_store"> <syntax> <literal>on</literal> | <literal>off</literal> | <value>строка</value></syntax> <default>off</default> <context>http</context> <context>server</context> <context>location</context> <para> Разрешает сохранение на диск файлов. Параметр <literal>on</literal> сохраняет файлы в соответствии с путями, указанными в директивах <link doc="ngx_http_core_module.xml" id="alias"/> или <link doc="ngx_http_core_module.xml" id="root"/>. Параметр <literal>off</literal> запрещает сохранение файлов. Кроме того, имя файла можно задать явно с помощью строки с переменными: <example> fastcgi_store /data/www$original_uri; </example> </para> <para> Время изменения файлов выставляется согласно полученному полю <header>Last-Modified</header> в заголовке ответа. Ответ сначала записывается во временный файл, а потом этот файл переименовывается. Начиная с версии 0.8.9, временный файл и постоянное место хранения ответа могут располагаться на разных файловых системах, но нужно учитывать, что в этом случае вместо дешёвой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если сохраняемые файлы будут находиться на той же файловой системе, что и каталог с временными файлами, задаваемый директивой <link id="fastcgi_temp_path"/> для данного location. </para> <para> Директиву можно использовать для создания локальных копий статических неизменяемых файлов, например, так: <example> location /images/ { root /data/www; open_file_cache_errors off; error_page 404 = /fetch$uri; } location /fetch/ { internal; fastcgi_pass backend:9000; ... fastcgi_store on; fastcgi_store_access user:rw group:rw all:r; fastcgi_temp_path /data/temp; alias /data/www/; } </example> </para> </directive> <directive name="fastcgi_store_access"> <syntax><value>пользователи</value>:<value>права</value> ...</syntax> <default>user:rw</default> <context>http</context> <context>server</context> <context>location</context> <para> Задаёт права доступа для создаваемых файлов и каталогов, например, <example> fastcgi_store_access user:rw group:rw all:r; </example> </para> <para> Если заданы какие-либо права для <literal>group</literal> или <literal>all</literal>, то права для <literal>user</literal> указывать необязательно: <example> fastcgi_store_access group:rw all:r; </example> </para> </directive> <directive name="fastcgi_temp_path"> <syntax> <value>путь</value> [<value>уровень1</value> [<value>уровень2</value> [<value>уровень3</value>]]]</syntax> <default>fastcgi_temp</default> <context>http</context> <context>server</context> <context>location</context> <para> Задаёт имя каталога для хранения временных файлов, полученных от другого сервера. В каталоге может использоваться иерархия подкаталогов до трёх уровней. Например, при такой конфигурации <example> fastcgi_temp_path /spool/nginx/fastcgi_temp 1 2; </example> временный файл будет следующего вида: <example> /spool/nginx/fastcgi_temp/<emphasis>7</emphasis>/<emphasis>45</emphasis>/00000123<emphasis>457</emphasis> </example> </para> </directive> </section> <section id="parameters" name="Параметры, передаваемые FastCGI-серверу"> <para> Поля заголовка HTTP-запроса передаются FastCGI-серверу в виде параметров. В приложениях и скриптах, запущенных в виде FastCGI-сервера, эти параметры обычно доступны в виде переменных среды. Например, поле заголовка <header>User-Agent</header> передаётся как параметр <literal>HTTP_USER_AGENT</literal>. Кроме полей заголовка HTTP-запроса можно передавать произвольные параметры с помощью директивы <link id="fastcgi_param"/>. </para> </section> <section id="variables" name="Встроенные переменные"> <para> В модуле <literal>ngx_http_fastcgi_module</literal> есть встроенные переменные, которые можно использовать для формирования параметров с помощью директивы <link id="fastcgi_param"/>: <list type="tag"> <tag-name><var>$fastcgi_script_name</var></tag-name> <tag-desc> URI запроса или же, если URI заканчивается слэшом, то URI запроса, дополненное именем индексного файла, задаваемого директивой <link id="fastcgi_index"/>. Эту переменную можно использовать для задания параметров <literal>SCRIPT_FILENAME</literal> и <literal>PATH_TRANSLATED</literal>, используемых, в частности, для определения имени скрипта в PHP. Например, для запроса “<literal>/info/</literal>” и при использовании директив <example> fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name; </example> параметр <literal>SCRIPT_FILENAME</literal> будет равен “<literal>/home/www/scripts/php/info/index.php</literal>”. <para> При использовании директивы <link id="fastcgi_split_path_info"/> переменная <var>$fastcgi_script_name</var> равна значению первого выделения, задаваемого этой директивой. </para> </tag-desc> <tag-name><var>$fastcgi_path_info</var></tag-name> <tag-desc>значение второго выделения, задаваемого директивой <link id="fastcgi_split_path_info"/>. Эту переменную можно использовать для задания параметра <literal>PATH_INFO</literal>. </tag-desc> </list> </para> </section> </module>