Модуль ngx_http_uwsgi_module

• Пример конфигурации
• Директивы
• uwsgi_bind
• uwsgi_buffer_size
• uwsgi_buffering
• uwsgi_buffers
• uwsgi_busy_buffers_size
• uwsgi_cache
• uwsgi_cache_background_update
• uwsgi_cache_bypass
• uwsgi_cache_key
• uwsgi_cache_lock
• uwsgi_cache_lock_age
• uwsgi_cache_lock_timeout
• uwsgi_cache_max_range_offset
• uwsgi_cache_methods
• uwsgi_cache_min_uses
• uwsgi_cache_path
• uwsgi_cache_purge
• uwsgi_cache_revalidate
• uwsgi_cache_use_stale
• uwsgi_cache_valid
• uwsgi_connect_timeout
• uwsgi_force_ranges
• uwsgi_hide_header
• uwsgi_ignore_client_abort
• uwsgi_ignore_headers
• uwsgi_intercept_errors
• uwsgi_limit_rate
• uwsgi_max_temp_file_size
• uwsgi_modifier1
• uwsgi_modifier2
• uwsgi_next_upstream
• uwsgi_next_upstream_timeout
• uwsgi_next_upstream_tries
• uwsgi_no_cache
• uwsgi_param
• uwsgi_pass
• uwsgi_pass_header
• uwsgi_pass_request_body
• uwsgi_pass_request_headers
• uwsgi_read_timeout
• uwsgi_request_buffering
• uwsgi_send_timeout
• uwsgi_socket_keepalive
• uwsgi_ssl_certificate
• uwsgi_ssl_certificate_key
• uwsgi_ssl_ciphers
• uwsgi_ssl_conf_command
• uwsgi_ssl_crl
• uwsgi_ssl_name
• uwsgi_ssl_password_file
• uwsgi_ssl_protocols
• uwsgi_ssl_server_name
• uwsgi_ssl_session_reuse
• uwsgi_ssl_trusted_certificate
• uwsgi_ssl_verify
• uwsgi_ssl_verify_depth
• uwsgi_store
• uwsgi_store_access
• uwsgi_temp_file_write_size
• uwsgi_temp_path

Модуль ngx_http_uwsgi_module позволяет передавать запросы на сервер uwsgi.

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

location / {
    include    uwsgi_params;
    uwsgi_pass localhost:9000;
}

Директивы

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

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

uwsgi_bind $remote_addr transparent;

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

Устанавливает размер буфера, используемого для чтения первой части ответа, полученного от сервера uwsgi. Эта часть обычно содержит небольшой заголовок ответа. По умолчанию размер буфера равен одной странице памяти. Это либо 4К, либо 8К, в зависимости от платформы. Его можно сделать меньше.

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

При включенной буферизации nginx получает ответ от сервера uwsgi как можно скорее, сохраняя его в буферы, заданные директивами uwsgi_buffer_size и uwsgi_buffers. Если весь ответ не помещается в память, его часть может быть сохранена во временный файл на диске. Запись во временные файлы контролируется директивами uwsgi_max_temp_file_size и uwsgi_temp_file_write_size.

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

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

Устанавливает количество и размер буферов, используемых для чтения ответа от сервера uwsgi для одного соединения. По умолчанию размер буфера равен одной странице памяти. Это либо 4К, либо 8К, в зависимости от платформы.

При включенной буферизации ответов от сервера uwsgi ограничивает общее количество занятых буферов, которые могут быть заняты отправкой ответа клиенту, пока ответ не будет полностью прочитан. Тем временем, остальные буферы могут быть использованы для чтения ответа и, при необходимости, буферизации части ответа во временный файл. По умолчанию, size ограничено размером двух буферов, заданных директивами uwsgi_buffer_size и uwsgi_buffers.

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

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

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

uwsgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
uwsgi_cache_bypass $http_pragma    $http_authorization;

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

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

uwsgi_cache_key localhost:9000$request_uri;

При включении, только один запрос за раз будет разрешен для заполнения нового элемента кэша, идентифицированного по директиве uwsgi_cache_key путём передачи запроса uwsgi серверу. Другие запросы к тому же элементу кэша будут ждать ответа в кэше или освобождения блокировки кэша для этого элемента, до времени, установленного директивой uwsgi_cache_lock_timeout.

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

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

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

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

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

server {
    ...
    location / {
        uwsgi_pass        backend;
        uwsgi_cache       cache_zone;
        uwsgi_cache_key   $uri;
        uwsgi_cache_purge $purge_method;
    }
}

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

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

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

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

Для минимизации числа обращений к серверам uwsgi при заполнении нового элемента кэша можно использовать директиву uwsgi_cache_lock.

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

uwsgi_cache_valid 200 302 10m;
uwsgi_cache_valid 404      1m;

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

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

uwsgi_cache_valid 5m;

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

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

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

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

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

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

Определяет таймаут для установления соединения с сервером uwsgi. Следует отметить, что этот таймаут обычно не может превышать 75 секунд.

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

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

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

Отключает обработку определенных полей заголовка ответа от сервера uwsgi. Следующие поля могут быть проигнорированы: «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» устанавливают параметры кэширования ответа caching;
• «X-Accel-Redirect» выполняет внутренний редирект на указанный URI;
• «X-Accel-Limit-Rate» устанавливает предел скорости передачи ответа клиенту;
• «X-Accel-Buffering» включает или отключает буферизацию ответа;
• «X-Accel-Charset» устанавливает желаемый кодировку ответа.

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

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

При включенной буферизации ответов от сервера uwsgi и весь ответ не помещается в буферы, заданные директивами uwsgi_buffer_size и uwsgi_buffers, часть ответа может быть сохранена во временном файле. Эта директива устанавливает максимальный size временного файла. Размер данных, записываемых во временный файл за один раз, устанавливается директивой uwsgi_temp_file_write_size.

Значение ноль отключает буферизацию ответов во временные файлы.

Это ограничение не относится к ответам, которые будут кэшироваться или храниться на диске.

Устанавливает значение поля modifier1 в заголовке пакета uwsgi.

Устанавливает значение поля modifier2 в заголовке пакета uwsgi.

Указывает, в каких случаях запрос должен быть передан следующему серверу:

error

произошла ошибка при установлении соединения с сервером, отправке запроса или чтении заголовка ответа;

timeout

произошло превышение времени ожидания при установлении соединения с сервером, отправке запроса или чтении заголовка ответа;

invalid_header

сервер вернул пустой или недопустимый ответ;

http_500

сервер вернул ответ с кодом 500;

http_503

сервер вернул ответ с кодом 503;

http_403

сервер вернул ответ с кодом 403;

http_404

сервер вернул ответ с кодом 404;

http_429

сервер вернул ответ с кодом 429 (1.11.13);

non_idempotent

обычно запросы с неидемпотентным методом (POST, LOCK, PATCH) не передаются следующему серверу, если запрос уже был отправлен промежуточному серверу (1.9.13); включение этого параметра явно позволяет повторно отправлять такие запросы;

off

отключает передачу запроса следующему серверу.

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

Директива также определяет, что считается неудачной попыткой связи с сервером. Случаи error, timeout и invalid_header всегда считаются неудачными попытками, даже если они не указаны в директиве. Случаи http_500, http_503, и http_429 считаются неудачными попытками только если они указаны в директиве. Случаи http_403 и http_404 никогда не считаются неудачными попытками.

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

Ограничивает время, в течение которого запрос может быть передан следующему серверу. Значение 0 отключает это ограничение.

Ограничивает количество попыток передачи запроса следующему серверу. Значение 0 отключает это ограничение.

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

uwsgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
uwsgi_no_cache $http_pragma    $http_authorization;

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

Устанавливает parameter, который должен быть передан серверу uwsgi. value может содержать текст, переменные и их комбинации. Эти директивы наследуются с предыдущего уровня конфигурации только в том случае, если на текущем уровне не определены директивы uwsgi_param.

Стандартные переменные среды CGI должны быть предоставлены как заголовки uwsgi, см. файл uwsgi_params в дистрибутиве:

location / {
    include uwsgi_params;
    ...
}

Если директива указана со значением if_not_empty (1.1.11), то такой параметр будет передан серверу только если его значение не пустое:

uwsgi_param HTTPS $https if_not_empty;

Устанавливает протокол и адрес сервера uwsgi. В качестве protocol, можно указать “uwsgi” или “suwsgi” (защищённый uwsgi, uwsgi через SSL). Адрес можно указать как доменное имя или IP-адрес, и порт:

uwsgi_pass localhost:9000;
uwsgi_pass uwsgi://localhost:9000;
uwsgi_pass suwsgi://[2001:db8::1]:9090;

или как путь к сокету UNIX-домена:

uwsgi_pass unix:/tmp/uwsgi.socket;

Если доменное имя разрешается в несколько адресов, все они будут использоваться в циклическом порядке. Кроме того, адрес может быть указан как группа серверов.

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

Протокол защищённого uwsgi поддерживается начиная с версии 1.5.8.

Разрешает передачу иначе отключённых полей заголовка с сервера uwsgi клиенту.

Указывает, передаётся ли исходное тело запроса серверу uwsgi. См. также директиву uwsgi_pass_request_headers.

Указывает, передаются ли поля заголовков исходного запроса серверу uwsgi. См. также директиву uwsgi_pass_request_body.

Определяет время ожидания чтения ответа от сервера uwsgi. Время ожидания устанавливается только между двумя последовательными операциями чтения, а не для передачи всего ответа. Если сервер uwsgi не передаёт ничего в течение этого времени, соединение закрывается.

Включает или отключает буферизацию тела запроса клиента.

При включённой буферизации всё тело запроса считывается с клиента перед отправкой запроса серверу uwsgi.

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

При использовании HTTP/1.1 с кодировкой передачи тела запроса в блоках (chunked), тело запроса будет буферизоваться независимо от значения директивы.

Устанавливает время ожидания передачи запроса серверу uwsgi. Время ожидания устанавливается только между двумя последовательными операциями записи, а не для передачи всего запроса. Если сервер uwsgi не получает ничего в течение этого времени, соединение закрывается.

Настраивает поведение «TCP keepalive» для исходящих соединений с сервером uwsgi. По умолчанию, для сокета действуют настройки операционной системы. Если директива имеет значение “on”, опция сокета SO_KEEPALIVE включается для сокета.

Указывает file с сертификатом в формате PEM, используемым для аутентификации на защищённом сервере uwsgi.

Начиная с версии 1.21.0, в имени file можно использовать переменные.

Указывает file с секретным ключом в формате PEM, используемым для аутентификации на защищённом сервере uwsgi.

Можно указать значение engine:name:id вместо file (1.7.9), которое загружает секретный ключ с указанным id из модуля OpenSSL name.

С версии 1.21.0 в имени file можно использовать переменные.

Указывает включённые шифры для запросов к защищённому серверу uwsgi. Шифры указаны в формате, понятном библиотеке OpenSSL.

Полный список можно просмотреть с помощью команды “openssl ciphers”.

Устанавливает произвольные команды конфигурации OpenSSL команд при установлении соединения с защищённым сервером uwsgi.

Директива поддерживается при использовании OpenSSL 1.0.2 или выше.

Можно указать несколько директив uwsgi_ssl_conf_command, находящихся на одном уровне. Эти директивы наследуются с предыдущего уровня конфигурации только в том случае, если на текущем уровне не определены директивы uwsgi_ssl_conf_command.

Обратите внимание, что непосредственная настройка OpenSSL может привести к непредсказуемому поведению.

Указывает file с отменёнными сертификатами (CRL) в формате PEM, используемыми для проверки сертификата защищённого сервера uwsgi.

Позволяет переопределить имя сервера, используемое для проверки сертификата защищённого сервера uwsgi и для передачи через SNI при установлении соединения с защищённым сервером uwsgi.

По умолчанию используется часть хоста из uwsgi_pass.

Указывает file с парольными фразами для секретных ключей, где каждая фраза указана на отдельной строке. Парольные фразы проверяются по очереди при загрузке ключа.

Включает указанные протоколы для запросов к защищённому серверу uwsgi.

Параметр TLSv1.3 используется по умолчанию с версии 1.23.4.

Включает или отключает передачу имени сервера через расширение TLS Server Name Indication (SNI, RFC 6066) при установлении соединения с защищённым сервером uwsgi.

uwsgi_store /data/www$original_uri;

location /images/ {
    root               /data/www;
    error_page         404 = /fetch$uri;
}

location /fetch/ {
    internal;

    uwsgi_pass         backend:9000;
    ...

    uwsgi_store        on;
    uwsgi_store_access user:rw group:rw all:r;
    uwsgi_temp_path    /data/temp;

    alias              /data/www/;
}

uwsgi_store_access user:rw group:rw all:r;

uwsgi_store_access group:rw all:r;

uwsgi_temp_path /spool/nginx/uwsgi_temp 1 2;

/spool/nginx/uwsgi_temp/7/45/00000123457