Модуль ngx_http_fastcgi_module

• Пример конфигурации
• Директивы
• fastcgi_allow_upstream
• fastcgi_bind
• fastcgi_bind_dynamic
• fastcgi_buffer_size
• fastcgi_buffering
• fastcgi_buffers
• fastcgi_busy_buffers_size
• fastcgi_cache
• fastcgi_cache_background_update
• fastcgi_cache_bypass
• fastcgi_cache_key
• fastcgi_cache_lock
• fastcgi_cache_lock_age
• fastcgi_cache_lock_timeout
• fastcgi_cache_max_range_offset
• fastcgi_cache_methods
• fastcgi_cache_min_uses
• fastcgi_cache_path
• fastcgi_cache_purge
• fastcgi_cache_revalidate
• fastcgi_cache_use_stale
• fastcgi_cache_valid
• fastcgi_catch_stderr
• fastcgi_connect_timeout
• fastcgi_force_ranges
• fastcgi_hide_header
• fastcgi_ignore_client_abort
• fastcgi_ignore_headers
• fastcgi_index
• fastcgi_intercept_errors
• fastcgi_keep_conn
• fastcgi_limit_rate
• fastcgi_max_temp_file_size
• fastcgi_next_upstream
• fastcgi_next_upstream_timeout
• fastcgi_next_upstream_tries
• fastcgi_no_cache
• fastcgi_param
• fastcgi_pass
• fastcgi_pass_header
• fastcgi_pass_request_body
• fastcgi_pass_request_headers
• fastcgi_read_timeout
• fastcgi_request_buffering
• fastcgi_request_dynamic
• fastcgi_send_lowat
• fastcgi_send_timeout
• fastcgi_socket_keepalive
• fastcgi_split_path_info
• fastcgi_store
• fastcgi_store_access
• fastcgi_temp_file_write_size
• fastcgi_temp_path
• Параметры, передаваемые FastCGI-серверу
• Встроенные переменные

Модуль ngx_http_fastcgi_module позволяет передавать запросы FastCGI-серверу.

Пример конфигурации

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;
}

Директивы

Задаёт условия, при которых доступ к FastCGI-серверу разрешён или запрещён. Если все строковые параметры не пусты и не равны «0», доступ разрешён. Условия проверяются каждый раз перед установлением соединения с FastCGI-сервером. Значения параметров могут содержать переменные:

geo $upstream_last_addr $allow {
    volatile;
    10.10.0.0/24        1;
}

server {
    listen 127.0.0.1:8080;

    location / {
        fastcgi_pass           localhost:9000;
        fastcgi_allow_upstream $allow;
        ...
    }
}

Эта директива доступна в рамках нашей коммерческой подписки.

Заставляет исходящие соединения с FastCGI-сервером устанавливаться с указанного локального IP-адреса и, при необходимости, порта (1.11.2). Значение параметра может содержать переменные (1.3.12). Специальное значение off (1.3.12) отменяет действие директивы fastcgi_bind, унаследованной с предыдущего уровня конфигурации, что позволяет системе автоматически назначать локальный IP-адрес и порт.

Параметр transparent (1.11.0) позволяет устанавливать исходящие соединения с FastCGI-сервером с нелокального IP-адреса, например с реального IP-адреса клиента:

fastcgi_bind $remote_addr transparent;

Чтобы этот параметр работал, обычно необходимо запускать рабочие процессы nginx с привилегиями суперпользователя. В Linux этого не требуется (1.13.8), так как при указании параметра transparent рабочие процессы наследуют возможность CAP_NET_RAW от главного процесса. Также необходимо настроить таблицу маршрутизации ядра для перехвата сетевого трафика от FastCGI-сервера.

При включении операция bind выполняется при каждой попытке установить соединение.

Эта директива доступна в рамках нашей коммерческой подписки.

Задаёт size буфера, используемого для чтения первой части ответа, полученного от FastCGI-сервера. Эта часть обычно содержит небольшой заголовок ответа; если его размер превышает размер буфера, ответ считается недопустимым. По умолчанию размер буфера равен размеру одной страницы памяти. В зависимости от платформы он составляет 4K или 8K. Его можно уменьшить.

Включает или отключает буферизацию ответов FastCGI-сервера.

При включённой буферизации nginx как можно быстрее получает ответ от FastCGI-сервера и сохраняет его в буферах, заданных директивами fastcgi_buffer_size и fastcgi_buffers. Если весь ответ не помещается в памяти, его часть может быть сохранена во временный файл на диске. Запись во временные файлы регулируется директивами fastcgi_max_temp_file_size и fastcgi_temp_file_write_size.

При отключённой буферизации ответ передаётся клиенту синхронно, сразу после получения. nginx не пытается прочитать весь ответ от FastCGI-сервера. Максимальный объём данных, который nginx может получить от сервера за один раз, задаётся директивой fastcgi_buffer_size.

Буферизацию также можно включить или отключить, передав в поле заголовка ответа «X-Accel-Buffering» значение «yes» или «no». Эту возможность можно отключить с помощью директивы fastcgi_ignore_headers.

Задаёт number и size буферов, используемых для чтения ответа FastCGI-сервера при одном соединении. По умолчанию размер буфера равен размеру одной страницы памяти. В зависимости от платформы он составляет 4K или 8K.

При включённой буферизации ответов FastCGI-сервера ограничивает общий size буферов, которые могут быть заняты отправкой ответа клиенту, пока ответ ещё не прочитан полностью. Остальные буферы в это время могут использоваться для чтения ответа и, при необходимости, для записи его части во временный файл. По умолчанию size ограничено размером двух буферов, заданных директивами fastcgi_buffer_size и fastcgi_buffers.

Задаёт зону общей памяти, используемую для кэширования. Одна и та же зона может использоваться в нескольких местах. Значение параметра может содержать переменные (1.7.9). Параметр off отключает кэширование, унаследованное с предыдущего уровня конфигурации.

Разрешает запуск фонового подзапроса для обновления просроченного элемента кэша, пока клиенту возвращается устаревший кэшированный ответ. Обратите внимание, что необходимо разрешить использование устаревшего кэшированного ответа во время его обновления.

Задаёт условия, при которых ответ не будет получен из кэша. Если хотя бы одно значение строковых параметров не пусто и не равно «0», ответ не будет получен из кэша:

fastcgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
fastcgi_cache_bypass $http_pragma    $http_authorization;

Может использоваться вместе с директивой fastcgi_no_cache.

Задаёт ключ кэширования, например

fastcgi_cache_key localhost:9000$request_uri;

Если директива включена, одновременно только одному запросу разрешается заполнить новый элемент кэша, определяемый согласно директиве fastcgi_cache_key, путём отправки запроса FastCGI-серверу. Другие запросы для того же элемента кэша будут ждать появления ответа в кэше или снятия блокировки этого элемента в течение времени, заданного директивой fastcgi_cache_lock_timeout.

Если последний запрос, отправленный FastCGI-серверу для заполнения нового элемента кэша, не завершился в течение указанного time, FastCGI-серверу может быть отправлен ещё один запрос.

Задаёт время ожидания для fastcgi_cache_lock. По истечении time запрос будет отправлен FastCGI-серверу, однако ответ не будет кэширован.

До версии 1.7.8 ответ мог быть кэширован.

Задаёт смещение в байтах для запросов диапазона байтов. Если диапазон выходит за пределы смещения, запрос диапазона будет передан FastCGI-серверу, а ответ не будет кэширован.

Если метод клиентского запроса указан в этой директиве, ответ будет кэширован. Методы «GET» и «HEAD» всегда добавляются в список, хотя рекомендуется указывать их явно. См. также директиву fastcgi_no_cache.

Задаёт number запросов, после которого ответ будет кэширован.

Задаёт путь и другие параметры кэша. Данные кэша хранятся в файлах. Ключ и имя файла в кэше являются результатом применения функции MD5 к проксируемому URL. Параметр levels задаёт уровни иерархии кэша: от 1 до 3; для каждого уровня допускаются значения 1 или 2. Например, при следующей конфигурации

fastcgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;

имена файлов в кэше будут выглядеть так:

/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c

Кэшированный ответ сначала записывается во временный файл, а затем файл переименовывается. Начиная с версии 0.8.9 временные файлы и кэш могут располагаться в разных файловых системах. Однако учтите, что в этом случае файл копируется между файловыми системами вместо дешёвой операции переименования. Поэтому рекомендуется размещать кэш и каталог временных файлов для каждой конкретной локации в одной файловой системе. Каталог временных файлов задаётся параметром use_temp_path (1.7.10). Если этот параметр опущен или имеет значение on, будет использоваться каталог, заданный директивой fastcgi_temp_path для данной локации. Если задано значение off, временные файлы будут размещаться непосредственно в каталоге кэша.

Кроме того, все активные ключи и информация о данных хранятся в зоне общей памяти, name и size которой настраиваются параметром keys_zone. В зоне размером один мегабайт может храниться около 8 тысяч ключей.

В рамках коммерческой подписки в зоне общей памяти также хранится расширенная информация о кэше, поэтому для того же количества ключей требуется задавать больший размер зоны. Например, в зоне размером один мегабайт может храниться около 4 тысяч ключей.

Кэшированные данные, к которым не обращались в течение времени, указанного параметром inactive, удаляются из кэша независимо от их актуальности. По умолчанию inactive равен 10 минутам.

Специальный процесс «менеджер кэша» отслеживает максимальный размер кэша, заданный параметром max_size, и минимальный объём свободного места, заданный параметром min_free (1.19.1), в файловой системе с кэшем. При превышении размера или нехватке свободного места он удаляет данные, к которым обращались реже всего. Данные удаляются итерациями, настроенными параметрами manager_files, manager_threshold и manager_sleep (1.11.5). За одну итерацию удаляется не более manager_files элементов (по умолчанию 100). Продолжительность одной итерации ограничена параметром manager_threshold (по умолчанию 200 миллисекунд). Между итерациями делается пауза, заданная параметром manager_sleep (по умолчанию 50 миллисекунд).

Через минуту после запуска активируется специальный процесс «загрузчик кэша». Он загружает в зону кэша информацию о ранее кэшированных данных, хранящихся в файловой системе. Загрузка также выполняется итерациями. За одну итерацию загружается не более loader_files элементов (по умолчанию 100). Кроме того, продолжительность одной итерации ограничена параметром loader_threshold (по умолчанию 200 миллисекунд). Между итерациями делается пауза, заданная параметром loader_sleep (по умолчанию 50 миллисекунд).

Кроме того, в рамках нашей коммерческой подписки доступны следующие параметры:

purger=on|off

Указывает, следует ли удалять с диска записи кэша, соответствующие маске с подстановочными знаками, с помощью очистителя кэша (1.7.12). Значение on (по умолчанию — off) активирует процесс «очиститель кэша», который постоянно перебирает все записи кэша и удаляет записи, соответствующие маске с подстановочными знаками.

purger_files=number

Задаёт количество элементов, проверяемых за одну итерацию (1.7.12). По умолчанию purger_files равно 10.

purger_threshold=number

Задаёт продолжительность одной итерации (1.7.12). По умолчанию purger_threshold равно 50 миллисекундам.

purger_sleep=number

Задаёт паузу между итерациями (1.7.12). По умолчанию purger_sleep равно 50 миллисекундам.

В версиях 1.7.3, 1.7.7 и 1.11.10 формат заголовка кэша был изменён. После обновления до более новой версии nginx ранее кэшированные ответы будут считаться недействительными.

Задаёт условия, при которых запрос считается запросом на очистку кэша. Если хотя бы одно значение строковых параметров не пусто и не равно «0», удаляется запись кэша с соответствующим ключом кэша. Успешное выполнение операции подтверждается ответом 204 (No Content).

Если ключ кэша запроса на очистку заканчивается звёздочкой («*»), из кэша удаляются все записи, соответствующие ключу с подстановочным знаком. Однако эти записи останутся на диске, пока не будут удалены из-за отсутствия обращений, не будут обработаны очистителем кэша (1.7.12) или к ним не обратится клиент.

Пример конфигурации:

fastcgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m;

map $request_method $purge_method {
    PURGE   1;
    default 0;
}

server {
    ...
    location / {
        fastcgi_pass        backend;
        fastcgi_cache       cache_zone;
        fastcgi_cache_key   $uri;
        fastcgi_cache_purge $purge_method;
    }
}

Эта функция доступна в рамках нашей коммерческой подписки.

Включает повторную проверку актуальности просроченных элементов кэша с помощью условных запросов с полями заголовка «If-Modified-Since» и «If-None-Match».

Определяет, в каких случаях при ошибке связи с FastCGI-сервером можно использовать устаревший кэшированный ответ. Параметры директивы соответствуют параметрам директивы fastcgi_next_upstream.

Параметр error также разрешает использовать устаревший кэшированный ответ, если для обработки запроса не удалось выбрать FastCGI-сервер.

Кроме того, параметр updating разрешает использовать устаревший кэшированный ответ, если в данный момент он обновляется. Это позволяет свести к минимуму количество обращений к FastCGI-серверам при обновлении кэшированных данных.

Использование устаревшего кэшированного ответа также можно разрешить непосредственно в заголовке ответа на заданное число секунд после того, как ответ устарел (1.11.10). Этот способ имеет более низкий приоритет, чем параметры директивы.

• Расширение «stale-while-revalidate» поля заголовка «Cache-Control» разрешает использовать устаревший кэшированный ответ, если в данный момент он обновляется.
• Расширение «stale-if-error» поля заголовка «Cache-Control» разрешает использовать устаревший кэшированный ответ в случае ошибки.

Чтобы свести к минимуму количество обращений к FastCGI-серверам при заполнении нового элемента кэша, можно использовать директиву fastcgi_cache_lock.

Задаёт время кэширования для разных кодов ответа. Например, следующие директивы

fastcgi_cache_valid 200 302 10m;
fastcgi_cache_valid 404      1m;

задают время кэширования в 10 минут для ответов с кодами 200 и 302 и в 1 минуту для ответов с кодом 404.

Если указано только кэширование time

fastcgi_cache_valid 5m;

кэшируются только ответы 200, 301 и 302.

Кроме того, для кэширования любых ответов можно указать параметр any:

fastcgi_cache_valid 200 302 10m;
fastcgi_cache_valid 301      1h;
fastcgi_cache_valid any      1m;

Параметры кэширования также можно задавать непосредственно в заголовке ответа. Это имеет более высокий приоритет, чем задание времени кэширования с помощью директивы.

• Поле заголовка «X-Accel-Expires» задаёт время кэширования ответа в секундах. Нулевое значение отключает кэширование ответа. Если значение начинается с префикса @, оно задаёт абсолютное время в секундах от эпохи, до которого ответ может кэшироваться.
• Если в заголовке отсутствует поле «X-Accel-Expires», параметры кэширования можно задать в полях заголовка «Expires» или «Cache-Control».
• Если заголовок содержит поле «Set-Cookie», такой ответ не кэшируется.
• Если заголовок содержит поле «Vary» со специальным значением «*», такой ответ не кэшируется (1.7.7). Если заголовок содержит поле «Vary» с другим значением, ответ кэшируется с учётом соответствующих полей заголовка запроса (1.7.7).

Обработку одного или нескольких из этих полей заголовка ответа можно отключить с помощью директивы fastcgi_ignore_headers.

Задаёт строку для поиска в потоке ошибок ответа, полученного от FastCGI-сервера. Если найдена string, считается, что FastCGI-сервер вернул недопустимый ответ. Это позволяет обрабатывать ошибки приложения в nginx, например:

location /php/ {
    fastcgi_pass backend:9000;
    ...
    fastcgi_catch_stderr "PHP Fatal error";
    fastcgi_next_upstream error timeout invalid_header;
}

Задаёт время ожидания установления соединения с FastCGI-сервером. Следует учитывать, что обычно это время не может превышать 75 секунд.

Включает поддержку диапазонов байтов для кэшированных и некэшированных ответов FastCGI-сервера независимо от наличия в этих ответах поля «Accept-Ranges».

По умолчанию nginx не передаёт клиенту поля заголовка «Status» и «X-Accel-...» из ответа FastCGI-сервера. Директива fastcgi_hide_header задаёт дополнительные поля, которые передаваться не будут. Если, напротив, требуется разрешить передачу полей, можно использовать директиву fastcgi_pass_header.

Определяет, следует ли закрывать соединение с FastCGI-сервером, если клиент закрыл соединение, не дождавшись ответа.

Отключает обработку определённых полей заголовка ответа 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) и «Vary» (1.7.7).

Если обработка этих полей заголовка не отключена, она приводит к следующим последствиям:

• «X-Accel-Expires», «Expires», «Cache-Control», «Set-Cookie» и «Vary» задают параметры кэширования ответа;
• «X-Accel-Redirect» выполняет внутреннее перенаправление на указанный URI;
• «X-Accel-Limit-Rate» задаёт ограничение скорости передачи ответа клиенту;
• «X-Accel-Buffering» включает или отключает буферизацию ответа;
• «X-Accel-Charset» задаёт требуемую кодировку ответа.

Задаёт имя файла, добавляемое после URI, оканчивающегося косой чертой, в значении переменной $fastcgi_script_name. Например, при таких настройках

fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;

для запроса «/page.php» параметр SCRIPT_FILENAME будет равен «/home/www/scripts/php/page.php», а для запроса «/» он будет равен «/home/www/scripts/php/index.php».

Определяет, следует ли передавать клиенту ответы FastCGI-сервера с кодами, равными или превышающими 300, либо перехватывать их и перенаправлять в nginx для обработки директивой error_page.

По умолчанию FastCGI-сервер закрывает соединение сразу после отправки ответа. Однако, если директиве задано значение on, nginx укажет FastCGI-серверу сохранять соединения открытыми. Это необходимо, в частности, для работы соединений keepalive с FastCGI-серверами.

fastcgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
fastcgi_no_cache $http_pragma    $http_authorization;

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;

fastcgi_param REDIRECT_STATUS 200;

fastcgi_param HTTPS           $https if_not_empty;

fastcgi_pass localhost:9000;

fastcgi_pass unix:/tmp/fastcgi.socket;

location ~ ^(.+\.php)(.*)$ {
    fastcgi_split_path_info       ^(.+\.php)(.*)$;
    fastcgi_param SCRIPT_FILENAME /path/to/php$fastcgi_script_name;
    fastcgi_param PATH_INFO       $fastcgi_path_info;

fastcgi_store /data/www$original_uri;

location /images/ {
    root                 /data/www;
    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/;
}

fastcgi_store_access user:rw group:rw all:r;

fastcgi_store_access group:rw all:r;

fastcgi_temp_path /spool/nginx/fastcgi_temp 1 2;

/spool/nginx/fastcgi_temp/7/45/00000123457