Mercurial > hg > nginx-site
view xml/ru/docs/http/ngx_http_fastcgi_module.xml @ 104:3ae68fe2e938
A nicer look for the directive's synopsis section, including i18n
for "syntax", "default", "context", and "any (context)" strings.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Wed, 19 Oct 2011 08:29:21 +0000 |
parents | c76a257f3fd4 |
children | 56457a474903 |
line wrap: on
line source
<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Директивы модуля ngx_http_fastcgi_module" link="/ru/docs/http/ngx_http_fastcgi_module.html" lang="ru"> <section name="" id="summary"> <para> Модуль ngx_http_fastcgi_module позволяет передавать запросы удалённому FastCGI-серверу. </para> </section> <section name="Пример конфигурации" id="example"> <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 name="Директивы" id="directives"> <directive name="fastcgi_buffer_size"> <syntax><value>размер</value></syntax> <default>4k/8k</default> <context>http, server, location</context> <para> Директива задаёт размер буфера, в который будет читаться первая часть ответа, получаемого от FastCGI-сервера. В этой части ответа находится, как правило, небольшой заголовок ответа. По умолчанию размер буфера равен размеру одного буфера в директиве <link id="fastcgi_buffers"/>, однако его можно сделать меньше. </para> </directive> <directive name="fastcgi_buffers"> <syntax><value>число размер</value></syntax> <default>8 4k/8k</default> <context>http, server, location</context> <para> Директива задаёт число и размер буферов для одного соединения, в которые будет читаться ответ, получаемый от FastCGI-сервера. По умолчанию размер одного буфера равен размеру страницы, в зависимости от платформы это или 4K, или 8K. </para> </directive> <directive name="fastcgi_cache"> <syntax><value>[зона|off]</value></syntax> <default>off</default> <context>http, server, location</context> <para> Директива задаёт зону для кэширования. Одна и та же зона может использоваться в нескольких местах. Параметр "off" запрещает кэширование, унаследованное с предыдущего уровня конфигурации. </para> </directive> <directive name="fastcgi_cache_bypass"> <syntax><value>строка [...]</value></syntax> <default/> <context>http, server, 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, server, location</context> <para> Директива задаёт ключ для кэширования, например, <example> fastcgi_cache_key localhost:9000$request_uri; </example> </para> </directive> <directive name="fastcgi_cache_path"> <syntax><value>путь [levels=уровни] keys_zone=название:размер [inactive=время] [max_size=размер]</value></syntax> <default/> <context>http</context> <para> Директива задаёт путь и другие параметры кэша. Данные кэша хранятся в файлах. Ключом и именем файла в кэше является результат функции md5 от проксированного URL. Параметр levels задаёт уровни иерархии кэша, например, при использовании <example> fastcgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m; </example> имена файлов в кэше будут такого вида: <example> /data/nginx/cache/<emphasis>c/29</emphasis>/b7f54b2df7773722d382f4809d650<emphasis>29c</emphasis> </example> </para> <para> Кэшируемый ответ записывается во временный файл, а потом этот файл переименовывается. Начиная с версии 0.8.9, временные файлы и кэш могут располагаться на разных файловых системах, но нужно учитывать, что в этом случае вместо дешёвой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если кэш будет находиться на той же файловой системе, что и каталог с временными файлами, задаваемый директивой <link id="fastcgi_temp_path"/> для данного location. </para> <para> Кроме того, все активные ключи и информация о данных хранятся в разделяемой памяти — зоне, имя и размер которой задаётся параметром keys_zone. Если к данным кэша не обращются в течение времени, заданного параметром inactive, то данные удаляются, независимо от их свежести. По умолчанию inactive равен 10 минутам. </para> <para> Специальный процесс "cache manager" следит за максимальным размером кэша, заданным параметром max_size, и при превышении его размеров удаляет самые невостребованные данные. </para> </directive> <directive name="fastcgi_cache_min_uses"> <syntax><value>число</value></syntax> <default>1</default> <context>http, server, location</context> <para> Директива задаёт число запросов, после которого ответ будет закэширован. </para> </directive> <directive name="fastcgi_cache_valid"> <syntax><value>ответ [ответ ...] время</value> </syntax> <default/> <context>http, server, location</context> <para> Директива задаёт время кэширования для разных ответов. Например, директивы <example> fastcgi_cache_valid 200 302 10m; fastcgi_cache_valid 404 1m; </example> задают время кэширования 10 минут для ответов 200 и 302, и 1 минуту для ответов 404. </para> <para> Если указано только время кэширования, <example> fastcgi_cache_valid 5m; </example> то кэшируются только ответы 200, 301 и 302. </para> <para> Кроме того, может кэшировать любые ответы с помощью параметра "any": <example> fastcgi_cache_valid 200 302 10m; fastcgi_cache_valid 301 1h; fastcgi_cache_valid any 1m; </example> </para> </directive> <directive name="fastcgi_cache_use_stale"> <syntax><value>[error | timeout | invalid_header | updating | http_500 | http_503 | http_404 | off] [...]</value></syntax> <default>off</default> <context>http, server, location</context> <para> Директива определяет, в каких случаях можно использовать устаревший закэшированный ответ, если при работе с проксированным сервером возникла ошибка. Параметры директивы совпадают с параметрами директивы <link id="fastcgi_next_upstream"/>. И, кроме того, есть параметр updating, которой разрешает использовать устаревший закэшированный ответ, если на данный момент он уже обновляется. </para> </directive> <directive name="fastcgi_connect_timeout"> <syntax><value>время</value></syntax> <default>60</default> <context>http, server, location</context> <para> Директива задаёт таймаут для соединения с FastCGI-сервером. Необходимо иметь в виду, что этот таймаут не может быть больше 75 секунд. </para> </directive> <directive name="fastcgi_index"> <syntax><value>имя</value></syntax> <default/> <context>http, server, location</context> <para> Директива задаёт имя файла, который при создании переменной $fastcgi_script_name будет добавляться после URI, если URI заканчивается слэшом. Например, при таких настройках <example> fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name; </example> и запросе "/page.php" параметр SCRIPT_FILENAME будет равен "/home/www/scripts/php/page.php", а при запросе "/" — "/home/www/scripts/php/index.php". </para> </directive> <directive name="fastcgi_hide_header"> <syntax><value>имя</value></syntax> <default/> <context>http, server, location</context> <para> nginx не передаёт клиенту строки заголовка "Status" и "X-Accel-..." из ответа FastCGI-сервера. Директива fastcgi_hide_header задаёт дополнительные строки. Если же строки нужно наоброт разрешить, то нужно воспользоваться директивой <link id="fastcgi_pass_header"/>. </para> </directive> <directive name="fastcgi_ignore_client_abort"> <syntax><value>[on|off]</value></syntax> <default>off</default> <context>http, server, location</context> <para> Директива определяет, закрывать ли соединение с FastCGI-сервером в случае, если клиент закрыл соединение, не дождавшись ответа. </para> </directive> <directive name="fastcgi_ignore_headers"> <syntax><value>имя [имя ...]</value></syntax> <default/> <context>http, server, location</context> <para> Директива fastcgi_ignore_headers запрещает обработку некоторых строк заголовка из ответа FastCGI-сервера. В директиве можно указать строки "X-Accel-Redirect", "X-Accel-Expires", "X-Accel-Limit-Rate" (1.1.6), "X-Accel-Buffering" (1.1.6), "X-Accel-Charset" (1.1.6), "Expires", "Cache-Control" и "Set-Cookie" (0.8.44). </para> </directive> <directive name="fastcgi_intercept_errors"> <syntax><value>on|off</value></syntax> <default>off</default> <context>http, server, location</context> <para> Директива определяет, передавать ли клиенту ответы FastCGI-сервера с кодом больше или равные 400 или же перенаправлять их на обработку nginx'у с помощью директивы error_page. </para> </directive> <directive name="fastcgi_no_cache"> <syntax><value>строка [...]</value></syntax> <default/> <context>http, server, 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_next_upstream"> <syntax> <value>[error|timeout|invalid_header|http_500|http_503|http_404|off]</value> </syntax> <default>error timeout</default> <context>http, server, location</context> <para> Директива определяет, в каких случаях запрос будет передан следующему серверу: <list type="bullet"> <listitem> error — произшла ошибка соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; </listitem> <listitem> timeout — произошёл таймаут во время соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; </listitem> <listitem> invalid_header — сервер вернул пустой или неверный ответ; </listitem> <listitem> http_500 — сервер вернул ответ с кодом 500; </listitem> <listitem> http_503 — сервер вернул ответ с кодом 503; </listitem> <listitem> http_404 — сервер вернул ответ с кодом 404; </listitem> <listitem> off — запрещает передачу запроса следующему серверу; </listitem> </list> </para> <para> Необходимо понимать, что передача запроса следующему серверу возможна только при условии, что клиенту ещё ничего не передавалось. То есть, если ошибка или таймаут возникли в середине передачи ответа, то исправить это уже невозможно. </para> </directive> <directive name="fastcgi_param"> <syntax><value>параметр значение</value></syntax> <default/> <context>http, server, location</context> <para> Директива задаёт параметр, который будут передаваться FastCGI-серверу. В качестве значения можно использовать текст, переменные и их комбинации. Директивы наследуются с предыдущего уровня при условии, что на данном уровне не описаны свои директивы fastcgi_param. </para> <para> Ниже приведён пример минимально необходимых параметров для PHP: <example> fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name; fastcgi_param QUERY_STRING $query_string; </example> </para> <para> Параметр SCRIPT_FILENAME используется в PHP для определения имени скрипта, а в параметре QUERY_STRING передаются параметры запроса. </para> <para> Если скрипты обрабатывают запросы POST, то нужны ещё три параметра: <example> fastcgi_param REQUEST_METHOD $request_method; fastcgi_param CONTENT_TYPE $content_type; fastcgi_param CONTENT_LENGTH $content_length; </example> </para> <para> Если PHP был собран с параметром конфигурации <command>--enable-force-cgi-redirect</command>, то нужно передавать параметр REDIRECT_STATUS со значением "200": <example> fastcgi_param REDIRECT_STATUS 200; </example> </para> </directive> <directive name="fastcgi_pass"> <syntax><value>fastcgi-server</value></syntax> <default/> <context>location, 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.xml">группой серверов</link>. </para> </directive> <directive name="fastcgi_pass_header"> <syntax><value>имя</value></syntax> <default/> <context>http, server, location</context> <para> Директива разрешает передавать клиенту запрещённые для передачи строки. </para> </directive> <directive name="fastcgi_read_timeout"> <syntax><value>время</value></syntax> <default>60</default> <context>http, server, location</context> <para> Директива задаёт таймаут при чтении ответа FastCGI-сервера. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени FastCGI-сервер ничего не передаст, то nginx закрывает соединение. </para> </directive> <directive name="fastcgi_send_timeout"> <syntax><value>время</value></syntax> <default>60</default> <context>http, server, location</context> <para> Директива задаёт таймаут при передаче запроса FastCGI-серверу. Таймаут устанавливается не на всю передачу запроса, а только между двумя операциями записи. Если по истечении этого времени FastCGI-сервер не примет новых данных, то nginx закрывает соединение. </para> </directive> <directive name="fastcgi_split_path_info"> <syntax><value>regex</value></syntax> <default/> <context>location</context> <para> Директива задаёт регулярное выражение, выделяющее значение для переменной $fastcgi_path_info. Регулярное выражение должно иметь два выделения, из которых первое становиться значением переменной $fastcgi_script_name, а второе — значением переменной $fastcgi_path_info. Например, при таких настройках <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> и запросе "/show.php/article/0001" параметр SCRIPT_FILENAME будет равен "/path/to/php/show.php", а параметр PATH_INFO — "/article/0001". </para> </directive> <directive name="fastcgi_store"> <syntax><value>on | off | строка </value></syntax> <default>off</default> <context>http, server, location</context> <para> Директива разрешает сохранение на диск файлов. Параметр "on" сохраняет файлы в соответствии с путями, указаными в директивах <link doc="ngx_http_core_module.xml" id="alias">alias</link> или <link doc="ngx_http_core_module.xml" id="root">root</link>. Параметр "off" запрещает сохранение файлов. Кроме того, имя файла можно явно задать с помощью строки с переменными: <example> fastcgi_store /data/www$original_uri; </example> </para> <para> Время модификации файлов выставляется согласно полученной строке "Last-Modified" в заголовке ответа. Ответ записывается во временный файл, а потом этот файл переименовывается. Начиная с версии 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></syntax> <default>user:rw</default> <context>http, server, location</context> <para> Директива задаёт права доступа для создаваемых файлов и каталогов, например, <example> fastcgi_store_access user:rw group:rw all:r; </example> </para> <para> Если заданы какие-либо права для groups или all, то права для user указывать необязательно: <example> fastcgi_store_access group:rw all:r; </example> </para> </directive> <directive name="fastcgi_temp_path"> <syntax><value>путь [ уровень1 [ уровень2 [ уровень3 ] ] ] </value></syntax> <default>fastcgi_temp</default> <context>http, server, location</context> <para> Директива задаёт имя каталога для хранения временных файлов полученных от другого сервера. В каталоге может использоваться иерархия подкаталогов до трёх уровней. Например, при такой конфигурации <example> fastcgi_temp_path /spool/nginx/fastcgi_temp 1 2; </example> имя временного будет такого вида: <example> /spool/nginx/fastcgi_temp/7/45/00000123457 </example> </para> </directive> </section> <section name="Параметры, передаваемые FastCGI-серверу" id="parameters"> <para> Строки заголовка HTTP запроса передаются FastCGI-серверу в виде параметров. В приложениях и скриптах, запущенных в виде FastCGI-сервера, эти параметры обычно доступны в виде переменных среды. Например, строка заголовка "User-Agent" передаётся как параметр HTTP_USER_AGENT. Кроме строк заголовка HTTP запроса, можно передавать произвольные параметры с помощью директивы <link id="fastcgi_param"/>. </para> </section> <section name="Встроенные переменные" id="variables"> <para> В модуле ngx_http_fastcgi_module есть встроенные переменные, которые можно использовать для формирования параметров с помощью директивы <link id="fastcgi_param"/>: <list type="bullet"> <listitem> <para> $fastcgi_script_name, эта переменная равна URI запроса или же, если URI заканчивается слэшом, то — URI запроса плюс имя индексного файла, задаваемого директивой <link id="fastcgi_index"/>. Эту переменную можно использовать для задания параметра SCRIPT_FILENAME и PATH_TRANSLATED, используемых, в частности, для определения имени скрипта в PHP. Например, для запроса "/info/" и при использовании директив <example> fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name; </example> параметр SCRIPT_FILENAME будут равен "/home/www/scripts/php/info/index.php". </para> <para> При использовании директивы <link id="fastcgi_split_path_info"/> переменная $fastcgi_script_name равна значению первого выделения, задаваемого этой директивой. </para> </listitem> <listitem> $fastcgi_path_info, эта переменная равна значению второго выделения, задаваемого директивой <link id="fastcgi_split_path_info"/>. Эту переменную можно использовать для задания параметра PATH_INFO. </listitem> </list> </para> </section> </module>