Директивы NGINX

Описание

Директива 'master_process' — это флаг, определяющий, будет ли NGINX работать в режиме мастера или в режиме одиночного процесса. Когда установлено 'on', мастер-процесс включается, что позволяет NGINX управлять рабочими процессами. Это стандартный режим работы NGINX, в котором мастер-процесс отвечает за управление рабочими процессами, включая их создание и завершение по мере необходимости в зависимости от нагрузки. Если 'master_process' установлена в 'off', NGINX будет работать без мастер-процесса и функционировать в режиме одиночного процесса. В этом режиме нет рабочих процессов; NGINX обрабатывает все запросы в одном процессе. Это может быть полезно для отладки или в легковесных окружениях, где многопроцессность не нужна, но такой режим менее эффективен по сравнению со стандартной моделью мастер-воркер. Конфигурация этой директивы имеет решающее значение для обеспечения функционирования NGINX в ожидаемой многопроцессной среде, где несколько рабочих процессов улучшают производительность и использование ресурсов. Параметр этой директивы — простой флаг — "on" или "off", указывающий, должен ли мастер-процесс быть включен или отключен. Как правило, он размещается в основном контексте файла конфигурации nginx, и его использование может варьироваться в зависимости от конкретных требований развертывания, таких как ограничения ресурсов или операционные цели.

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

master_process on;

Описание

Директива `timer_resolution` в NGINX позволяет задать разрешение таймера событий в миллисекундах. Эта директива определяется в основном модуле и имеет решающее значение для оптимизации операций, связанных с учётом времени в системе обработки событий NGINX. Регулируя разрешение таймера, пользователи могут влиять на то, как обрабатываются события, что потенциально может привести к повышению производительности приложений с особыми требованиями к точности временных характеристик. Аргумент директивы `timer_resolution` — одно значение, задающее разрешение таймера в миллисекундах. Это особенно важно для приложений с событиями высокой частоты, где более мелкое разрешение таймера может улучшить точность выполнения таких событий. Однако чрезмерно низкое значение может увеличить нагрузку на CPU из-за более частых проверок таймера. Поэтому необходимо найти баланс, соответствующий рабочей нагрузке сервера. Обратите внимание, что эта директива должна быть задана в главном контексте, то есть она должна появляться только на верхнем уровне конфигурации NGINX (например, в основном блоке конфигурации и не внутри events или http блоков). Понимание потребности вашего приложения в точности временных показателей поможет эффективно использовать эту директиву для повышения общей производительности.

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

timer_resolution 100;

Описание

Директива `pid` используется в ядре NGINX для задания расположения файла, который будет содержать идентификатор процесса (PID) мастер-процесса при запуске NGINX. Этот PID-файл имеет решающее значение для управления процессом NGINX, позволяя администраторам легко отслеживать и контролировать его, особенно при выполнении операций, таких как корректное завершение работы или перезагрузка. Указав для этой директивы путь к файлу, NGINX создаст этот файл и запишет в него свой PID при старте. Это облегчает управление процессом и гарантирует, что системные администраторы смогут эффективно управлять службой без необходимости угадывать идентификатор процесса. Параметр директивы `pid` — это единый аргумент, задающий путь к файлу, в котором будет сохраняться PID. Обычно этот путь указывается в место, доступное для записи пользователем, под которым выполняется процесс NGINX, поэтому важно обеспечить корректные права доступа. В случаях, когда указанный PID-файл не может быть создан или записан из-за проблем с правами доступа или неверного пути, NGINX выдаст ошибку и завершит работу, не запустившись. Поэтому необходимо убедиться, что указанный путь действителен и доступен. Директива `pid` должна находиться в основном контексте конфигурации, как правило на верхнем уровне конфигурационного файла, до любых блоков server или location, поскольку она относится ко всему процессу NGINX, а не к отдельным процессам серверов.

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

pid /var/run/nginx.pid;

Описание

Директива `lock_file` в NGINX используется для определения конкретного файла, который выступает в качестве блокировки, чтобы предотвратить одновременный запуск нескольких экземпляров NGINX. При запуске NGINX он пытается создать блокировку с помощью указанного файла. Если этот файл уже существует, что указывает на то, что другой экземпляр NGINX запущен, новый экземпляр не запустится и зафиксирует соответствующее сообщение об ошибке. Этот механизм необходим для сохранения целостности конфигураций и обеспечения того, что одновременно может работать только один главный процесс NGINX. Аргумент, передаваемый в `lock_file`, — это путь к файлу, который можно указать в любом доступном для записи месте. Как правило, это временный каталог или выделенный каталог конфигурации. Тщательно выбирая расположение файла блокировки, системные администраторы могут более эффективно управлять средами с несколькими экземплярами. Использование файла блокировки особенно полезно в конфигурациях, где автоматизированные скрипты или менеджеры сервисов могут непреднамеренно попытаться запустить несколько экземпляров NGINX, что приводит к конфликтам и другим нежелательным состояниям. Важно отметить, что если указанный файл блокировки не может быть создан из-за проблем с правами или ошибок файловой системы, NGINX не запустится и отобразит сообщение об ошибке, связанное с невозможностью создать файл блокировки. Поэтому администраторы должны убедиться, что процесс NGINX имеет соответствующие права для создания и записи в этот файл блокировки.

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

lock_file /var/run/nginx.lock;

Описание

Директива `worker_processes` определяет, сколько рабочих процессов NGINX создаст для обработки запросов. Каждый рабочий процесс может одновременно обрабатывать множество соединений, что позволяет NGINX эффективно масштабироваться в зависимости от числа доступных ядер CPU и объёма входящих запросов. Указанное число рабочих процессов может существенно повлиять на общую производительность сервера, особенно при высокой нагрузке. Эта директива может принимать целочисленное значение, обозначающее фиксированное число рабочих процессов, или ключевое слово `auto`, которое инструктирует NGINX автоматически задать количество на основе доступных ядер CPU. При установке в `auto` NGINX вычисляет количество рабочих процессов исходя из числа обнаруженных на сервере ядер CPU. Рекомендуется задавать это значение с учётом аппаратного обеспечения и специфических потребностей приложения для достижения оптимальной производительности. На практике при настройке директивы `worker_processes` системным администраторам следует отслеживать нагрузку и показатели производительности их приложений, чтобы определить подходящее значение. Как указание слишком малого, так и слишком большого числа рабочих процессов может привести к ухудшению производительности. В некоторых средах может потребоваться тщательная настройка, чтобы учесть характеристики ожидаемой нагрузки на сервер.

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

worker_processes auto;

Описание

Директива `debug_points` предназначена для разработчиков и опытных пользователей, которые хотят управлять потоком выполнения сервера NGINX в целях отладки. Эту директиву можно настраивать в главном контексте; она принимает один аргумент, задающий, какую точку отладки вызвать. Доступные операнды для этой директивы — `stop` и `abort`, каждый из которых по‑разному влияет на процесс NGINX при достижении во время выполнения. Когда установлено `stop`, NGINX приостанавливает выполнение в заданной точке отладки, позволяя пользователю при необходимости подключить отладчик. Это особенно полезно для пошагового анализа поведения приложения в ответ на конкретные запросы или системные события. С другой стороны, выбор `abort` приведёт к немедленному завершению процесса, что удобно при отладке фатальных ошибок или для обеспечения целостности системы в нежелательных состояниях. Поведение директивы `debug_points` может значительно улучшить процесс отладки при разработке или диагностике модулей и конфигураций NGINX. Она служит механизмом введения преднамеренных точек останова в коде без внесения изменений в исходный код, что облегчает более эффективные отладочные сценарии.

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

debug_points stop;

Описание

Директива `user` в NGINX задаёт привилегии пользователя и группы для рабочих процессов. Это важно для безопасности: NGINX будет работать от имени непривилегированного пользователя, а не root, что снижает потенциальный ущерб от уязвимостей. Директива принимает один или два параметра: первый параметр — имя пользователя, а второй (необязательный) — имя группы. Если указан только один аргумент, NGINX будет использовать группу по умолчанию, связанную с этим пользователем. Например, `user nginx;` устанавливает пользователя 'nginx' и использует группу по умолчанию для 'nginx'. При указании обоих параметров запись имеет вид `user username groupname;`. Эта директива должна объявляться в основном контексте конфигурационного файла NGINX, обычно в файле `nginx.conf`, до определения контекстов `events` или `http`. Изменения, внесённые этой директивой, вступают в силу только при запуске или перезапуске NGINX. Если процесс уже запущен, изменение этой директивы потребует полной остановки и последующего запуска NGINX для применения. Следует убедиться, что указанный пользователь имеет достаточные права доступа к необходимым файлам, каталогам и ресурсам, таким как журналы или document roots, но не обладает чрезмерно широкими правами, чтобы сохранять принцип наименьших привилегий.

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

user www-data;
user nginx nginx;

Описание

Директива `worker_priority` позволяет задать значение nice для рабочих процессов в NGINX, что помогает влиять на то, как операционная система планирует эти процессы в среде с несколькими ядрами. Значение nice — целое число в диапазоне от -20 (высший приоритет) до 19 (низший приоритет), что позволяет тонко управлять распределением ресурсов CPU между рабочими процессами NGINX. Эта директива особенно полезна в окружениях, где требуется отдавать приоритет обработке веб‑трафика по сравнению с другими системными процессами, обеспечивая более быструю и эффективную реакцию веб‑сервера под нагрузкой. По умолчанию рабочие процессы NGINX наследуют системные настройки приоритета по умолчанию. При установке конкретного приоритета с помощью директивы `worker_priority` вы стремитесь сделать время отклика сервера более предсказуемым и эффективным, снижая вероятность конфликтов с другими процессами, которые могут потреблять ресурсы CPU. Важно учитывать, что установка высокого приоритета для рабочих процессов NGINX может привести к конкуренции за ресурсы с другими системными процессами, поэтому необходимо внимательно оценивать общую нагрузку и требования к системе. При настройке NGINX обязательно проводите тщательное тестирование после изменения параметра `worker_priority`, так как его влияние может значительно различаться в зависимости от нагрузки и архитектуры сервера. Кроме того, не все операционные системы могут поддерживать все значения nice, поэтому рекомендуется обратиться к документации вашей операционной системы, чтобы обеспечить совместимость.

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

worker_priority 10;

Описание

Директива `worker_cpu_affinity` используется в основном контексте для указания, на каких ядрах CPU может выполняться worker-процесс. Это помогает оптимизировать производительность, гарантируя, что worker-процесс работает на заданных ядрах и тем самым избегая переключения контекста и промахов кэша, которые могут возникать при миграции процессов между ядрами. Директива принимает один или несколько аргументов, задающих привязку к ядрам CPU. Это особенно полезно на системах с несколькими ядрами CPU, позволяя максимально использовать ресурсы и минимизировать задержки. Параметры для этой директивы задаются в формате списка CPU, которые могут быть указаны в разных формах, включая одноядерные спецификации (например, '0'), диапазонные спецификации (например, '0-3') или их комбинации. Каждое добавленное значение обозначает допустимые ядра CPU, которые соответствующий worker может использовать. При определении нескольких worker-процессов ядра CPU могут быть распределены между ними, что дополнительно улучшает параллельную обработку. Такая конфигурация помогает поддерживать производительность при высокой нагрузке и может приводить к более предсказуемому времени отклика. Внедрение `worker_cpu_affinity` может потребовать некоторых экспериментов для определения оптимальной конфигурации в зависимости от конкретной нагрузки и архитектуры оборудования. Тщательный мониторинг производительности системы должен направлять эти решения, так как эффективность привязки к ядрам может варьироваться в зависимости от характера нагрузки и числа доступных ядер CPU.

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

worker_cpu_affinity auto;  
# Example with specific core assignment for 4 workers:  
worker_cpu_affinity  0001 0010 0100 1000;

Описание

Директива 'worker_rlimit_nofile' задаёт ограничение на число дескрипторов файлов, которые может открывать рабочий процесс. Это важно для максимизации потенциального числа одновременных подключений или обращений к файлам, которые NGINX может обработать. Когда это ограничение достигается, рабочие процессы не смогут открыть дополнительные файлы или установить новые соединения, что может привести к неудачным запросам или обрывам соединений. Эта директива необходима для сайтов и приложений с высоким трафиком, где значение по умолчанию может быть недостаточным. Установив более высокое значение, администраторы могут оптимизировать производительность и отзывчивость сервера NGINX. Значение задаётся в главном контексте и должно быть настроено с учётом ожидаемого трафика и доступных ресурсов сервера.

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

worker_rlimit_nofile 65536;

Описание

Директива `worker_rlimit_core` используется для задания максимального размера core-файлов, создаваемых рабочими процессами в NGINX. Core-файл — это файл, содержащий снимок памяти работающего процесса в момент его аварийного завершения. Эта директива позволяет администраторам NGINX задать, какого размера могут быть core-дампы для целей отладки и анализа. Значение, указанное в этой директиве, напрямую соответствует настройке `ulimit` для core-дампов, что обеспечивает эффективное управление ресурсами и упрощает поиск и устранение неисправностей в процессе разработки или в производственной среде. Указав ненулевое числовое значение, администратор может настроить предел размера core-файлов в соответствии с требованиями. Однако следует помнить, что установка чрезмерно большого предела размера core-файлов может занять значительное дисковое пространство, особенно в средах с высокой частотой аварий процессов. С другой стороны, установка значения 0 полностью отключает генерацию core-дампов, что может затруднить отладку при возникновении проблем. Как правило, рекомендуется устанавливать предел, который обеспечивает баланс между возможностью получения полезной отладочной информации и эффективным управлением использованием дисковых ресурсов. Директива должна быть определена в основном контексте конфигурационного файла NGINX и обычно задается в глобальном конфигурационном файле, таком как `nginx.conf`. Администраторы должны убедиться, что у них есть соответствующие права для изменения настроек генерации core-файлов, и учитывать ограничения и настройки их операционной системы, касающиеся core-дампов при использовании этой директивы.

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

worker_rlimit_core 512M;

Описание

Директива `worker_shutdown_timeout` в NGINX задаёт длительность (в миллисекундах), в течение которой NGINX будет ожидать плавного завершения рабочих процессов после получения сигнала завершения. Это позволяет рабочим процессам завершить выполняющиеся запросы и освободить ресурсы до принудительного завершения. Это особенно полезно в сценариях, где длительные соединения или большие запросы могут требовать дополнительного времени для завершения обработки. Если рабочий процесс не завершит свои операции в заданный период ожидания, NGINX принудительно завершит эти процессы. Установка слишком низкого значения может привести к прерыванию активных запросов, что повлечёт за собой потенциальную потерю данных или неполные транзакции. Напротив, слишком большое значение может задержать перезапуск или остановку приложения, что повлияет на доступность сервиса во время обслуживания или обновлений. На практике внимательный выбор этого параметра позволяет сбалансировать непрерывность обслуживания и эффективное управление ресурсами при обновлениях или плавных перезапусках.

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

worker_shutdown_timeout 30000;  # Set a 30 seconds timeout for worker shutdown

Описание

Директива `working_directory` в NGINX используется для указания директории, в которой будут работать рабочие процессы. Эта настройка важна, так как определяет директорию по умолчанию для процессов, у которых не задана конкретная рабочая директория при запуске. Задав рабочую директорию, вы обеспечиваете корректное разрешение относительных путей, используемых в конфигурациях или других директивах, относительно этой директории. Данная директива принимает один аргумент — путь к директории, которую вы хотите установить в качестве рабочей среды для рабочих процессов NGINX. Она должна использоваться в основном контексте файла конфигурации NGINX. При запуске рабочие процессы NGINX наследуют эту настройку и используют её для разрешения относительных путей, работы с файлами и ведения логов, а также для других задач, что помогает управлять правами доступа и организовывать хранение файлов. Важно убедиться, что указанная директория доступна процессу NGINX и что для неё заданы соответствующие права доступа. Непредоставление доступной директории может привести к ошибкам в работе NGINX, особенно при обработке файлов, таких как логи или файлы конфигурации, которые зависят от рабочей директории для построения своих путей.

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

working_directory /var/www/html;

Описание

Директива 'env' используется в основном контексте конфигурационного файла NGINX для указания переменных окружения, которые должны быть переданы рабочим процессам. Это особенно полезно для задания значений конфигурации, к которым рабочие процессы могут обращаться во время выполнения, таких как API-ключи, строки подключения к базе данных или другие параметры, которые могут меняться в зависимости от среды развертывания. Синтаксис директивы 'env' прост: она принимает один аргумент, который задаёт имя переменной окружения. Можно указать несколько директив 'env' для задания нескольких переменных, поскольку каждая директива применяется независимо. В базовом C-коде директива 'env' обрабатывается во время фазы запуска NGINX. Указанные переменные добавляются в набор переменных окружения рабочих процессов NGINX, что позволяет обращаться к ним как к обычным переменным окружения. Директива 'env' особенно полезна в сценариях развертывания приложений в контейнеризированных средах (например, Docker) или системах оркестрации (например, Kubernetes), поскольку она дополняет практики управления конфигурацией при развертывании, позволяя легко изменять настройки без изменения кода приложения. Важно отметить, что значения, заданные директивой 'env', не сохранятся при перезагрузках процесса NGINX, если они явно не включены снова в конфигурационный файл. Кроме того, любые изменения переменных окружения в системе после запуска NGINX не вступят в силу, пока процесс NGINX не будет перезапущен. Поэтому понимание того, как эффективно использовать эту директиву, имеет решающее значение для поддержания конфигурации при развертываниях.

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

env MY_DATABASE_USER;
env MY_API_KEY;

Описание

Директива `load_module` позволяет пользователям динамически загружать указанный модуль NGINX без перекомпиляции всего бинарного файла NGINX. Эта директива должна находиться в основном контексте конфигурации и принимает один аргумент: путь к файлу разделяемого объекта модуля (обычно с суффиксом .so). Когда рабочий процесс NGINX запускается, эта директива инструктирует NGINX попытаться загрузить модуль, указанный в её аргументе, что позволяет добавить дополнительную функциональность в сервер без необходимости перезапуска или перекомпиляции. Эта директива может быть критически важна для включения опциональных функций или сторонних модулей, расширяющих базовые возможности NGINX, таких как дополнительные механизмы аутентификации или улучшения производительности. Если модуль зависит от других модулей или разделяемых библиотек, эти зависимости также должны быть удовлетворены во время выполнения для успешной загрузки. Пользователям следует убедиться, что указанный файл модуля доступен и процесс NGINX имеет необходимые права для его загрузки. Если загрузка модуля не удастся, NGINX выдаст ошибку и может отказаться от запуска в зависимости от серьёзности возникшей ошибки. Чтобы эффективно использовать эту директиву, обычно её определяют в основном блоке конфигурации NGINX, который обрабатывается перед остальными настройками. Важно отметить, что все зависимости модуля должны быть разрешены заранее, чтобы избежать ошибок во время выполнения.

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

load_module modules/ngx_http_custom_module.so;

Описание

Директива error_log является основополагающей при настройке поведения логирования в NGINX. Она позволяет администраторам определить один или несколько файлов журнала, в которые будут записываться сообщения об ошибках, включая критические ошибки, предупреждения и информационные сообщения о работе сервера. Директива может принимать различные уровни логирования, такие как "debug", "info", "notice", "warn", "error" и "crit", которые определяют степень серьёзности записываемых сообщений. Журналы помогают в диагностике проблем и мониторинге производительности и надёжности сервера. В самой простой форме директива error_log принимает один аргумент, указывающий путь к файлу журнала. Если она указана несколько раз, NGINX будет записывать сообщения в несколько файлов, каждый из которых может иметь разные уровни логирования. Эта возможность обеспечивает тонкую настройку логирования; например, вы можете отправлять сообщения об ошибках в один файл журнала, а критические сообщения — в другой. По умолчанию уровень логирования установлен в "error", что означает, что будут записываться только сообщения об ошибках и более серьёзные сообщения, если не настроено иначе.

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

error_log /var/log/nginx/error.log warn;

Описание

Директива `pcre_jit` управляет использованием JIT-компиляции (Just-In-Time) для регулярных выражений, обрабатываемых с помощью библиотеки PCRE (Perl Compatible Regular Expressions). Когда JIT включена, регулярные выражения преобразуются в нативный машинный код для повышения производительности при сопоставлении шаблонов, что может существенно ускорить обработку запросов, зависящих от регулярных выражений при сопоставлении location или в директивах сервера. Эта директива доступна в контексте `main` и может быть установлена в значение `on` или `off`. По умолчанию JIT-компиляция отключена (off). Однако при включении она может повысить эффективность операций NGINX, использующих регулярные выражения, особенно при высокой нагрузке. Важно убедиться, что установленная в системе библиотека PCRE поддерживает JIT-компиляцию, так как не все сборки PCRE включают эту возможность. При использовании директивы `pcre_jit` администраторам следует учитывать, что хотя она может улучшить производительность, она также может привести к увеличению потребления памяти из-за хранения скомпилированных шаблонов регулярных выражений. Кроме того, в отдельных случаях сложные регулярные выражения могут вызывать проблемы совместимости; поэтому рекомендуется тщательно протестировать конфигурации после включения этой директивы.

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

pcre_jit on;

Описание

Директива `thread_pool` используется для определения пула потоков, который позволяет NGINX передавать обработку асинхронных запросов потокам, что может улучшить производительность за счёт более эффективного использования многоядерных процессоров. Эта директива принимает два-три аргумента: имя пула потоков, размер пула и необязательный параметр размера стека потока. Параметры позволяют тонко настроить ресурсы, выделяемые для обработки одновременных подключений с помощью потоков, помогая сбалансировать распределение нагрузки по ресурсам сервера. Когда директива `thread_pool` задана, NGINX создаёт указанное количество потоков в пуле, которые могут использоваться для задач, зависящих от ввода-вывода (I/O) или требующих блокирующих операций. Потоки управляются независимо от рабочих процессов, что позволяет эффективно выполнять операции без блокировки основного цикла событий. Это особенно полезно в сценариях, таких как скрипты на Lua, загрузки файлов или другие долгие операции, которые обычно замедляют работу при обработке непосредственно в рабочем процессе. Необязательный параметр размера стека определяет объём стека, выделяемого для каждого потока, что может быть критично при глубокой рекурсии или операциях с большой нагрузкой на стек. Важно тщательно управлять размером пула потоков и количеством рабочих процессов, так как слишком большое число потоков может привести к избыточному переключению контекста, снижению отдачи в производительности и, в конечном итоге, к исчерпанию ресурсов.

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

thread_pool my_pool 32;

Описание

Директива `devpoll_changes` в NGINX используется для настройки того, сколько файловых дескрипторов может одновременно отслеживаться на предмет событий при применении метода событий devpoll. Эта техника особенно полезна в средах, где может быть большое число одновременных соединений, например на высоконагруженных веб‑серверах. Установка адекватного значения позволяет NGINX эффективно обслуживать большее количество соединений, не сталкиваясь с ограничениями, которые могут ухудшить производительность. Параметром для директивы `devpoll_changes` является одно целое число, определяющее максимальное число событий, которое должно быть возвращено при каждом системном вызове. Если этот предел достигается, любые дополнительные изменения не будут обработаны до тех пор, пока не освободится место. Фактическое поведение директивы может существенно влиять на эффективность сетевых операций и обработку клиентов, особенно в системах с высокой степенью параллельности. Неправильная настройка может привести к перерасходу ресурсов или потере соединений. При настройке этого параметра важно учитывать возможности системы и ожидаемую нагрузку, чтобы добиться оптимальной производительности. Убедиться, что это значение соответствует характеристикам окружения (например, доступной памяти и CPU), поможет максимально увеличить пропускную способность сервера.

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

events {
    devpoll_changes 1024;
}

Описание

Директива `devpoll_events`, когда указана в контексте `events`, включает механизм DEVPOLL для обработки соединений в событийно-ориентированной архитектуре NGINX. DEVPOLL, доступный в Solaris и в вариантах других Unix-подобных систем, предлагает масштабируемый способ обработки большого числа одновременных соединений. Используя DEVPOLL, NGINX может эффективно мониторить и реагировать на события на файловых дескрипторах без необходимости выполнения O(n) линейных сканирований, которые могут стать узким местом в других моделях событий, таких как select() или poll(). Эта директива не принимает аргументов и обычно используется для оптимизации производительности серверных приложений при высокой нагрузке. Она позволяет рабочим процессам переходить в спящий режим и реактивно обрабатывать входящие соединения или другие события, что способствует лучшему использованию CPU и показателям производительности за счёт уменьшения переключений контекста и повышенной общей отзывчивости системы. В основном это приносит пользу в окружениях, где ожидается значительное число одновременных соединений, например веб-серверам, обслуживающим тысячи пользователей.

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

events {
    devpoll_events;
}

Описание

Директива `epoll_events`, используемая в контексте `events` в NGINX, позволяет администраторам указывать количество и типы событий, которые должен обрабатывать механизм epoll. Она повышает производительность и масштабируемость NGINX при одновременной обработке большого числа подключений за счёт оптимизации порядка очередности и обработки событий. Директива принимает один аргумент, определяющий, как должны управляться события. Используя возможности epoll, NGINX может обеспечить неблокирующий ввод-вывод, одновременно эффективно управляя обратными вызовами для операций чтения и записи, тем самым уменьшая задержку и увеличивая пропускную способность. При настройке `epoll_events` пользователи могут изменять такие параметры, как максимальное число дескрипторов файлов или конкретные маски событий, которые задают условия, при которых дескрипторы будут инициировать обратные вызовы. Такая настройка особенно полезна в средах с высокой нагрузкой и большим количеством одновременных подключений, где тонкая настройка модели обработки событий может привести к заметному приросту производительности. Пользователям следует быть знакомыми с интерфейсом epoll в Linux, а также с последствиями различных конфигураций для использования системных ресурсов и поведения приложения. Таким образом, директива обеспечивает тонкую настройку асинхронной обработки событий, что способствует репутации NGINX как быстрого и эффективного веб-сервера. Использование директивы `epoll_events` обычно возникает в сценариях, где от NGINX ожидается обработка большого числа одновременных соединений, например в высоконагруженных веб-приложениях, где оптимизация цикла событий может помочь поддерживать отзывчивость и производительность под нагрузкой.

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

events {
    epoll_events 1024;
}

Описание

Директива 'worker_aio_requests' используется в контексте 'events' для указания ограничения на число одновременных асинхронных I/O (AIO) запросов, которые может обрабатывать каждый рабочий процесс NGINX. Эта директива особенно полезна в сценариях, где NGINX используется для передачи статических файлов или эффективной обработки больших медиафайлов с помощью асинхронных механизмов. Устанавливая эту директиву, администраторы могут лучше управлять использованием ресурсов рабочих процессов и оптимизировать производительность в зависимости от возможностей сервера и характера нагрузки.\n\nЗначение должно быть положительным целым числом, указывающим максимальное количество AIO-запросов, которые рабочий процесс может поставить в очередь. Если рабочий процесс превысит это число, он не сможет принимать новые AIO-запросы до завершения части поставленных в очередь запросов. Эта директива помогает настраивать производительность приложений NGINX, активно использующих асинхронные файловые операции, находя баланс между пропускной способностью и потреблением ресурсов. Поэтому значение должно определяться исходя из конкретной нагрузки и результатов тестирования, чтобы обеспечить оптимальную производительность без перегрузки рабочих процессов.\n\nПоведение 'worker_aio_requests' может существенно влиять на время отклика сервера и общую пропускную способность, особенно в сценариях с высокой нагрузкой. Поэтому важно мониторить производительность сервера и при необходимости корректировать это значение в зависимости от требований приложения и возможностей аппаратного обеспечения.

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

events {
    worker_aio_requests 1024;
}

Описание

Директива 'eventport_events' в NGINX предназначена для задания поведения event ports, используемых в модели обработки событий. Она в первую очередь применяется в системах, которые поддерживают event port API, позволяя более эффективно выполнять event-driven I/O за счёт масштабируемого способа обработки подключений. Эта директива даёт пользователям возможность оптимизировать свой event loop для повышения производительности, особенно в сценариях с высокой конкурентностью. При указании директивы 'eventport_events' NGINX использует механизм event port операционной системы, что может значительно повысить производительность за счёт одновременной обработки множества событий. Это особенно полезно в средах с большим числом одновременных соединений, поскольку уменьшает накладные расходы на управление многочисленными отдельными потоками или процессами. Параметры, связанные с этой директивой, как правило, включают опции для настройки таймаутов и других связанных свойств, позволяющих подбирать производительность по мере необходимости. Наличие этой директивы следует тщательно обдумывать, поскольку она может повлиять на общую масштабируемость и отзывчивость веб-сервера. Корректная настройка её параметров может привести к существенному улучшению пропускной способности и времени отклика для приложений с высокой нагрузкой.

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

events {
    eventport_events;
}

Описание

Директива `iocp_threads` специфична для runtime NGINX на Windows и позволяет настраивать, сколько потоков выделяется для обработки завершения I/O с использованием модели IOCP (I/O Completion Ports). Эта модель обеспечивает масштабируемый подход к обработке множества одновременно выполняемых I/O-операций, что особенно полезно для высокопроизводительных нагрузок. По умолчанию число потоков устанавливается равным числу ядер CPU, но его можно явно задать для оптимизации производительности в зависимости от потребностей приложения. Каждый поток завершения I/O работает независимо, обрабатывая завершённые I/O-запросы по сигналу завершения, что позволяет лучше использовать системные ресурсы. При использовании `iocp_threads` администраторам следует учитывать связь между числом потоков и ожидаемой нагрузкой. Небольшое число потоков может привести к узким местам при высокой нагрузке, тогда как чрезмерно большое — к издержкам переключения контекста. Поэтому рекомендуется проводить тестирование производительности, чтобы определить оптимальную конфигурацию. Кроме того, эта директива эффективна прежде всего на платформах Windows, где используется модель IOCP, и не влияет на Linux или другие операционные системы, которые не реализуют эту модель. Директива определяется в контексте 'events' конфигурации NGINX, где располагается большинство настроек, связанных с производительностью.

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

events {
    iocp_threads 4;
}

Описание

Директива 'post_acceptex' — это параметр конфигурации, который позволяет пользователям определить пользовательскую функцию, выполняемую после успешной операции accept в цикле обработки событий NGINX. Это особенно полезно для расширения поведения обработки соединений после их принятия. Указывая функцию, разработчики получают более тонкий контроль над обработкой соединений в специализированных сценариях, например для логирования деталей соединения или динамического изменения настроек соединения. Директива принимает один аргумент — имя функции, которую вызовет NGINX. Эта функция должна соответствовать ожидаемой сигнатуре, которую NGINX способен распознать и корректно выполнить. Это обеспечивает гибкий механизм для разработчиков и системных администраторов, позволяющий адаптировать конфигурации NGINX под конкретные нужды. Кроме того, поскольку это выполняется на низком уровне внутри модуля обработки событий, оно может быть очень эффективным и позволять настраиваемое поведение без значительных накладных расходов. На практике определение функции 'post_acceptex' включает не только реализацию самой функции, но и обеспечение её корректного взаимодействия с другими частями архитектуры NGINX. Правильная реализация может открыть доступ к расширенным возможностям, таким как обработка уникальных протоколов, пользовательское логирование или интеграция с внешними службами сразу после установления соединения.

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

events {
    post_acceptex my_custom_accept_function;
}

Описание

Директива `acceptex_read` в NGINX используется внутри контекста `events` для управления тем, использует ли NGINX функцию сокета AcceptEx при принятии входящих соединений. AcceptEx — это Windows-специфичное API, которое позволяет серверу сразу читать входящее соединение, снижая количество переключений контекста и повышая производительность. При установке в 'on' NGINX будет пытаться использовать эту возможность для принятия соединений, что при высоких нагрузках может дать более высокую производительность благодаря эффективности обработки сокетов. Однако эта функция применима только на платформах Windows, где поддерживается AcceptEx.\n\nПараметр для этой директивы — флаг, который может быть 'on' или 'off'. Если установить его в 'on', NGINX будет использовать функцию AcceptEx при обработке новых соединений. Соответственно, установка в 'off' означает использование обычного метода принятия соединений. Важно учитывать, что использование AcceptEx может повысить производительность, но также привести к проблемам совместимости с некоторыми сетевыми конфигурациями, что может повлиять на поведение приложения.\n\nОценка нагрузок сервера, типов обрабатываемого трафика и базовой инфраструктуры поможет принять решение о включении этой опции. Следует отметить, что эта функция специфична для Windows и не будет иметь эффекта на установках NGINX, не являющихся Windows. Необходимо провести соответствующее тестирование, чтобы убедиться, что включение AcceptEx не приведёт к нежелательным побочным эффектам в среде.

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

events {
    acceptex_read on;
}

Описание

Директива `kqueue_changes` используется в контексте обработки событий в NGINX и специально оптимизирует производительность при использовании механизма событий kqueue, характерного для операционных систем BSD-подобного типа, включая macOS. Эта директива позволяет задавать максимальное число изменений, которые могут быть поставлены в очередь при мониторинге файловых дескрипторов, что помогает тонко настроить отзывчивость сервера NGINX при высокой нагрузке. Параметр задаёт предел того, сколько ожидающих изменений файловых дескрипторов может быть обработано одновременно, что может влиять на эффективность обработки подключений в периоды пикового трафика. При установке этой директивы важно учитывать типы приложений, работающих на сервере, и ожидаемую нагрузку. Более низкое значение может привести к пропуску событий при высокой нагрузке, тогда как более высокое значение может потреблять больше памяти и вычислительных ресурсов. Важно найти баланс между этими аспектами для обеспечения оптимальной производительности. Например, если ваше приложение часто добавляет или удаляет файловые дескрипторы из мониторинга, имеет смысл увеличить это значение, чтобы выдерживать более высокие темпы входящих подключений. Эффективное управление этим параметром может привести к улучшению производительности, особенно для приложений, испытывающих всплески запросов на подключение, превышающие обычную нагрузку. NGINX по умолчанию использует разумное значение, подходящее для многих сценариев, но администраторы могут настраивать значение `kqueue_changes` в зависимости от специфики поведения и требований приложения, что может привести к повышению производительности или снижению риска переполнения очереди событий.

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

events {
    kqueue_changes 256;
}

Описание

Директива kqueue_events специально предназначена для использования в контексте events конфигурации NGINX. Она указывает NGINX использовать механизм уведомлений о событиях kqueue, который очень эффективен и особенно подходит для обработки большого количества одновременных соединений на ОС, совместимых с BSD, таких как FreeBSD и macOS. Благодаря использованию kqueue, NGINX может активно отслеживать несколько file descriptors, уменьшая нагрузку на CPU, связанную с polling, и обеспечивая более масштабируемую производительность под нагрузкой. Когда директива kqueue_events включена, это влияет на то, как worker processes обрабатывают события, позволяя им пробуждать простаивающие соединения только при наличии реального события, например при поступлении данных или закрытии соединения. Это контрастирует со старыми механизмами обработки событий, которые могли требовать периодического опроса, что при росте числа соединений приводит к расходованию ресурсов. Важно убедиться, что ваша установка NGINX скомпилирована с поддержкой kqueue, поскольку эта директива не будет работать, если базовая OS или build не поддерживают kqueue. Эта директива принимает один аргумент, который служит для переключения использования kqueue. При правильной настройке преимущества включают более низкое потребление ресурсов и повышенную скорость за счёт более быстрой обработки событий. Необходимо протестировать конфигурацию в тестовой среде, чтобы убедиться, что она работает как ожидалось и не вводит непредвиденных проблем.

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

events {
    kqueue_events;
}

Описание

Директива events является ключевым компонентом архитектуры NGINX, управляющим тем, как сервер обрабатывает подключения. Она позволяет NGINX использовать событийно-ориентированную модель, что значительно повышает производительность и масштабируемость за счёт способности обрабатывать множество подключений с меньшими затратами ресурсов по сравнению с традиционными многопоточными подходами. В блоке events можно задать различные параметры для оптимизации обработки подключений, например параметр worker_connections, который определяет максимальное число одновременных подключений, которые может обрабатывать каждый рабочий процесс. Сама директива не принимает аргументов, но служит контейнером для опций конфигурации, влияющих на цикл событий NGINX. Наиболее заметный параметр, который можно настроить в блоке events, — это 'worker_connections', задающий максимальное число подключений на один рабочий процесс. Тщательная настройка этих параметров позволяет администраторам достичь оптимального использования ресурсов и отклика, соответствующих нагрузке сервера.

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

events {
    worker_connections 1024;
}

Описание

Директива worker_connections имеет ключевое значение для оптимизации числа одновременных соединений, обрабатываемых каждым рабочим процессом в NGINX. Эта директива по сути определяет верхний предел соединений, который может обслуживать один рабочий процесс, тем самым влияя на общую масштабируемость веб-сервера. При определении значения этой директивы важно учитывать доступные ресурсы на вашем сервере, включая память, CPU и пропускную способность сети. Для максимальной эффективности значение worker_connections следует настраивать совместно с директивой worker_processes. Общее потенциальное число соединений, которое может обрабатывать NGINX, можно вычислить как `worker_processes * worker_connections`. Точная настройка этих параметров позволяет эффективно контролировать, сколько клиентов может одновременно подключаться и взаимодействовать с вашими приложениями. В условиях высокой нагрузки установка этого значения слишком высокой может привести к исчерпанию ресурсов и ухудшению производительности сервера. Мониторинг и корректировка этой директивы на основе шаблонов трафика помогут поддерживать оптимальное состояние сервера.

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

events {
    worker_connections 1024;
}

Описание

Директива 'use' позволяет пользователю указать метод обработки событий, который NGINX будет использовать при обработке соединений. В зависимости от платформы и модулей, скомпилированных в NGINX, эта директива поддерживает различные варианты реализации событийно-ориентированной архитектуры, например использование методов `epoll`, `kqueue` или `select`. Каждый вариант даёт разные характеристики производительности и масштабируемости в зависимости от операционной среды сервера.\n\nДиректива принимает один аргумент, задающий требуемый метод. Корректное использование гарантирует, что NGINX сможет эффективно обрабатывать множество одновременных соединений, оптимизируя использование ресурсов и повышая общую пропускную способность. Важно выбрать подходящий метод, соответствующий возможностям операционной системы сервера; например, 'epoll' рекомендуется для систем Linux, тогда как 'kqueue' предпочтителен в системах BSD.\n\nНеправильная конфигурация, например указание неподдерживаемого метода обработки событий для конкретной платформы, может привести к ошибкам при запуске или существенно ухудшить производительность. Понимание компромиссов и возможностей каждого метода обработки событий имеет важное значение при развертывании NGINX в рабочей среде.

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

events {
    use epoll;
}

Описание

Директива `multi_accept` в NGINX используется для оптимизации процесса обработки соединений, позволяя рабочему процессу принимать несколько новых соединений одновременно, а не по одному. Когда эта директива включена, рабочий процесс может повысить пропускную способность за счёт уменьшения накладных расходов, связанных с переключением контекста, и снижения задержки при обработке отдельных соединений. Эту директиву можно установить в значение `on` или `off`. При установке в `on` она инструктирует рабочие процессы принимать столько новых соединений, сколько позволяет уровень сокетов операционной системы. Такое поведение особенно полезно в условиях высокой нагрузки, когда ожидается большое количество одновременных соединений. С другой стороны, при значении `off` поведение по умолчанию — принимать только одно соединение за раз. Это может приводить к увеличению задержки для входящих соединений, поскольку последующие подключения должны ждать, пока рабочий процесс освободится для их обработки. Важно учитывать, что включение `multi_accept` не гарантирует улучшения производительности во всех ситуациях. Выгоды в значительной степени зависят от того, как базовая операционная система обрабатывает операции с сокетами и от конкретных условий нагрузки на сервер. Администраторам серверов следует контролировать производительность, чтобы определить, приносит ли включение этой директивы ожидаемые результаты.

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

events {
    multi_accept on;
    worker_connections 1024;
}

Описание

Директива `accept_mutex` в NGINX используется для улучшения производительности событийных серверов за счёт управления тем, как рабочие процессы обрабатывают входящие соединения при высокой нагрузке на сервер. Когда она установлена в `on`, директива позволяет только одному рабочему процессу принимать новое соединение за раз, что снижает конкуренцию за ресурсы и повышает эффективность их использования. Это особенно полезно в ситуациях, когда количество одновременных соединений превышает вычислительную способность отдельных рабочих процессов, поскольку помогает предотвратить эффект «thundering herd», когда несколько процессов одновременно пытаются принять новые соединения. Директива `accept_mutex` опирается на параметр `accept_mutex_delay`, который задаёт задержку (в миллисекундах), в течение которой рабочий процесс должен ждать, прежде чем попытаться принять новое соединение, если доступны другие рабочие процессы. При правильной настройке эта задержка обеспечивает синхронизацию между рабочими процессами, уменьшая вероятность перегрузки доступных ресурсов. Синхронизация достигается за счёт того, что одному рабочему предоставляется «право» принять новое входящее соединение, в то время как другие ждут своей очереди. Оптимальная конфигурация может значительно варьироваться в зависимости от нагрузки на сервер и базовой инфраструктуры.

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

events {
    accept_mutex on;
    accept_mutex_delay 500;
}

Описание

Директива 'accept_mutex_delay' в NGINX задает задержку, применяемую, когда рабочий процесс пытается принять новое соединение, но не может сразу получить accept mutex. Этот mutex необходим для синхронизации доступа между несколькими рабочими процессами, чтобы не перегрузить сервер быстрыми запросами на соединение. Если рабочий процесс не может получить этот mutex, он приостановится на время, указанное в этой директиве, прежде чем вновь пытаться принимать соединения, что позволяет равномерно распределять нагрузку между рабочими и повышать эффективность. Параметр для 'accept_mutex_delay' задается в миллисекундах, что позволяет администраторам тонко настраивать задержку в зависимости от возможностей сервера и ожидаемой нагрузки. Например, установка 'accept_mutex_delay 500;' позволяет рабочему процессу ждать до полусекунды перед повторной попыткой. Эта настройка может существенно влиять на распределение соединений между несколькими рабочими процессами, особенно в условиях высокой конкурентности. Правильная настройка может максимизировать пропускную способность и снизить задержки, одновременно минимизируя конкуренцию за ресурсы. Важно отметить, что увеличение задержки может улучшить справедливость распределения при высокой нагрузке, позволяя другим рабочим процессам принимать соединения, но также может привести к меньшему числу принимаемых соединений при низкой нагрузке, поэтому значение следует устанавливать исходя из реальных моделей трафика.

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

events {
    accept_mutex on;
    accept_mutex_delay 300;
}

Описание

Директива `debug_connection` позволяет указать IP addresses, из которых входящие подключения будут записываться в debug log. Эта директива необходима при устранении неполадок в экземпляре NGINX, так как она предоставляет подробное представление о обработке запросов от назначенных клиентов. По умолчанию, без этой директивы, никакие IPs не получат расширенного логирования, что критично для эффективной отладки. При использовании этой директивы указанный IP может быть одиночным IP address или задан в CIDR notation для подсетей, что делает её гибкой в различных сетевых сценариях. Директива должна быть размещена в контексте `events` конфигурации NGINX, поскольку она связана с обработкой подключений. Детальные логи будут содержать не только стандартную информацию о запросах, но и дополнительные отладочные сведения, которые помогают системным администраторам выявлять неверные настройки или аномалии в подключениях. Важно учитывать, что большое количество debug connections может приводить к образованию больших файлов логов, которые потребуют управленческих мер при включении в рабочей среде. Поэтому эта директива обычно используется временно при диагностике конкретных проблем для ограниченного круга пользователей, а не для всего входящего трафика. В заключение, директива `debug_connection` предоставляет мощный инструмент для выборочного усиления логирования для конкретных клиентских подключений, что позволяет более эффективно выполнять отладку и мониторинг системы.

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

events {
    debug_connection 192.168.1.0/24;
}

Описание

'ssl_engine' директива позволяет пользователям определить, какой SSL-движок NGINX должен использовать для обработки защищённых соединений. По умолчанию NGINX использует библиотеку OpenSSL, если не настроено иное. Эта директива может быть полезна в ситуациях, когда пользователь хочет использовать другую реализацию SSL, такую как GnuTLS, или пользовательскую SSL-библиотеку для расширенных возможностей или повышения производительности. Директива принимает только один аргумент, который соответствует имени желаемого SSL-движка. При использовании директивы важно, чтобы указанный SSL-движок был скомпилирован в NGINX, иначе команда завершится с ошибкой во время выполнения, что может привести к ошибкам при запуске. Такая гибкость позволяет системным администраторам тонко настраивать обработку NGINX запросов SSL/TLS в зависимости от их инфраструктуры или требований приложения. Пользователям следует всегда проверять совместимость выбранного SSL-движка с текущей конфигурацией NGINX, а также его производительность и возможности безопасности.

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

ssl_engine 'openssl';

Описание

Директива `ssl_object_cache_inheritable` — это флаг, управляющий наследованием настроек кэша объектов SSL в NGINX. Когда эта директива установлена в 'on', она позволяет наследовать настройки кэша объектов SSL дочерним контекстам, таким как блоки server или location, обеспечивая более гибкое и централизованное управление поведением кэширования SSL. Это особенно полезно в сложных конфигурациях, где несколько серверных блоков должны использовать одни и те же настройки кэша объектов SSL. По умолчанию механизмы кэширования SSL повышают производительность, сохраняя параметры и объекты SSL-сессий, снижая тем самым накладные расходы при установлении новых SSL-соединений. Возможность наследования этих настроек позволяет разработчикам не дублировать параметры кэша в разных блоках, упрощая процесс конфигурирования и минимизируя возможные ошибки, которые могут возникнуть из-за несогласованных настроек. Если `ssl_object_cache_inheritable` опущена, поведение по умолчанию не допускает наследование, сохраняя прежнее поведение, при котором настройки кэша нужно явно задавать в каждом соответствующем блоке. Эта директива особенно важна в средах, где производительность SSL критична, так как обеспечивает единую стратегию кэширования в разных конфигурациях сервера.

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

ssl_object_cache_inheritable on;

Описание

Директива 'quic_bpf' используется в основном модуле NGINX для управления тем, включен ли механизм BPF для обработки пакетов QUIC. BPF — это мощная функция, которая позволяет фильтровать и обрабатывать сетевые пакеты на низком уровне, обеспечивая эффективную обработку для протокола QUIC, разработанного для улучшения производительности веба за счёт уменьшения задержек и лучшего управления перегрузкой. Используя BPF, NGINX может анализировать шаблоны трафика и принимать более обоснованные решения в реальном времени, тем самым повышая производительность приложений, использующих протокол QUIC. Директива принимает аргумент-флаг, который может быть установлен в 'on' или 'off'. При значении 'on' NGINX будет применять BPF ко всем входящим QUIC-соединениям, что может увеличить пропускную способность и снизить задержки за счёт более эффективной обработки исходящих и входящих пакетов. Напротив, установка 'off' отключает эту функцию, возвращая стандартную обработку пакетов QUIC без оптимизаций BPF. Следует отметить, что для эффективной работы BPF NGINX должен быть скомпилирован с необходимыми библиотеками, поддерживающими эту возможность, а также базовая операционная система должна поддерживать BPF.

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

quic_bpf on;

Описание

Директива 'http' является фундаментальным компонентом конфигурации NGINX, предоставляя контекст для настройки параметров, специфичных для HTTP. При определении эта директива инкапсулирует все остальные директивы, связанные с HTTP, которые задают поведение веб-сервера при обработке запросов и ответов. Это включает настройки для блоков server, location, логирования и прочего, позволяя администраторам определять, как входящие HTTP-запросы обрабатываются в разных контекстах и конфигурациях сервера. В пределах контекста 'http' администраторы могут задавать параметры, такие как блоки 'server', что позволяет реализовывать настройки виртуального хостинга, а также настраивать протокол, поведение буферизации и средства контроля доступа. Такая структура обеспечивает детальный контроль над поведением сервера, позволяя применять оптимизации и настройки на высоком уровне, влияющие на все настроенные серверы или на выборочные блоки. Отсутствие параметров у этой директивы также означает, что она служит исключительно организационной границей и не требует специальных опций для работы. Использование директивы 'http' означает, что последующие директивы, определённые в её области, относятся к обработке HTTP. Например, директивы, такие как 'server', 'location' и 'client_max_body_size', часто находятся вложенными в блок 'http', что демонстрирует её роль как точки сбора связанных настроек и в конечном счёте влияет на общую производительность и гибкость веб-сервера NGINX.

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

http {
    server {
        listen 80;
        server_name example.com;
        location / {
            root /var/www/html;
            index index.html;
        }
    }
}

Описание

The 'mail' directive in NGINX is pivotal for enabling the mail processing functionalities provided by the mail module. When declared at the main context of the configuration, it activates the capability for NGINX to act as a mail proxy server, handling protocols such as IMAP, POP3, and SMTP. This directive does not accept any parameters or arguments; its mere presence in the configuration indicates that mail functionalities should be included in the NGINX operations. Upon initializing, the mail module configures its settings based on additional, related mail-specific directives that follow the 'mail' directive in the configuration file. These include directives that define server and user credentials, authentication methods, and upstream servers. It is notable that this directive alone does not process any mail; rather, it sets the groundwork for subsequent configurations that specify how NGINX should interface with mail clients and mail servers. The directive plays a critical role in ensuring that NGINX can effectively manage and forward email requests, interacting seamlessly with existing mail infrastructure. By integrating mail protocols, NGINX extends its versatility beyond static and dynamic web content serving to include robust email handling capabilities, which can be especially beneficial in load-balanced environments or when consolidating multiple services into a unified architecture.

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

mail {
    server {
        listen 110;
        protocol pop3;
        proxy on;
    }
    server {
        listen 143;
        protocol imap;
        proxy on;
    }
}

Описание

Директива `google_perftools_profiles` располагается в конфигурации ядра NGINX и используется для включения сбора информации профилирования с помощью Google Performance Tools (gperftools). Такое профилирование полезно для мониторинга и анализа производительности процессов NGINX, позволяя администраторам выявлять узкие места в производительности и оптимизировать конфигурации соответствующим образом. Когда эта директива включена, NGINX будет генерировать информацию профилирования, которую можно анализировать с помощью инструментов, таких как 'pprof'. Конкретно, директива принимает один аргумент — путь к файлу вывода, в котором должны сохраняться данные профилирования. Эта информация включает использование процессора, статистику распределения памяти и графы вызовов, которые дают представление о работе рабочих процессов NGINX. Тщательно изучая сгенерированные профили, можно выявлять и устранять проблемы с производительностью, что приводит к улучшению производительности и использованию ресурсов сервера NGINX. Директива должна располагаться в основном контексте конфигурации NGINX и принимать в качестве аргумента корректный путь. Если указанный путь недоступен для записи рабочими процессами NGINX, профилирование не будет включено, что может привести к вводящим в заблуждение выводам о производительности. Часто она применяется вместе с другими директивами производительности для получения всестороннего понимания состояния сервера.

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

google_perftools_profiles /var/log/nginx/perf_data;

Описание

Директива 'stream' позволяет NGINX обрабатывать не-HTTP трафик, обеспечивая работу с потоками TCP и UDP. Эту директиву можно настроить в main context, что позволяет пользователям указывать разные servers или upstreams для различных типов потоковых данных. Внутри 'stream' блока пользователи могут определять несколько server blocks, где каждый server может обрабатывать разные протоколы, порты или конфигурации upstream, отличные от обычной обработки HTTP. С введением этой директивы пользователи могут использовать различные директивы, такие как 'server' и 'proxy_pass', внутри контекста 'stream' для обработки потоков. Например, TCP load balancing может быть настроен прямо в этом блоке, что смещает использование ресурсов в пользу разных backend servers на основе алгоритмов, таких как round-robin, least connections или IP hash. Кроме того, можно настроить лимиты соединений, таймауты и обработку ошибок, чтобы обеспечить эффективную и отказоустойчивую обработку потоков. Директива 'stream' открывает NGINX как более универсальный прокси, помогая в таких задачах, как SSL termination для TCP services, что упрощает защищённую передачу. В результате это расширяет круг применений за пределами стандартной парадигмы HTTP/HTTPS, позволяя, например, базам данных и игровым серверам использовать возможности NGINX для эффективного управления своей сетевой функциональностью.

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

stream {
    upstream backend {
        server backend1.example.com:12345;
        server backend2.example.com:12345;
    }

    server {
        listen 12345;
        proxy_pass backend;
    }
}

Описание

Директива 'include' предназначена для повышения модульности и удобства сопровождения конфигурации NGINX путем включения других файлов конфигурации. Это помогает разбивать большие файлы конфигурации на управляемые части, облегчая их обновление и организацию. Используя директиву 'include', пользователи могут определить общие настройки в отдельном файле и включать их там, где это необходимо в разных контекстах конфигурации, способствуя принципу DRY (Don't Repeat Yourself). Аргумент для директивы 'include' состоит из пути к одному или нескольким файлам конфигурации. Путь может быть указан как абсолютный или как относительный путь от текущего рабочего каталога. Поддерживаются также подстановочные символы, позволяющие включать несколько файлов, соответствующих заданному шаблону. Когда NGINX обрабатывает основной файл конфигурации, он разрешает и читает файлы, указанные в директиве 'include', в том порядке, в котором они указаны. Директивы внутри этих файлов затем объединяются с текущим контекстом, позволяя им соответствующим образом влиять на настройки конфигурации. Файлы конфигурации, включаемые с помощью этой директивы, могут определять различные аспекты NGINX, такие как блоки location, настройки server или конфигурации upstream. Однако следует соблюдать осторожность, чтобы избежать конфликтов с уже существующими настройками в основном файле конфигурации. Если включённый файл содержит директивы, которые изменяют уже определённые настройки, последнее определённое значение в объединённой конфигурации будет иметь приоритет. Такая гибкость делает директиву 'include' мощным инструментом для эффективной структуризации сложных конфигураций NGINX.

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

# Example of using the 'include' directive
include /etc/nginx/conf.d/*.conf;

Описание

Директива 'allow' указывает, каким IP-адресам предоставляется доступ к указанному server или location block. Она может принимать как IPv4, так и IPv6-адреса, а также CIDR Notation для указания диапазонов IP-адресов. Когда присутствует несколько директив 'allow', их можно комбинировать для более тонкого контроля доступа к ресурсу. Если запрос поступил с IP-адреса, который совпадает с одним из правил 'allow', ему предоставляется доступ, если только он не соответствует также директиве 'deny'. Такая настройка позволяет включать в белый список конкретные адреса клиентов, одновременно блокируя или ограничивая доступ для остальных. Директиву 'allow' обычно используют вместе с директивой 'deny', которая указывает, какие IP-адреса следует блокировать. Директива может быть настроена в различных контекстах, таких как http, server, location и limit_except, что даёт гибкость в применении правил доступа в зависимости от архитектуры приложения. При конфигурации обработка запроса определяется порядком проверки: если существуют какие-либо правила 'allow', они проверяются до правил 'deny'. Параметром, передаваемым директиве 'allow', может быть одиночный IP-адрес или CIDR block, который представляет собой диапазон адресов, указанный в формате "192.168.1.0/24". Например, 'allow 192.168.1.1;' разрешит доступ с конкретного IP 192.168.1.1, тогда как 'allow 10.0.0.0/8;' позволит всем IP из диапазона 10.0.0.0 — 10.255.255.255.

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

location /protected {
    allow 192.168.1.1;
    deny all;
}

Описание

Директива 'deny' в NGINX используется для управления доступом к ресурсам сервера на основе IP address клиента. Она может быть определена в нескольких контекстах, включая http, server, location и limit_except, что даёт гибкость при описании правил доступа. Директива требует одного аргумента — это IP address (или нотация CIDR) клиентов, которым будет отказано в доступе. Когда запрос поступает с IP address, который соответствует правилу 'deny', NGINX вернёт 403 Forbidden HTTP status code, предотвращая дальнейшую обработку запроса. Эта директива может использоваться совместно с директивой 'allow', которая указывает, каким IP address предоставляется доступ. В случаях, когда обе директивы используются, NGINX оценивает правила в том порядке, в котором они определены, и если найдётся совпадающее deny-правило, запрос будет отклонён независимо от последующих allow-правил. Кроме того, директива deny может задавать отказ как для IPv4, так и для IPv6 адресов, что делает её адаптируемой к разным сетевым ситуациям.

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

location /protected {
    deny 192.168.1.0/24;
    deny 10.0.0.1;
}

Описание

Директива `add_before_body` используется в модуле NGINX HTTP core для добавления определённого содержимого перед тем, как тело ответа будет отправлено клиенту. Это особенно полезно для внедрения скриптов, заметок или другой разметки непосредственно в полезную нагрузку ответа без изменения приложения или бэкенд‑сервера. Вставляемое содержимое может задаваться как строковый литерал, который выводится в составе HTTP-ответа во время фазы обработки запроса. Директиву можно задавать в таких контекстах, как `http`, `server` и `location`, что позволяет тонко контролировать места вставки содержимого. Аргумент этой директивы — единое строковое значение, обозначающее добавляемое содержимое. После настройки `add_before_body` обрабатывает запрос на этапе вывода, гарантируя, что указанное содержимое предшествует исходному телу ответа. Поскольку это изменяет структуру ответа, важно убедиться, что вставляемое содержимое не нарушает тип или структуру содержимого ответа. Следует тщательно продумать добавляемое содержимое, чтобы сохранить корректное форматирование HTTP-ответа.

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

http {
    server {
        location /example {
            add_before_body '';
        }
    }
}

Описание

Директива `add_after_body` используется в NGINX для определения контента, который должен быть включён в конец HTTP-ответа, после того как тело ответа было передано. Это может быть полезно для внедрения скриптов, трекеров или кодов аналитики, либо любых дополнительных данных, которые должны загружаться после того, как основной контент был доставлен клиенту. Директива принимает один аргумент — контент, который будет добавлен. Этот контент может быть простым текстом, HTML или любым допустимым фрагментом данных, который сервер может отдать клиенту. Она особенно полезна для веб-приложений, зависящих от скриптов на стороне клиента, позволяя разработчикам добавлять необходимые JavaScript-фрагменты или HTML-элементы, которые должны появиться после того, как основной ответ был отображён. Используя эту директиву, можно модифицировать контент без прямого изменения исходного тела ответа, тем самым сохраняя целостность доставляемого содержимого.

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

location /example {
    add_after_body '';
}

Описание

Директива 'addition_types' в NGINX используется для сопоставления расширений файлов с пользовательскими MIME-типами, которые должны быть добавлены в заголовок Content-Type HTTP-ответов. Эта директива позволяет администраторам веб-сервера обрабатывать типы файлов, не покрываемые стандартными определениями MIME-типов, обеспечивая корректную доставку контента в зависимости от типа файла. Синтаксис директивы 'addition_types' требует как минимум одного аргумента, состоящего из расширения файла, за которым следует MIME-тип. Несколько расширений и соответствующих им MIME-типов могут быть определены в одной директиве. Когда файл отдается, NGINX проверяет указанные расширения по отношению к запрошенному файлу. Если найдено совпадение, соответствующий MIME-тип включается в ответ, дополняя предопределённые типы в конфигурации NGINX. Эта директива может использоваться в различных контекстах, таких как http, server или location блоки, что даёт гибкость при настройке MIME-типов для разных частей вашего веб-приложения. Добавление пользовательских MIME-типов может помочь предотвратить проблемы с обработкой файлов на стороне клиента, обеспечивая правильную интерпретацию браузерами содержимого передаваемых файлов.

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

http {
    addition_types .json application/json;
    addition_types .xml application/xml;
}

Описание

Директива `auth_basic` позволяет защитить локации или ресурсы на вашем сервере NGINX, требуя от клиентов HTTP Basic-аутентификацию. Когда эта директива включена, клиенты должны предоставить действительное имя пользователя и пароль, которые проверяются в соответствии с учётными данными, заданными в конфигурации. Эта директива преимущественно используется в сценариях, где требуется простое управление доступом, например для ограничения доступа к определённой части вашего сайта. Директива принимает один аргумент — название области (realm). Это имя является важной частью процесса аутентификации, так как оно будет отображаться в диалоговом окне аутентификации, показываемом браузером пользователя. Для полной реализации базовой аутентификации следует также использовать директиву `auth_basic_user_file` вместе с `auth_basic`, чтобы указать расположение файла паролей, содержащего разрешённые имена пользователей и хэшированные пароли. Без этого директивы не будут работать, так как сервер не будет знать, какие учётные данные проверять. В более сложных конфигурациях вы можете дополнительно контролировать доступ с помощью других директив, таких как `allow` и `deny`, которые можно комбинировать с `auth_basic` для уточнения, какие пользователи могут получить доступ к защищённому содержимому в зависимости от их IP-адресов или других критериев.

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

location /private {
    auth_basic "Restricted Content";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

Описание

Директива `auth_basic_user_file` используется в NGINX для указания пути к файлу, содержащему пары имён пользователей и хэшей паролей, необходимых для аутентификации пользователей через базовую HTTP-аутентификацию. Эта директива обычно используется в сочетании с директивой `auth_basic`, которая включает базовую аутентификацию для заданного контекста. Когда клиент делает запрос на сервер NGINX, настроенный для базовой аутентификации, сервер проверяет наличие директивы `auth_basic_user_file`. Если она присутствует, сервер читает указанный файл и сверяет имя пользователя и пароль, отправленные клиентом, с хранящимися хэшами. Файл должен иметь определённый формат: в каждой строке указано имя пользователя, за которым следует хэш пароля, сгенерированный с помощью инструмента вроде `htpasswd` из набора Apache HTTP Server. Процесс аутентификации направлен на ограничение доступа к конкретным ресурсам, гарантируя, что доступ получают только действующие пользователи. Важно обеспечить безопасное хранение файла с пользователями и недопущение его публичного доступа, чтобы предотвратить несанкционированный доступ к содержащимся в нём учётным данным. Кроме того, NGINX повышает безопасность, поддерживая различные криптографические алгоритмы хеширования для паролей, что затрудняет злоумышленникам компрометацию учётных записей пользователей.

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

location /secret {
    auth_basic "Restricted Access";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

Описание

The `auth_request` directive allows NGINX to handle authentication through a subrequest to a specified location. This location is intended to process authentication requests, and if the subrequest returns a 2xx status code, access to the original request is granted. If the response is anything other than a 2xx status, access is denied and the original request is not processed. This directive can be used in various contexts, including `http`, `server`, and `location`, allowing for flexible integration within different server configurations. The argument expects a single location name or path that NGINX will use for performing the authentication check. Typically, this would be a designated endpoint that handles the logic of checking user credentials or access conditions for the request being evaluated. When using `auth_request`, it's essential to ensure that the subrequest location is properly configured to return the correct status code based on the authentication result. The subrequest can also carry along the original request's headers if required, allowing for more complex authentication checks that consider client information.

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

location /protected {
    auth_request /auth;
}

location = /auth {
    internal;
    # Authentication logic here
    if ($http_authorization = "Bearer valid_token") {
        return 200;
    }
    return 401;
}

Описание

Директива `auth_request_set` в NGINX используется для определения переменной, которая будет хранить результат внутреннего запроса аутентификации. Как правило, директива принимает два аргумента: имя переменной, которую нужно установить, и тот ответ, который вы хотите проверить (либо код статуса, либо конкретная переменная). В сценариях, когда внутренний запрос аутентификации проходит успешно, переменная устанавливается; если он не проходит, переменная остаётся неустановленной или сбрасывается в начальное состояние. Эта директива особенно полезна в сочетании с директивой `auth_request`, поскольку позволяет выполнять более детализированный контроль доступа, оценивая результат запросов аутентификации. Например, в зависимости от значения переменной, установленной `auth_request_set`, можно выполнять дополнительную логику, обеспечивая разные уровни доступа или обработку ошибок. Если запрос аутентификации возвращает ответ 2xx, это означает успех, тогда как любые ответы 4xx или 5xx указывают на ошибку, что позволяет настраивать реакции на попытки неавторизованного доступа. Размещение директивы `auth_request_set` гибко: её можно использовать в контекстах `http`, `server` или `location`, что обеспечивает широкую вариативность конфигурации. Кроме того, важно убедиться, что внутренние запросы аутентификации корректно сконфигурированы и доступны. Поведение добавляемой переменной и её взаимодействие с другими директивами может существенно влиять на маршрутизацию и поведение контроля доступа в NGINX, поэтому при внедрении в рабочую среду требуется тщательное тестирование.

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

location /protected {
    auth_request /auth;
    auth_request_set $auth_status $upstream_status;
    error_page 401 = @error401;
} 
location = /auth {
    internal;
    proxy_pass http://backend_auth;
}

Описание

Директива 'autoindex' позволяет NGINX генерировать и отображать список файлов в каталоге, когда индексный файл отсутствует. При включении, если пользователь запрашивает каталог без индексного файла (например, index.html или index.htm), NGINX вернёт сортируемый список файлов, содержащихся в этом каталоге. Эта директива может быть задана в различных контекстах: http, server, and location. Установив 'autoindex on', можно сделать содержимое каталогов доступным, что может быть полезно при отладке, но представляет риск безопасности, если конфиденциальные файлы будут случайно открыты. Вывод можно настроить с помощью связанных директив, таких как 'autoindex_format', для разных форматов отображения (например, компактного или полного списка). Важно правильно настроить права доступа к каталогам, чтобы избежать несанкционированного доступа. Когда 'autoindex' используется вместе с директивами управления доступом, такими как 'allow' и 'deny', сначала применяются правила доступа, чтобы определить, следует ли отказать или разрешить запрос, прежде чем обрабатывать индекс.

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

location /files {
    autoindex on;
}

Описание

`autoindex_format` указывает формат вывода списков каталогов, когда включена функция autoindex в NGINX. Эта директива позволяет пользователям изменить внешний вид сгенерированного HTML для лучшей читаемости или кастомизации. NGINX поддерживает несколько предопределённых форматов, таких как `html` и `json`, каждый из которых соответствует своему стилю представления. Когда директива задана в конфигурационном файле, NGINX использует указанный формат вывода вместо значений по умолчанию, что повышает удобство использования индексов каталогов для клиентов или приложений, которые могут полагаться на определённые структуры данных в ответе. В практических сценариях `autoindex_format` можно использовать для предоставления удобного для пользователя представления содержимого каталогов в формате HTML, например с ссылками и размерами файлов, или в формате JSON для потребления API, который легко парсится программно. Формат должен задаваться в допустимых контекстах, а именно на уровнях `http`, `server` или `location`, что позволяет гибко управлять поведением в зависимости от области действия конфигурации NGINX. Эта директива в первую очередь предназначена для интеграции с различными клиентскими приложениями, которые обрабатывают списки каталогов по-разному в зависимости от ожидаемого формата.

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

location /files {
    autoindex on;
    autoindex_format json;
}

Описание

Директива `autoindex_localtime` в NGINX влияет на способ генерации списков каталогов при включённой индексации директорий. Когда эта директива установлена в 'on', NGINX будет отображать время последнего изменения файлов в локальном часовом поясе вместо UTC, что делает отображение более понятным для пользователей, которые скорее ориентируются в своём местном времени, а не в координированном всемирном времени. Эту директиву можно размещать в нескольких контекстах, включая 'http', 'server' и 'location', что позволяет тонко настраивать её поведение в зависимости от области запроса. Параметр этой директивы — просто флаг: 'on' для включения показа локального времени в списках каталогов или 'off' для его отключения; по умолчанию используется 'off'. Включение этой функции может улучшить пользовательский опыт, особенно для приложений, которые отображают метаданные файлов в удобном для пользователя виде, поскольку это позволяет пользователям видеть формат времени, соответствующий их географическому положению, вместо необходимости конвертировать время из UTC. Важно отметить, что включение `autoindex_localtime` не меняет фактические временные метки файлов, хранящихся на сервере; оно лишь изменяет способ их представления в списках каталогов для конечных пользователей.

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

location /files {
    autoindex on;
    autoindex_localtime on;
}

Описание

Директива `autoindex_exact_size` используется в HTTP-сервере NGINX для определения того, как размеры файлов представлены в автоматически сгенерированных списках каталогов. Когда эта директива включена (установлена в 'on'), NGINX будет показывать точные размеры файлов в байтах. Если установлена в 'off', она преобразует размер в более удобочитаемый формат (например, KB, MB и т.д.) при выдаче списка каталогов. Эта настройка может быть особенно полезна пользователям, которым нужны точные данные о размерах файлов, особенно в средах, где размеры файлов необходимо тщательно отслеживать. Контекст для этой директивы включает `http`, `server` и `location`, что позволяет гибко размещать её в зависимости от архитектуры приложения. Директива принимает один флаговый аргумент: он может быть либо 'on', либо 'off'. Наличие этих опций позволяет администратору сервера настроить поведение модуля autoindex в соответствии с потребностями конкретных локаций сервера или всей конфигурации сервера.

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

location /files {
    autoindex on;
    autoindex_exact_size on;
}

Описание

Директива 'modern_browser' используется в конфигурации NGINX для указания того, какие браузеры следует считать современными и обрабатывать иначе при обработке запросов. Она может повысить производительность веб-приложений, включая или отключая определённые функции или поведения в зависимости от возможностей клиента. Директива может принимать один или два параметра, что позволяет задавать конкретные условия, при которых применяются оптимизации или правила для современных браузеров. Например, если запрос поступает от распознанного современного браузера, NGINX может скорректировать свой ответ или поведение маршрутизации соответствующим образом. При конфигурации директивы при указании одного параметра он обозначает версию браузера, тогда как второй, необязательный параметр может задавать дополнительные настройки совместимости. Директива применима в различных контекстах, включая HTTP, server и location-блоки, и позволяет администраторам оптимизировать ответы сервера в зависимости от браузера пользователя, потенциально улучшая общий пользовательский опыт за счёт использования современных технологий, таких как HTTP/2, или специальных механизмов кэширования. Для эффективного использования этой директивы важно правильно понимать строки user-agent и возможности браузеров.

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

server {
    location / {
        modern_browser Firefox 90;
    }
}

Описание

Директива 'ancient_browser' в NGINX предназначена для управления входящими запросами от браузеров, которые считаются устаревшими или несовместимыми с современными веб-стандартами. Указав директиву 'ancient_browser', администраторы сервера могут определить, обслуживать ли специальный контент, перенаправлять пользователя на другой URL или применять определённые политики для этих устаревших браузеров. Это особенно полезно при решении вопросов безопасности или для информирования пользователей со старыми браузерами о ограничениях их ПО. Эта директива может принимать несколько аргументов, каждый из которых представляет собой конкретный браузер или user agent string, определяемый как устаревший браузер. Поведение может включать пользовательские страницы ошибок, перенаправление на предложения обновления или отдачу упрощённой версии сайта, специально разработанной для таких устаревших клиентов. Гибкость в определении того, какие браузеры попадают в эту категорию, позволяет тонко управлять тем, как сервер NGINX взаимодействует с устаревшими клиентами, обеспечивая баланс между доступностью и современной производительностью веба. При настройке этой директивы важно учитывать корректность указанных шаблонов user-agent, а также понимать, что разные контексты (http, server, and location) могут влиять на её эффективность. Также следует учитывать необходимость баланса между поддержкой старых технологий и сохранением стандартов безопасности и производительности на сервере.

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

http {
    ancient_browser "MSIE 5.0";
    ancient_browser "Mozilla/4.0";
    location / {
        # Normal processing
    }
}

Описание

Директива `modern_browser_value` используется для задания или изменения HTTP-ответа, связанного с запросами, отправленными современными браузерами. Она централизует конфигурацию для обработки специфического поведения браузеров, что позволяет выполнять целевые оптимизации и корректировать ответы в зависимости от того, исходил ли запрос от распознанного современного браузера. При настройке эта директива позволяет задать значение, которое изменяет заголовки ответа сервера, специально адаптированные для современных веб-браузеров. Это может улучшить совместимость и производительность браузеров для различных функций сайта или повысить безопасность, предоставляя современным браузерам специализированные инструкции по обработке определённых ресурсов. В параметры могут входить значения, определяющие политики кэширования или форматы ответа, специально разработанные для новых версий браузеров, поддерживающих передовые технологии.

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

modern_browser_value "joyful_response";

Описание

Директива `ancient_browser_value` в NGINX используется для задания параметра ответа на запросы, исходящие от устаревших веб‑браузеров, идентифицируемых как 'ancient'. По сути, эта директива указывает, как NGINX должен обрабатывать такие запросы, позволяя оптимизировать ответы или применять конкретные правила для улучшения удобства пользователей или поддержания совместимости. Директива может располагаться в разных контекстах, таких как `http`, `server` или `location`, что обеспечивает гибкость применения в зависимости от области конфигурации. Директива принимает один аргумент, который обычно представляет собой числовое значение или строку, обозначающую действие, которое следует выполнить, или значение, которое нужно установить при обнаружении таких запросов. Поведение директивы может влиять на то, как обслуживаются ресурсы, особенно на сайтах, стремящихся поддерживать широкий спектр пользовательских агентов. Это особенно полезно для устаревших систем, которые по-прежнему зависят от старых браузерных технологий, поскольку позволяет им получать возможные исправления или указания на обновлённые ресурсы вместо полного отказа во доступе. Например, если сервер определяет, что агент пользователя соответствует критериям для классификации как 'ancient' браузер, сервер может ответить настраиваемым сообщением или перенаправить на страницу с рекомендацией обновить браузер. В целом эта директива — полезный инструмент для веб-разработчиков, стремящихся поддерживать доступность для разнородной аудитории пользователей.

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

http {
    ancient_browser_value "Upgrade your browser";
}

Описание

Директива 'charset' используется для определения набора символов, который должен использоваться в HTTP-заголовках, которые NGINX отправляет клиентам. Она играет ключевую роль в обеспечении корректного отображения содержимого на стороне клиента, информируя браузер о кодировке передаваемых данных. Это важно для веб-приложений, которым нужно точно обрабатывать разные языки или символы. Директива принимает один аргумент, который указывает набор символов, например 'utf-8', 'iso-8859-1' или 'windows-1251'. Когда эта директива установлена, NGINX будет включать charset в заголовок 'Content-Type' ответов, тем самым сообщая эту кодировку браузеру клиента. Это помогает предотвратить проблемы с неправильным отображением символов, такие как искажённый текст или неожиданные символы. Кроме того, директиву 'charset' можно настроить в разных контекстах, то есть её можно задать в блоке HTTP, server или location. Это позволяет тонко контролировать то, как различные части веб-приложения обрабатывают кодировку символов, что делает её гибкой для контента, обслуживаемого из разных частей сайта.

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

http {
    charset utf-8;

    server {
        location / {
            charset iso-8859-1;
        }
    }
}

Описание

Директива `source_charset` в NGINX используется для задания набора символов, применяемого при обработке тел входящих запросов. Эта директива особенно важна при обработке форм и содержимого POST-запросов, поскольку обеспечивает корректную интерпретацию символов сервером в соответствии с указанной кодировкой. Директиву можно применять в различных контекстах, включая `http`, `server`, `location` и `if in location`, что позволяет гибко настраивать поведение в зависимости от разных местоположений сервера или типов запросов. При определении `source_charset` необходимо указать единственное значение charset в качестве аргумента, например 'utf-8', 'iso-8859-1' и т. п. Если при обработке входящих данных кодировка не указана, NGINX по умолчанию будет интерпретировать данные таким образом, который может привести к искажению символов, особенно для содержимого с не ASCII символами. Корректная настройка `source_charset` критически важна для приложений, обрабатывающих многоязычный текст или данные из разных регионов с разными стандартами кодировок. Кроме того, для некоторых наборов символов могут существовать специальные инструкции по обработке или ограничения, поэтому важно обратиться к документации NGINX, чтобы узнать, какие наборы символов поддерживаются и какие нюансы связаны с их реализацией в разных контекстах. Неправильные настройки или неверные значения charset могут привести к таким проблемам, как повреждённые данные, неудачные запросы или ошибки сервера, что подчёркивает важность тестирования и проверки параметров charset в вашей конфигурации NGINX.

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

# Set the source charset to UTF-8 for proper encoding handling
source_charset utf-8;

Описание

Директива `override_charset` в NGINX используется для управления кодировкой ответов контента, отдаваемого сервером. По умолчанию учитывается набор символов, указанный в заголовке Content-Type ответа. Тем не менее бывают случаи, когда администратор может захотеть принудительно установить другую charset, независимо от того, что указывает бэкенд-сервис. Установка `override_charset` в `on` обеспечивает это. Когда `override_charset` установлена в `on`, NGINX заменяет любой charset, указанный в заголовке Content-Type ответов, на кодировку, сконфигурированную на сервере. Это особенно полезно в средах, где контент из разных источников может использовать несовместимые charset, или когда серверу необходимо применять единую политику кодировки ко всем HTTP-ответам. Напротив, когда директива установлена в `off` (значение по умолчанию), NGINX позволяет приоритету иметь charset, указанный в Content-Type, что может приводить к потенциально несовместимой кодировке символов в разных ответах. Эта директива может быть настроена в различных контекстах, а именно в `http`, `server`, `location`, а также внутри блока `if` внутри `location`. Каждый контекст позволяет тонко настраивать поведение charset в зависимости от разных сценариев обработки запросов. Принудительное применение конкретной charset может повысить совместимость с клиентами, ожидающими определённую кодировку, тем самым избегая проблем, связанных с неверной интерпретацией символов, особенно в мультиязычном контенте.

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

http {
    override_charset on;
    server {
        location / {
            root   html;
            index  index.html index.htm;
        }
    }
}

Описание

Директива `charset_types` в NGINX позволяет администраторам указать, к каким типам содержимого будет применено определённое кодирование символов. Эта директива принимает один или несколько MIME types в качестве аргументов и должна использоваться внутри блока `http`, `server` или `location`. Когда ответ соответствует одному из указанных MIME types, NGINX автоматически добавляет соответствующий заголовок `Content-Type` для этого набора символов, информируя тем самым клиентов о том, как корректно интерпретировать данные ответа. Например, если вы укажете `charset_types text/html application/json;`, NGINX будет отправлять набор символов, заданный директивой `charset`, для любого ответа с `Content-Type: text/html` или `Content-Type: application/json`. Это особенно полезно для обеспечения корректного отображения текста на клиентах: задавая набор символов по умолчанию для разных типов файлов, вы повышаете совместимость с многобайтовыми кодировками символов, такими как UTF-8. Если тип содержимого запроса не совпадает ни с одним из типов, указанных в `charset_types`, NGINX не будет применять набор символов по умолчанию, заданный директивой `charset`, к таким ответам, что позволяет точно контролировать, как разные типы содержимого обрабатывают кодировку символов.

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

http {
    charset UTF-8;
    charset_types text/html application/json text/css;
}

Описание

Директива `charset_map` позволяет задавать, каким образом разные кодировки символов должны отображаться на MIME-компоненты в контексте `http` NGINX. Это особенно полезно для того, чтобы содержимое, обслуживаемое NGINX, корректно указывало свою кодировку символов, что может влиять на отображение контента в браузерах. Каждая запись в блоке `charset_map` состоит из исходной и целевой кодировок, позволяя при необходимости выполнять преобразование между различными кодировками. Директива действует в контексте `http` и настраивается с помощью блочной структуры, содержащей ряд записей в формате `charset source_charset destination_charset;`. Например, если определённую кодировку нужно трактовать как другую — например, сопоставить `latin1` с `utf-8` — это можно объявить в этом блоке. Когда NGINX обрабатывает запросы, он просматривает это соответствие, чтобы определить, как поступать с кодировкой символов для содержимого, отправляемого клиентам. Важно убедиться, что определённые соответствия точны и необходимы, поскольку неверная конфигурация может привести к неправильному отображению содержимого в браузерах клиентов. Кроме того, это может иметь решающее значение для интернационализации, когда содержимое должно поставляться в разных языках и кодировках в зависимости от местоположения и предпочтений пользователя.

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

charset_map {
    charset windows-1251 utf-8;
    charset iso-8859-1 utf-8;
};

Описание

Директива `dav_methods` используется для определения набора HTTP-методов, которые разрешены при взаимодействии клиентов с ресурсами через WebDAV. Эта директива имеет ключевое значение для управления правами доступа к ресурсам, которые изменяются посредством HTTP-запросов. Разрешая конкретные методы, такие как `GET`, `PUT`, `DELETE` и `PROPFIND`, администратор может контролировать, какие действия клиенты могут выполнять на сервере, повышая тем самым как безопасность, так и функциональность. Например, если директива настроена так, чтобы разрешать `PUT`, клиенты смогут загружать файлы, тогда как запрет `DELETE` помешает им удалять файлы. Такая тонкая настройка прав необходима для сервисов, которые активно используют WebDAV, позволяя серверу соответствующим образом реагировать в зависимости от метода взаимодействия. Директива может принимать один или несколько аргументов, которые соответствуют HTTP-методам, которые вы хотите разрешить, что делает её гибкой при настройке прав. По сути, директива `dav_methods` применяется в контекстах `http`, `server` или `location` и может быть критически важна для того, чтобы позволять только требуемые HTTP-действия, тем самым эффективно защищая ваши службы WebDAV.

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

location /dav {
    dav_methods PUT DELETE PROPFIND;
}

Описание

Директива 'create_full_put_path' является опцией конфигурации в NGINX, которая определяет, следует ли создавать полные пути для файлов, загружаемых клиентом, во время PUT-запросов. Когда установлено значение 'on', NGINX не только создаст целевой файл, указанный в PUT-запросе, но и обеспечит существование всех каталогов, ведущих к этому целевому файлу. Это особенно важно в сценариях, когда клиенты могут пытаться загружать файлы в пути, которые ранее не были созданы на сервере, что повышает надёжность обработки загрузок файлов, гарантируя наличие необходимой структуры каталогов. Если директива установлена в 'off' (по умолчанию), NGINX вернёт 403 Forbidden, если каталог, указанный в пути PUT, не существует. Однако при включённой 'create_full_put_path' во время операции PUT, если промежуточные каталоги отсутствуют, NGINX попытается автоматически создать их, позволяя загрузке завершиться успешно. Это может значительно упростить управление загрузками и помочь предотвратить ошибки из‑за отсутствующих каталогов при использовании клиентами PUT-запросов. С точки зрения ожидаемого поведения, когда эта директива размещена в контекстах http, server или location, она функционирует одинаково во всех случаях, что делает её гибкой для различных конфигураций, где ожидаются загрузки файлов.

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

location /uploads {
    create_full_put_path on;
    root /var/www;
}

Описание

Директива `min_delete_depth` используется в обработке файлов NGINX для указания минимальной глубины каталога, необходимой для выполнения операций удаления. Когда эта директива установлена, NGINX разрешает удалять только те каталоги, глубина которых больше или равна указанному уровню. Это особенно полезно для предотвращения случайного удаления корневых или верхнеуровневых каталогов за счёт введения более строгого условия для операций удаления. В иерархической конфигурации NGINX глубина каталога вычисляется на основе числа слэшей (/) в пути. Например, путь `/var/www/html` имеет глубину 2. Директива помогает защититься от необратимых удалений, обеспечивая возможность удаления только тех каталогов, которые соответствуют критерию минимальной глубины. Таким образом администраторы могут снизить риски потери данных при управлении файловой структурой на сервере. Эту директиву можно задавать на нескольких уровнях, включая `http`, `server` и `location`, что даёт гибкость в зависимости от потребностей конфигурации. Значение, присваиваемое `min_delete_depth`, должно быть положительным целым числом, соответствующим требуемой глубине каталога для возможности удаления.

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

http {
    min_delete_depth 2;
}

Описание

Директива `dav_access` используется в HTTP-модуле NGINX для задания правил, которые контролируют доступ к ресурсам WebDAV на основе IP-адреса клиента. Разрешая или запрещая конкретные IP-адреса или диапазоны адресов, администраторы сайта могут управлять тем, кто может взаимодействовать с ресурсами, доступными через WebDAV. Эта директива может принимать от одного до трёх аргументов в зависимости от требуемых операций, которые обычно подразумевают указание 'allow' для предоставления доступа или 'deny' для его ограничения. Она работает путём проверки IP-адреса входящего запроса по заданным правилам и соответственно разрешает или блокирует запрос. При настройке `dav_access` администраторы могут определять несколько правил, которые могут быть либо включающими (allow), либо исключающими (deny). Правила могут быть структурированы иерархически, то есть правило deny может переопределять правило allow в случае конфликта. Следует уделять внимание порядку правил, поскольку NGINX обрабатывает их последовательно и применит действие, соответствующее первому совпавшему правилу. Пользователи также могут комбинировать правила для IPv4 и IPv6, которые в конфигурации обрабатываются отдельно.

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

location /webdav {
    dav_methods PUT DELETE MKCOL COPY MOVE;
    dav_access allow 192.168.1.0/24;
    dav_access deny all;
}

Описание

Директива `degradation` позволяет пользователю настраивать обработку запросов в зависимости от заданных условий во время обработки сервером. При её использовании конфигурируются параметры, влияющие на поведение сервера; это особенно полезно для приложений, которым требуется приоритизировать определённые типы трафика или адаптироваться к меняющимся условиям нагрузки. Директива принимает один аргумент, определяющий способ оценки и обработки запросов; конкретные сведения о допустимых значениях аргумента и его контексте использования следует уточнять в документации соответствующего модуля и системных ресурсах. Эта директива особенно полезна для динамического управления качеством обслуживания на основе реальной нагрузки или шаблонов доступа. Реализуя параметры degradation, администраторы могут обеспечить работу приложения при повышенной нагрузке за счёт ограничения доступа, изменения поведения ответов или определения резервных стратегий. Этот механизм может быть необходим для поддержания непрерывности сервиса и производительности в периоды пиковых нагрузок или при нестабильных сетевых условиях. Примеры сценариев: понижение приоритета для определённых типов запросов, включение подробного логирования для диагностики или настройка времени отклика.

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

http {
    degradation 1;
}

Описание

Директива 'degrade' в NGINX позволяет администраторам задавать, как должен вести себя сервер, когда primary backend server недоступен. Эта директива особенно полезна в схемах балансировки нагрузки, где может быть несколько upstream серверов или сервисов. Включив директиву 'degrade', NGINX позволит маршрутизировать запросы на назначенный вторичный сервер или заранее определённый набор серверов даже когда один или несколько upstream серверов не работают. Это помогает поддерживать доступность сервиса и гарантировать, что пользователи продолжают получать ответы даже в случае сбоев. Когда директива 'degrade' включена, она фактически изменяет поведение при отказах, позволяя обслуживать запросы с вторичных ресурсов вместо полного отказа. Это особенно важно в средах с высокой доступностью, где критично поддерживать непрерывность сервиса. Администраторам необходимо убедиться, что соответствующие конфигурации fallback настроены, например, определены backup servers в контексте upstream, чтобы эффективно использовать эту директиву. Кроме того, успех использования этой директивы зависит от общих health checks и правильной настройки upstream серверов.

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

http {
    upstream backend {
        server primary_server;
        server backup_server backup;
    }
    server {
        location / {
            proxy_pass http://backend;
            degrade;
        }
    }
}

Описание

Директива 'empty_gif' используется внутри контекста location в конфигурации NGINX, чтобы инструктировать сервер возвращать небольшой прозрачный GIF, когда запрос соответствует этому location. Эта директива особенно полезна для пикселей отслеживания или заполнителей, где контент недоступен, но требуется ответ для клиентского отслеживания. Директива не принимает аргументов и активирует встроенный URL-ответ для пустого GIF-изображения, которое имеет размер 1x1 пиксель и полностью прозрачно. Когда поступает запрос к location, в котором задана директива 'empty_gif', NGINX не будет обрабатывать дальнейшие директивы для этого запроса в этом location; вместо этого он сформирует HTTP-ответ, содержащий данные GIF-изображения. По умолчанию NGINX выполняет типичную обработку запроса, если иное не указано директивами, подобными 'empty_gif'. Поэтому эффективное использование этой директивы требует аккуратного размещения в определениях location в конфигурации сервера, чтобы она случайно не перекрывала другие настройки конфигурации. Директива расширяет возможности сервера по предоставлению ряда функций без необходимости наличия физического файла изображения на сервере, что оптимизирует использование ресурсов и упрощает конфигурацию в сценариях, таких как аналитическое отслеживание или отображение визуальных заполнителей.

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

location /tracking {
    empty_gif;
}

Описание

Директива `fastcgi_pass` в NGINX указывает местоположение сервера FastCGI, который будет обрабатывать запросы. Она может направлять трафик на TCP socket, Unix socket или IP-адрес с указанным портом. Эта директива обычно настраивается внутри блока `location`, что позволяет NGINX управлять тем, как обрабатываются запросы в зависимости от пути URL и других параметров. Когда запрос поступает, он маршрутизируется на указанный сервер FastCGI, который обрабатывает запрос и возвращает соответствующий ответ NGINX, который затем отдает его клиенту. В контексте использования вы обычно настраиваете директиву `fastcgi_pass` вместе с дополнительными директивами, такими как `fastcgi_param`, которая задает параметры для FastCGI-приложения (например, имя файла скрипта, метод запроса и т. д.). Сервер FastCGI отвечает обработанными данными, и NGINX пересылает ответ обратно клиенту. Этот механизм необходим для генерации динамического контента в веб-приложениях, где бэкенд-обработка делегируется серверу FastCGI для повышения производительности и масштабируемости.

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

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

Описание

Директива `fastcgi_index` в NGINX указывает файл по умолчанию, который будет отдаваться, когда FastCGI-запрос направлен в локацию без указания имени файла. Когда клиент запрашивает каталог, NGINX проверяет наличие указанного файла `fastcgi_index` в этом каталоге. Если в запросе не указан конкретный файл, NGINX автоматически добавит значение `fastcgi_index` к запросу для FastCGI-сервера, чтобы тот сгенерировал ответ. Эта директива обычно используется вместе с настройками `fastcgi_param` и `include`, что позволяет более плавно интегрировать PHP или другие приложения на базе FastCGI. Она улучшает удобство для пользователей, гарантируя, что если ожидается индексный файл (например, `index.php`), он будет автоматически отдан без необходимости явного указания его клиентом. Директива может быть установлена на нескольких уровнях конфигурации: `http`, `server` и `location`, что позволяет гибко управлять поведением в разных контекстах вашей конфигурации NGINX.

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

location / {
    index index.php;
    fastcgi_index index.php;
    fastcgi_pass 127.0.0.1:9000;
    include fastcgi_params;
}

Описание

Директива `fastcgi_split_path_info` позволяет указать регулярное выражение, которое соответствует части URI запроса и разделяет его на два компонента: "script" и "path info". Это важно для приложений FastCGI, когда вы хотите направлять определённые запросы URI к конкретным скриптам, одновременно передавая остаточную информацию пути для обработки. Директива определяет, как парсится URI, и позволяет приложению эффективно обрабатывать запросы. Когда эта директива задана, сервер обрабатывает URI запроса в соответствии с указанным шаблоном, захватывая "script" и "path info" в переменные окружения `SCRIPT_NAME` и `PATH_INFO` соответственно. Эта функциональность позволяет разработчикам создавать чистые URL, одновременно позволяя их скриптам корректно работать с ожидаемыми входными данными. Предоставленное регулярное выражение должно быть тщательно сконструировано, чтобы адекватно захватывать требуемое; неправильные шаблоны могут привести к непредвиденному поведению или неверной маршрутизации запросов. Директива может использоваться внутри контекстов `http`, `server` и `location`, что делает её очень гибкой для использования на разных уровнях конфигурации NGINX. Важно убедиться, что указанное регулярное выражение соответствует синтаксису, используемому в NGINX, и не конфликтует с существующими маршрутами на вашем сервере.

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

location ~ \.php$ {
    fastcgi_split_path_info ^(.+\.php)(/.+)$;
    fastcgi_pass 127.0.0.1:9000;
    include fastcgi_params;
}

Описание

`fastcgi_store` используется для определения поведения NGINX в отношении сохранения ответа, полученного от FastCGI-сервера. Когда эта директива установлена, она инструктирует NGINX сохранять тело ответа FastCGI-приложения в файл на диске, что позволяет повысить эффективность обслуживания повторных запросов к одному и тому же ресурсу FastCGI. При указании первый аргумент должен быть допустимым путем к файлу или URI, где должен храниться ответ. Это поддерживает различные возможности файловой системы; например, это может быть динамически создаваемый путь файла на основе переменных запроса или статический путь. Режим хранения также может включать установку прав доступа к файлам в зависимости от конфигурации — что очень полезно при настройке прав для выдачи статических файлов из ответов FastCGI. Кроме того, директива влияет на кэширование, поскольку она позволяет более устойчивый механизм кэширования по сравнению со стандартным кэшированием в памяти, так как сохраняет ответы в виде файлов. Однако при конфигурации пути хранения, прав доступа и стратегий очистки этих файлов требуется тщательное планирование для грамотного управления дисковым пространством в процессе работы.

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

location /example {
    fastcgi_pass backend;
    fastcgi_index index.php;
    fastcgi_store on;
    fastcgi_store_access user:rw group:rw all:r;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
}

Описание

Директива 'fastcgi_store_access' задаёт права доступа к файлам, которые сохраняются при использовании модуля FastCGI. Эта директива позволяет операторам определять, какие клиенты могут получить доступ к сохранённым файлам на основе их IP-адресов, используя правила allow или deny. Она может принимать до трёх параметров, где каждый параметр задаёт различные правила доступа в зависимости от указанных IP-адресов. Директива особенно полезна в сценариях, где в файлах, сгенерированных ответами FastCGI, могут храниться конфиденциальные данные, поэтому жизненно важно строго контролировать доступ, чтобы предотвратить несанкционированный доступ. Когда эта директива установлена, NGINX проверяет входящий запрос по указанным правилам доступа. Если IP клиента совпадает с любым правилом 'allow', доступ предоставляется, а если совпадает с правилом 'deny' — доступ запрещается. Если ни одно правило не применимо, поведение доступа определяется конфигурацией по умолчанию. Директива обеспечивает гибкость и контроль, позволяя администраторам тонко настраивать уровни доступа в соответствии с потребностями их приложений. Например, её можно настроить так, чтобы разрешать доступ только из определённых сетей или IP-адресов и запрещать остальные, что повышает безопасность сохранённых ответов FastCGI.

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

location /store {
    fastcgi_store on;
    fastcgi_store_access user:rw group:rw all:r;
    fastcgi_pass backend;
}

Описание

Директива `fastcgi_buffering`, при установке в значение `on`, включает буферизацию ответов от FastCGI-серверов перед их отправкой клиенту. Этот механизм буферизации позволяет NGINX эффективнее обрабатывать ответы, считывая всё тело ответа от FastCGI-сервера в буфер перед пересылкой клиенту. Напротив, при установке в `off` ответы передаются клиенту сразу после получения, что может повысить отзывчивость ценой ухудшения управления ресурсами, особенно при высокой нагрузке. Когда директива установлена в `on`, NGINX использует несколько предопределённых размеров буферов, которые можно настроить с помощью других директив, таких как `fastcgi_buffers` и `fastcgi_buffer_size`. Такая стратегия буферизации может привести к снижению задержек для клиентов, поскольку NGINX сможет отправлять более крупные куски данных быстрее, когда весь ответ будет получен — это особенно полезно для больших тел ответа. Однако буферизацию нужно управлять осторожно; чрезмерная буферизация может привести к увеличению использования памяти. Эта директива может быть настроена в контекстах `http`, `server` или `location`, что обеспечивает гибкую конфигурацию в зависимости от конкретных потребностей. Важно понимать последствия обоих значений (`on` и `off`) для оптимальной настройки производительности NGINX в соответствии с требованиями приложения.

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

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_buffering off;
    include fastcgi_params;
}

Описание

В NGINX директива `fastcgi_request_buffering` позволяет администратору включать или отключать буферизацию тела запроса при обработке запросов модулем FastCGI. По умолчанию, когда эта директива установлена в 'on', NGINX буферизует всё тело запроса перед передачей его процессу FastCGI. Это может повысить производительность, особенно в сценариях, где приложению требуются все данные запроса перед началом обработки. Однако установка `fastcgi_request_buffering` в 'off' позволяет передавать запросы напрямую в приложение FastCGI без промежуточной буферизации в NGINX. Это особенно полезно при обработке больших загрузок или когда приложение обрабатывает данные в реальном времени. При такой настройке данные могут начинать обрабатываться по мере их поступления, что потенциально снижает потребление памяти и улучшает отзывчивость при работе с большими полезными нагрузками или длительными запросами. Директиву можно указывать на уровнях контекстов `http`, `server` или `location`, что позволяет тонко настраивать поведение обработки запросов в зависимости от конкретных локаций или серверных блоков в соответствии с потребностями обслуживаемого приложения.

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

location /upload {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_request_buffering off;
}

Описание

Директива `fastcgi_ignore_client_abort` — это параметр конфигурации в NGINX, который помогает управлять поведением запросов, обрабатываемых через интерфейс FastCGI. Когда она включена (установлена в 'on'), NGINX продолжит обработку ответа от бэкенд-сервера FastCGI даже если клиент, сделавший запрос, отключился до полного отправления ответа. Напротив, если директива установлена в 'off', NGINX завершит FastCGI-запрос при отключении клиента, что может быть важно в сценариях, где приоритетом является экономия ресурсов. Она позволяет контролировать использование ресурсов в ситуациях, когда клиент может отказаться от запроса, потенциально снижая затраты на продолжающуюся обработку на бэкенде. Важно отметить, что если у вас есть длительно выполняющиеся FastCGI-запросы, которые должны завершиться даже после отключения клиента, включение этой директивы может быть полезно. Однако в случаях, когда ответ генерируется динамически и имеет значение для сессии клиента, сохранение значения по умолчанию (off) может быть разумным, чтобы избежать лишней обработки и расходования ресурсов. Эту директиву можно задать в контекстах `http`, `server` или `location`, что определяет, где регулируется поведение при отключении клиента.

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

location /api {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_ignore_client_abort on;
}

Описание

Директива `fastcgi_bind` используется в HTTP-сервере NGINX для указания адреса или сокета, к которому FastCGI-сервер должен привязываться при обработке запросов. Эта директива может принимать один или два аргумента. Первый аргумент — это адрес (IPv4 или IPv6) или путь к Unix socket, который указывает, где FastCGI-сервер может слушать соединения. Опциональный второй аргумент может указывать порт для привязки, позволяя более точно контролировать сетевые интерфейсы и порты, используемые процессом FastCGI. При использовании Unix socket синтаксис просто представляет собой путь к сокету без указания порта. Этот механизм привязки критичен в сценариях, где может работать несколько FastCGI-серверов, поскольку позволяет NGINX направлять трафик к нужному экземпляру FastCGI. FastCGI-серверы могут быть эффективно распределены в зависимости от заданной привязки, что может повысить производительность за счёт ограничения лишней сетевой нагрузки. Правильная конфигурация директивы `fastcgi_bind` необходима при развёртывании приложений на NGINX, зависящих от FastCGI, так как обеспечивает корректное распределение серверных ресурсов в соответствии с требованиями приложения и поддерживает отзывчивость на клиентские запросы. Для контекста эта директива может использоваться в блоках `http`, `server` или `location`, что даёт широкую гибкость в настройке обработчиков FastCGI для разных частей установки NGINX.

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

location ~ \.php$ {
    fastcgi_pass   127.0.0.1;  # Example FastCGI server address
    fastcgi_bind   127.0.0.1:9000;
}

Описание

Директива `fastcgi_socket_keepalive` позволяет управлять тем, следует ли поддерживать постоянные соединения с серверами FastCGI. Если установить 'on', NGINX будет держать FastCGI socket открытым после обработки запроса, что позволит последующим запросам повторно использовать существующее соединение вместо установления новых. Это может привести к повышению производительности за счёт уменьшения накладных расходов на создание и разрушение socket'ов, особенно при высокой нагрузке, когда множество запросов направляются к одному и тому же FastCGI-серверу. Директиву можно задавать внутри контекстов `http`, `server` или `location`, что делает её гибкой — она может применяться глобально или к конкретным блокам серверов и локациям. Флаг также можно установить в 'off', если вы хотите отключить поведение keepalive, в результате чего для каждого запроса к FastCGI-серверу будет устанавливаться новое соединение. Изменение этого параметра требует тщательного учёта способности FastCGI-сервера обрабатывать постоянные соединения, а также любых конфигураций таймаутов, которые могут повлиять на производительность.

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

http {
    server {
        location / {
            fastcgi_pass 127.0.0.1:9000;
            fastcgi_socket_keepalive on;
        }
    }
}

Описание

Директива `fastcgi_connect_timeout` задаёт максимальное время, в течение которого NGINX будет ожидать установления соединения с сервером FastCGI до того, как запрос будет признан неудачным. Этот таймаут особенно важен, когда ваш сервер FastCGI находится под большой нагрузкой или медленно отвечает, поскольку он помогает предотвратить зависание NGINX при попытке установить соединение. Если соединение не удаётся установить в указанный промежуток времени, запрос будет прерван, и клиенту будет возвращена ошибка 504 Gateway Timeout. Эта директива устанавливается в контексте конфигурации `http`, `server` или `location`, что позволяет настраивать её глобально или конкретно для определённых блоков server или путей location. Значение `fastcgi_connect_timeout` задаётся в секундах и может быть положительным целым числом. Важно выбрать подходящее значение с учётом ожидаемого времени ответа вашего сервера FastCGI, чтобы оно не было слишком большим (что ведёт к ненужным задержкам) и не слишком маленьким (что вызывает преждевременные таймауты).

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

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_connect_timeout 30s;
    include fastcgi_params;
}

Описание

Директива `fastcgi_send_timeout` задает максимальное время, в течение которого NGINX будет ждать ответа от сервера FastCGI. Если это время превысит предел, NGINX завершит соединение с сервером FastCGI и вернет клиенту ошибку. Значение указывается в миллисекундах и помогает предотвратить задержки, вызванные неотзывчивыми приложениями FastCGI. Директиву можно устанавливать на уровнях блоков `http`, `server` или `location`, что обеспечивает гибкую конфигурацию в зависимости от конкретного случая использования. При настройке `fastcgi_send_timeout` важно выбрать подходящее значение, исходя из ожидаемого времени ответа вашего FastCGI-бэкенда. Слишком короткий таймаут может приводить к необоснованным ошибкам для обычных запросов, тогда как слишком длинный — задерживать обработку неотзывчивых запросов. Поведение директивы можно дополнительно уточнить, используя ее совместно с другими директивами, такими как `fastcgi_read_timeout` и `fastcgi_buffering`, что эффективно контролирует как обработку ответов, так и стратегию таймаутов.

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

location /app {
    include fastcgi_params;
    fastcgi_pass backend;
    fastcgi_send_timeout 30s;
}

Описание

Директива `fastcgi_send_lowat` используется для оптимизации отправки данных из NGINX на FastCGI-серверы путём указания порога отправки данных. Если суммарное количество байтов, ожидающих отправки, остаётся ниже этого порога, процесс может отправлять больше данных без блокировки, что обеспечивает лучшую производительность, особенно при высокой нагрузке. Директива полезна в сценариях, где важна низкая задержка, например в веб‑приложениях, которые полагаются на частые небольшие ответы от FastCGI‑бэкенда. Параметр директивы `fastcgi_send_lowat` — одно целое число, обозначающее количество байтов. Когда это значение задано, если объём данных, поставленных в очередь на отправку на FastCGI‑сервер, превысит этот порог, NGINX начнёт блокировать или ограничивать дальнейшие операции отправки. Это позволяет соединению оставаться эффективным, обеспечивая оптимальное использование сетевых ресурсов без перегрузки сервера. Настройка этого значения особенно полезна с учётом потребностей приложения и характеристик производительности бэкенда.

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

location /api {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_send_lowat 16384;
}

Описание

Директива `fastcgi_buffer_size` задаёт размер буфера, используемого для чтения заголовка ответов FastCGI от бэкенд‑сервера. Когда NGINX обменивается данными с приложением FastCGI, он буферизует заголовок ответа, чтобы корректно обработать его перед передачей тела. Правильно подобранный размер буфера может повысить производительность вашей конфигурации NGINX, гарантируя, что заголовки помещаются в буфер без необходимости нескольких операций чтения, что снижает задержки. Размер буфера определяется в контексте блоков `http`, `server` или `location`, что позволяет задавать его с точностью до уровня конфигурации. Директива принимает аргумент со значением размера, например `16k` или `32`. Если буфер недостаточно велик для хранения данных заголовка, NGINX может переключиться на отдельный буфер для тела, что может привести к увеличению времени ответа или использованию ресурсов. Обеспечение соответствия `fastcgi_buffer_size` ожидаемым размерам ответов ваших приложений FastCGI имеет решающее значение для оптимальной производительности.

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

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_buffer_size 32k;
    include fastcgi_params;
}

Описание

Директива 'fastcgi_pass_request_headers' используется в конфигурациях NGINX для определения того, следует ли пересылать заголовки клиентского запроса на FastCGI-сервер. Эта директива принимает в качестве аргумента логический флаг, который позволяет включить или отключить передачу этих заголовков. При значении 'on' NGINX передаёт все заголовки из клиентского запроса, включая те, которые могут быть изменены или добавлены промежуточными прокси или другими сервисами. Напротив, установка 'off' означает, что никакие заголовки запроса не будут отправлены на FastCGI-сервер. Эффективное использование этой директивы важно для приложений, которые зависят от определённых заголовков для корректной работы, например `HTTP_REFERER` или `USER_AGENT`. Непередача этих заголовков может привести к проблемам в веб-приложениях или системах управления контентом, которые ожидают определённые заголовки запроса. Также важно учитывать вопросы безопасности при пересылке некоторых заголовков, так как это может раскрыть чувствительную информацию из клиентских запросов, которой могут злоупотребить. Эту директиву можно задать в контекстах http, server или location, что делает её гибкой в зависимости от требований конфигурации. Правильное использование и понимание этой директивы, особенно с точки зрения производительности и безопасности, имеет ключевое значение при интеграции NGINX с приложениями FastCGI.

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

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_pass_request_headers on;
    include fastcgi_params;
}

Описание

Директива `fastcgi_pass_request_body` используется в конфигурации NGINX, чтобы указать, должно ли тело HTTP-запроса клиента отправляться на FastCGI-сервер. Эта директива принимает в качестве аргумента флаг, который может быть 'on' или 'off'. Если установлено 'on', тело запроса пересылается на бэкенд FastCGI-сервер в рамках обработки запроса. Если же установлено 'off', тело запроса не отправляется, что фактически игнорирует любые данные, которые клиент мог отправить в теле запроса. Эта директива особенно полезна в ситуациях, когда обработка запроса не требует входных данных из тела, например при GET-запросах или при использовании FastCGI-сервера для операций, которые не обрабатывают входные данные. Правильное использование обеспечивает эффективную передачу данных и управление ответами между NGINX и FastCGI-бэкендом, минимизируя ненужную передачу данных, когда она не нужна. Часто она используется совместно с другими директивами FastCGI, такими как `fastcgi_pass`, чтобы гарантировать обращение к соответствующему серверу в зависимости от заданных контекстов запроса.

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

location /example {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_pass_request_body off;
}

Описание

Директива `fastcgi_intercept_errors` работает совместно с FastCGI и управляет тем, как NGINX обрабатывает ошибки, возвращаемые FastCGI-сервером, например HTTP-статусы 4xx или 5xx. При значении 'on' NGINX будет перехватывать эти ответные ошибки, что позволяет задавать пользовательские страницы ошибок или выполнять дополнительную обработку вместо прямой пересылки исходного ответа об ошибке FastCGI клиенту. Это особенно полезно в ситуациях, когда вы хотите отображать удобочитаемые сообщения об ошибках для пользователя или реализовать специфические механизмы восстановления после ошибок. Директива принимает булев флаг в качестве аргумента, который может быть 'on' или 'off'. Когда установлено 'on', любые ответные ошибки от FastCGI-сервера (например, со статусными кодами в диапазоне 400 или 500) могут быть обработаны с помощью конкретных конфигураций страниц ошибок, определённых в конфигурации NGINX. При значении 'off' поведение по умолчанию позволяет NGINX возвращать ответ FastCGI как есть, включая любые сообщения об ошибке. Директива может использоваться в контекстах 'http', 'server' или 'location', что даёт гибкость в выборе места установки в зависимости от требуемой области действия конфигурации обработки ошибок.

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

location /app {
    fastcgi_pass backend;
    fastcgi_intercept_errors on;
    fastcgi_index index.php;
    include fastcgi_params;
}

Описание

Директива `fastcgi_read_timeout` используется для указания продолжительности, в течение которой NGINX будет ожидать ответа от FastCGI сервера после отправки запроса. Это полезно в сценариях, когда обработка на стороне FastCGI может занять больше времени, чем ожидалось, и вы хотите избежать преждевременного закрытия соединений, которые всё ещё могут в итоге ответить. Таймаут применяется индивидуально к каждому запросу и может быть задан в разных контекстах, таких как `http`, `server` и `location`. Параметр этой директивы — значение времени, которое можно указать в секундах (s), минутах (m), часах (h) или днях (d). Если время ожидания превышено и ответ не получен, NGINX разорвёт соединение с FastCGI сервером и может вернуть клиенту ошибку. Настройка `fastcgi_read_timeout` может быть критически важна для оптимизации производительности приложений, которым требуется больше времени на обработку, например при выполнении сложных запросов к базе данных или операций с файлами. Важно отметить, что слишком низкое значение может привести к нежелательному закрытию соединений, тогда как слишком высокое — заставит клиентов ждать необоснованно долго ответа, который может никогда не поступить. Поэтому рекомендуется подбирать это значение, исходя из характеристик производительности приложения.

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

location /api {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_read_timeout 120s;
}

Описание

Директива `fastcgi_buffers` имеет решающее значение для настройки того, как NGINX обрабатывает ответ от FastCGI-сервера. Она задаёт количество буферов и размер каждого буфера, которые NGINX использует при чтении ответов. Эта директива помогает оптимизировать производительность и использование памяти, управляя тем, сколько данных может быть считано одновременно с FastCGI-бэкенда до отправки клиенту. Когда вы указываете `fastcgi_buffers` с двумя аргументами, первый аргумент обозначает количество буферов, а второй — размер каждого буфера. NGINX выделяет общее пространство буферов в соответствии с указанными значениями, что помогает эффективно буферизовать большие ответы и предотвращать преждевременную отправку клиентам частичных ответов. Буферы могут вмещать полный размер ответа от FastCGI-сервера, улучшая производительность приложений, которые генерируют большие ответы, например веб-приложений с интенсивной обработкой данных. Также важно отметить, что значение `fastcgi_buffers` должно быть установлено соответствующим образом, исходя из ожидаемого размера ответов, которые будет генерировать ваше приложение. Установка слишком малого значения может привести к снижению производительности или дополнительным накладным расходам, поскольку NGINX может вынужденно читать с FastCGI-бэкенда чаще, чем необходимо для формирования полного ответа.

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

fastcgi_buffers 16 8k;

Описание

В NGINX директива `fastcgi_busy_buffers_size` определяет максимальный размер пространства буферизации FastCGI, который может использоваться для обрабатываемых ответов. Это распределение памяти критично для управления тем, как FastCGI буферизует данные, отправляемые от вышестоящего сервера, прежде чем они будут переданы клиенту. Когда достигается размер, указанный в `fastcgi_busy_buffers_size`, NGINX начнёт либо отправлять клиенту накопленные в буфере ответы, либо обрабатывать трафик иначе в зависимости от настроек. Директива принимает один аргумент, задающий размер занятых буферов в байтах. Если выделенного буфера недостаточно, NGINX можно настроить так, чтобы либо отложить обработку, либо управлять потоком данных, обеспечивая корректный порядок ответов и их успешную доставку. Эта директива может влиять на производительность, особенно при высокой нагрузке: слишком маленький буфер может привести к ухудшению времени отклика и увеличению задержек, поскольку NGINX придётся часто сбрасывать буферы, чтобы вместить входящие данные. Для оптимальной производительности при настройке этой директивы следует учитывать ожидаемые максимальные размеры ответов от вышестоящего сервера и типичную нагрузку на сервер NGINX. Неправильная конфигурация может привести к узким местам в производительности, поэтому мониторинг и тестирование необходимы для подбора подходящих размеров буферов под конкретные потребности приложения.

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

http {
    server {
        location /api {
            fastcgi_pass 127.0.0.1:9000;
            fastcgi_busy_buffers_size 16k;
            include fastcgi_params;
        }
    }
}

Описание

Директива `fastcgi_force_ranges` используется в NGINX для обработки запросов диапазонов байтов, отправляемых на FastCGI backend. По умолчанию некоторые приложения FastCGI могут некорректно поддерживать диапазоны байтов, что приводит к неправильной доставке содержимого при частичных запросах. Когда эта директива включена (установлена в 'on'), NGINX обеспечит, что запросы с диапазонами байтов правильно интерпретируются и обрабатываются FastCGI server, принуждая его отвечать с `206 Partial Content`, при условии, что указанный диапазон действителен. На практике данная директива особенно важна при отдаче видео- или аудиоконтента по HTTP, когда клиенты могут запрашивать определённые диапазоны байтов для потоковой передачи. Поручая FastCGI server учитывать такие запросы с диапазонами, NGINX повышает совместимость и эффективность доставки содержимого. Директива может применяться глобально или в рамках конкретных контекстов server и location, что делает её гибкой для различных конфигураций сайтов. Директива `fastcgi_force_ranges` принимает флаг: он может быть установлен в 'on' или 'off', при этом 'off' отключает принудительное поведение ответа. Когда она включена, NGINX взаимодействует напрямую с FastCGI server для согласования и управления диапазонами байтов, обеспечивая клиентам получение соответствующих сегментов данных, которые они запрашивают. Такое поведение улучшает опыт конечного пользователя, особенно для приложений с богатым медиа-контентом.

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

server {
    location /api {
        fastcgi_pass backend;
        fastcgi_force_ranges on;
    }
}

Описание

Директива 'fastcgi_limit_rate' используется для контроля пропускной способности, выделяемой ответам FastCGI, предлагая способ задать ограничения на скорость передачи данных от NGINX к бэкенду FastCGI. Это помогает управлять нагрузкой на сервер и оптимизировать распределение ресурсов в ситуациях, когда отдельные приложения FastCGI могут генерировать чрезмерный трафик, особенно в периоды высокого спроса. Когда директива установлена, она задаёт максимальное количество байт в секунду, которые могут быть отправлены на сервер FastCGI. Если эта скорость превышается, NGINX временно приостанавливает отправку заголовков и возобновляет её только после того, как скорость передачи данных опустится ниже заданного порога. Важно отметить, что 'fastcgi_limit_rate' принимает один аргумент, который обычно указывается в байтах в секунду и может использовать суффиксы, такие как 'k' для килобайт или 'm' для мегабайт, что облегчает настройку ограничений пропускной способности. Директиву можно размещать в контекстах 'http', 'server' или 'location', что даёт гибкость в применении разных ограничений в зависимости от области действия вашего приложения или структуры сайта. Администраторы могут точно настроить, сколько пропускной способности выделяется на обработку FastCGI, что позволяет лучше управлять производительностью в различных условиях.

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

location /fastcgi {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_limit_rate 100k;
}

Описание

Директива `fastcgi_cache` задает зону общей памяти, используемую для хранения ответов FastCGI, фактически кэшируя их, чтобы снизить нагрузку на сервер и ускорить время ответа для часто запрашиваемого контента. Когда сервер FastCGI формирует ответ, он может кэшироваться на основе параметров запроса, что позволяет последующим идентичным запросам обслуживаться из кэша вместо повторного формирования ответа через обращение к бэкенд-серверу. Директива требует аргумента — имени зоны кэша, которая предварительно определяется с помощью директивы `fastcgi_cache_path`. Её можно использовать в различных контекстах, таких как блоки `http`, `server` и `location`, что позволяет осуществлять точечный контроль над тем, как разные локации обрабатывают кэширование. В сочетании с сопутствующими директивами, такими как `fastcgi_cache_key`, администраторы могут определить, что считается уникальной записью в кэше, тем самым настраивая поведение механизма кэширования под потребности приложения. Поведение кэширования также определяется связанными директивами, такими как `fastcgi_cache_valid`, которая задаёт время, в течение которого записи в кэше считаются действительными, и `fastcgi_cache_bypass`, позволяющая динамически управлять обходом кэша, что обеспечивает возможность предоставления обновлённых данных, когда это необходимо.

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

http {
    fastcgi_cache_path /tmp/cache levels=1:2 keys_zone=my_cache:10m;
    server {
        location / {
            fastcgi_pass backend;
            fastcgi_cache my_cache;
            fastcgi_cache_valid 200 1h;
        }
    }
}

Описание

Директива `fastcgi_cache_key` играет ключевую роль в определении уникального ключа, используемого при сохранении или извлечении закэшированных ответов FastCGI. Формируя ключ кэша, она позволяет NGINX различать разные элементы кэша в зависимости от конкретики запроса. Этот ключ может быть комбинацией переменных, что позволяет эффективно сохранять и извлекать динамический контент, обеспечивая точные и релевантные попадания в кэш для конкретных запросов. При определении ключа кэша вы можете использовать различные переменные, доступные в NGINX, которые могут представлять такие атрибуты, как запрошенный URI, метод запроса или другие заголовки. Конфигурация позволяет реализовать индивидуальные стратегии кэширования для оптимизации производительности и использования ресурсов. Директива действует в контекстах, таких как `http`, `server` и `location`, обеспечивая гибкость на разных уровнях конфигурации NGINX. Важно отметить, что неправильная настройка `fastcgi_cache_key` может привести к несоответствиям в кэше и, как следствие, к выдаче некорректных ответов пользователям. Поэтому крайне важно тщательно конструировать ключ кэша, чтобы полностью воспользоваться возможностями кэширования NGINX и избежать непредвиденного поведения.

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

fastcgi_cache_key "$scheme$request_method$host$request_uri";

Описание

Директива `fastcgi_cache_path` используется для определения параметров хранения FastCGI-кэша в NGINX. Эта директива задаётся внутри блока `http` и указывает путь, в котором будут храниться кэшированные файлы, а также настройки для размера зоны кэша, ключей и других параметров. По сути она создаёт каталог, содержащий данные ответов от FastCGI-сервера, что может значительно ускорить время ответа за счёт выдачи кэшированного содержимого вместо перенаправления запросов к бэкенд-серверу каждый раз. Эта директива требует как минимум двух аргументов: путь кэша и строку конфигурации зоны кэша, которая обычно включает имя и размер кэша. Зона кэша определяет, как NGINX сегментирует и управляет кэшированными ответами. Также можно указать дополнительные параметры, такие как `inactive` или `max_size`, чтобы задать, как долго элементы будут храниться в кэше или максимальный размер кэша соответственно. Важность этой директивы трудно переоценить, так как правильная настройка FastCGI-кэша может привести к улучшению производительности и снижению нагрузки на бэкенд-серверы.

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

http {
    fastcgi_cache_path /var/cache/nginx/fastcgi_cache levels=1:2 keys_zone=fastcgi_cache:10m inactive=60m max_size=1g;
}

Описание

Директива `fastcgi_cache_bypass` является частью HTTP-модуля NGINX и используется для управления механизмами кэширования FastCGI. При настройке эта директива принимает одно или несколько условий (переменные или атрибуты запроса клиента), которые определяют, когда NGINX должен пропустить кэшированный ответ и вместо этого получить свежий от upstream-сервера. Она особенно полезна в ситуациях, когда необходимо гарантировать возврат клиентам самых актуальных данных в зависимости от их запросов или определённых условий, таких как конкретные заголовки, куки или параметры запроса, которые указывают на то, что нужен динамический ответ, а не закэшированный. Эту директиву можно задать в контекстах `http`, `server` или `location`, что даёт гибкость в области её применения. Как правило, используют переменные, такие как `$arg_argname` для обращения к конкретным параметрам запроса, `$http_cookie` для кук, или даже пользовательские заголовки приложения для создания соответствующих условий обхода. Это помогает оптимизировать использование ресурсов, позволяя при необходимости отдавать устаревшие данные, одновременно обеспечивая выдачу самых свежих данных, когда это необходимо. В сочетании с другими директивами, связанными с кэшированием FastCGI, такими как `fastcgi_cache` и `fastcgi_cache_key`, она обеспечивает надёжную стратегию кэширования для повышения производительности при сохранении актуальности содержимого в зависимости от взаимодействия с пользователем и чувствительности данных.

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

location / { 
    fastcgi_pass backend;
    fastcgi_cache my_cache;
    fastcgi_cache_bypass $http_cache_bypass;
}

Описание

Директива `fastcgi_no_cache` используется, чтобы указать NGINX, следует ли кэшировать ответы от FastCGI-серверов, таких как обработчики PHP. Эта директива принимает одну или несколько переменных или условий, определяющих правила кэширования. Например, если значение указанной переменной истинно, NGINX не кэширует ответ, что позволяет генерировать динамический контент без задержек, вызванных попаданиями в кэш. Она работает совместно с директивой `fastcgi_cache_bypass` для обеспечения согласованного поведения кэширования на основе похожих условий. Директива должна быть задана в контексте `http`, `server` или `location` в конфигурационном файле NGINX и обычно используется вместе с настройками кэширования для достижения оптимальной производительности. Она особенно полезна в приложениях, где требуется инвалидировать кэш в определённых обстоятельствах, например, когда пользователь вошёл в систему, или содержимое ответа значительно меняется в зависимости от параметров запроса. Эффективно управляя динамическим контентом, `fastcgi_no_cache` помогает поддерживать актуальность данных приложения и улучшает пользовательский опыт в веб-приложениях.

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

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_no_cache $http_cache_control;
}

Описание

Директива `fastcgi_cache_valid` задаёт период времени, в течение которого кэшированный ответ FastCGI считается действительным, то есть может быть отдан без повторного запроса к backend server. Эта директива принимает интервал времени и конкретный код ответа или диапазон кодов ответа. Например, использование `fastcgi_cache_valid 200 10m;` указывает, что ответ 200 OK будет кэшироваться в течение 10 минут. Можно указать несколько строк этой директивы, чтобы задать разные периоды действия для разных кодов ответа. Важно отметить, что директива должна располагаться в соответствующем контексте, например в блоках http, server или location, и работает в сочетании с директивой `fastcgi_cache`. Когда отдается действительный кэш, директива `fastcgi_cache_bypass` может использоваться для условного обхода кэша. Это обеспечивает большую гибкость в поддержании актуального содержимого при необходимости, при этом сохраняя преимущества кэширования для повторяющихся запросов.

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

fastcgi_cache my_cache;
fastcgi_cache_valid 200 10m;
fastcgi_cache_valid 404 1m;

Описание

Директива `fastcgi_cache_min_uses` задаёт минимальное количество одинаковых запросов к конкретному URI, которое должно быть выполнено, прежде чем его ответ будет помещён в кэш. Это особенно полезно, чтобы избежать кэширования ответов для малопосещаемых конечных точек, гарантируя сохранение в кэше только часто запрашиваемого содержимого. Значение этой директивы должно быть положительным целым числом, так как оно указывает, сколько раз должен поступить запрос к одному и тому же ресурсу до принятия решения о кэшировании ответа. Когда количество запросов к конкретному URI достигает или превышает значение, определённое директивой `fastcgi_cache_min_uses`, для этого ответа срабатывает механизм кэширования. Это помогает оптимизировать поведение кэша, предотвращая занятость кэш-памяти редкими или неактуальными ответами. Директиву можно задать в контекстах `http`, `server` или `location`, что позволяет обеспечить детальный контроль в зависимости от потребностей приложения. Минимизируя потенциальное загрязнение кэша ответами для редко запрашиваемых URI, вы можете повысить производительность приложения и эффективность использования кэш-памяти. Это особенно полезно в сценариях с динамическим содержимым, когда некоторые ответы не должны кэшироваться, если они не запрашиваются часто.

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

http {
    fastcgi_cache_path /path/to/cache levels=1:2 keys_zone=my_cache:10m;
    server {
        location /api {
            fastcgi_pass 127.0.0.1:9000;
            fastcgi_cache my_cache;
            fastcgi_cache_min_uses 5;
        }
    }
}

Описание

Директива `fastcgi_cache_max_range_offset` задаёт максимальное количество байт, которое может быть указано в качестве смещения, когда клиент выполняет range‑запрос к ресурсу, обслуживаемому кэшированием FastCGI. Эта директива помогает оптимизировать поведение кэша и ответы для частично загруженных ресурсов, гарантируя, что сервер не выдаёт устаревшие или избыточные данные, когда клиенты запрашивают только определённые части файла. Установка этой директивы с числовым значением позволяет контролировать детализацию ответа на range‑запросы к кешированному содержимому. Если смещение превышает указанное значение, NGINX может отказаться от выполнения range‑запроса или обработать его иначе в зависимости от реализации модуля FastCGI и применяемой стратегии кэширования. Это особенно полезно в ситуациях, где критично минимизировать потребление пропускной способности, или для более эффективной выдачи ответов при работе с большими файлами, к которым часто обращаются по частям. Эту директиву можно применять в разных контекстах, включая http, server и location-блоки в файле конфигурации NGINX, что делает её гибкой для различных сценариев использования и настроек сервера.

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

http {
    fastcgi_cache_path /var/cache/nginx/fastcgi_temp levels=1:2 keys_zone=my_cache:10m;
    server {
        location / {
            fastcgi_pass backend;
            fastcgi_cache my_cache;
            fastcgi_cache_max_range_offset 1048576;  # 1 MB
        }
    }
}

Описание

Директива `fastcgi_cache_use_stale` позволяет NGINX выдавать устаревшие кешированные ответы в определённых условиях, улучшая пользовательский опыт и производительность за счёт сокращения простоев или задержек при проблемах с сервером. Эту директиву можно включать для различных сценариев, включая 'error', 'timeout', 'invalid_header' или 'updating'. Если запрос сталкивается с такими проблемами, вместо возврата ошибки NGINX может отдать последний успешно закешированный ответ. Такое поведение особенно полезно в конфигурациях с высокой доступностью, когда важно поддерживать вовлечённость пользователей, даже если серверы бэкенда испытывают временные проблемы. Эту директиву можно задавать в нескольких контекстах: `http`, `server` и `location`, что делает её гибкой для различных конфигураций. Каждый переданный аргумент должен указывать, в каких сценариях следует возвращать устаревшие данные. Если указано несколько условий, устаревший контент будет выдан, если выполнено любое из них. Директива работает совместно с директивой `fastcgi_cache` и фактически повышает устойчивость механизма кэширования, смягчая влияние сбоев upstream или медленных ответов на опыт клиента.

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

location /api {
    fastcgi_pass backend;
    fastcgi_cache my_cache;
    fastcgi_cache_use_stale error timeout;
}

Описание

Директива fastcgi_cache_methods используется в конфигурации NGINX, чтобы задавать, какие HTTP-методы (например, GET или POST) будут кэшироваться при использовании FastCGI. По умолчанию NGINX кэширует только ответы на GET-запросы, что подходит для страниц, которые редко меняются и могут обслуживаться напрямую из кэша. Однако в некоторых случаях приложения могут возвращать на POST-запросы ответы, которые выгодно кэшировать для повышения производительности и снижения нагрузки на бэкенд-сервер. Эта директива позволяет администраторам настроить поведение кэширования в соответствии с потребностями приложения. Директива принимает в качестве параметра один или несколько HTTP-методов. Например, указание "GET POST" позволяет кэшировать как GET, так и POST-запросы. Важно учитывать природу запроса и связанного с ним ответа: не все POST-запросы следует кэшировать, так как они часто приводят к изменению состояния. Неправильное кэширование таких запросов может привести к некорректной работе приложения или к тому, что пользователям будет выдаваться устаревший контент. При применении этой директивы её можно размещать в контексте http, server или location, что обеспечивает гибкость конфигурации кэширования в зависимости от требуемой степени детализации управления. Если указанные методы не соответствуют ожидаемому поведению вашего приложения, это может непреднамеренно привести к узким местам в производительности или к сценариям некорректного кэширования.

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

location ~ \.php$ {
    fastcgi_pass   backend;
    fastcgi_cache  my_cache;
    fastcgi_cache_methods GET POST;
}

Описание

Директива 'fastcgi_cache_lock' может использоваться для предотвращения одновременной генерации одинаковых ответов FastCGI несколькими запросами. При включении, если два или более запросов обращаются к одному и тому же кэшируемому ресурсу, только первый запрос будет продолжен для генерации upstream-ответа. Последующие запросы будут поставлены в очередь до тех пор, пока ответ не будет сгенерирован и помещён в кэш, после чего они смогут отдавать кэшированный ответ вместо отправки множества запросов к upstream. Директива принимает флаг ('on' или 'off'). При установке в 'on' NGINX применяет механизм блокировки, позволяя только одному запросу генерировать ответ, пока остальные ждут. Установка в 'off' отключает это поведение, в результате чего все запросы к одному и тому же ресурсу могут одновременно генерировать новые upstream-запросы, что может привести к повышенной нагрузке и проблемам с производительностью в условиях высокого трафика. Важно отметить, что использование 'fastcgi_cache_lock' может повысить эффективность в сценариях, где вероятны случаи одновременной генерации кэша, но это должно совмещаться с подходящей стратегией кэширования, чтобы обеспечить оптимальную производительность при максимальном использовании кэша.

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

location /api {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_cache my_cache;
    fastcgi_cache_lock on;
    fastcgi_cache_key "$scheme$request_method$host$request_uri";
}

Описание

Директива `fastcgi_cache_lock_timeout` задаёт длительность, в течение которой запрос будет ожидать получения блокировки в FastCGI cache, если другой запрос уже обрабатывает эту запись кэша. Это особенно полезно в сценариях, когда запросы могут сталкиваться при попытке сохранить одинаковое кэшированное содержимое. Если время ожидания истечёт до того, как блокировка будет получена, запрос на блокировку терпит неудачу, что предотвращает длительные задержки для параллельных запросов и позволяет им продолжить выполнение вместо бесконечного ожидания. Эта директива может помочь улучшить время отклика вашего приложения, особенно при высокой нагрузке. Установив `fastcgi_cache_lock_timeout`, вы можете точно контролировать, сколько времени один запрос будет ждать другой, уменьшая задержку и улучшая общий пользовательский опыт в периоды пикового трафика. Директива должна задаваться в соответствующем контексте, таком как `http`, `server` или `location`, и принимает один аргумент — длительность тайм-аута. Когда настроенный тайм-аут достигается, последующие запросы могут получить альтернативный ответ или обрабатываться иначе в зависимости от внутренней логики приложения. Поэтому при выборе значения для этой директивы следует тщательно взвесить поведение блокировок и общую производительность.

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

location /api {
    fastcgi_pass backend;
    fastcgi_cache my_cache;
    fastcgi_cache_lock on;
    fastcgi_cache_lock_timeout 10s;
}

Описание

Директива `fastcgi_cache_lock_age` в HTTP-модуле NGINX задаёт максимальное время в секундах, которое запрос должен ожидать доступности блокировки кэша `FastCGI`, если кэш уже заблокирован другим запросом. Когда поступает несколько запросов к одному ресурсу и кэш заблокирован из-за обработки того же содержимого другим запросом, эта директива предотвращает бесконечное ожидание запросов. Вместо этого заданный период ожидания (устанавливаемый этой директивой) позволяет повторить запросы после определённого времени. Это помогает оптимизировать время ответа для пользователей и улучшает общую производительность сервера, избегая чрезмерных задержек в ожидании. Параметр для `fastcgi_cache_lock_age` задаётся в секундах и принимает целочисленное значение. Например, если эта директива установлена в 10, любой запрос, столкнувшийся с блокировкой кэша, будет ждать максимум 10 секунд, прежде чем отказаться от получения блокировки и отправить новый запрос. Слишком большие значения могут привести к задержкам в ответах пользователям, тогда как слишком маленькие — к ненужным промахам кэша. Администраторам следует подбирать значение параметра `fastcgi_cache_lock_age`, исходя из ожидаемых шаблонов доступа к кэшу для их приложений и допустимой задержки для конечных пользователей.

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

location /app {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_cache my_cache;
    fastcgi_cache_lock on;
    fastcgi_cache_lock_age 10;
}

Описание

Директива 'fastcgi_cache_revalidate' в NGINX позволяет более тонко контролировать повторную проверку кешированных ответов от FastCGI-бэкендов. Когда эта директива установлена в 'on', NGINX будет отправлять условные запросы с использованием заголовков 'If-Modified-Since' или 'If-None-Match' на основе кешированного содержимого. Это гарантирует, что если содержимое изменилось на бэкенде, клиент получит обновлённый ответ соответственно. Такое поведение помогает поддерживать кешированное содержимое актуальным, одновременно минимизируя ненужные запросы к бэкенду, что может улучшить производительность в средах с динамическим содержимым, которое не меняется часто. В противоположность этому, когда значение установлено в 'off', NGINX будет отдавать кешированные ответы без запроса к бэкенду на предмет обновлений, что может привести к отдаче устаревшего содержимого, если исходные данные изменились. Директива особенно полезна при работе с содержимым, частота обновления которого непредсказуема, так как она находит баланс между обслуживанием из кеша и обеспечением того, чтобы пользователи получали наиболее свежую версию ответа, не теряя преимуществ эффективности кеширования.

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

http {
    fastcgi_cache_path /var/cache/nginx/fastcgi_tmp levels=1:2 keys_zone=my_cache:10m;

    server {
        location /fastcgi {
            include fastcgi_params;
            fastcgi_pass backend;
            fastcgi_cache my_cache;
            fastcgi_cache_revalidate on;
        }
    }
}

Описание

Директива `fastcgi_cache_background_update` — это логический параметр, который определяет, будет ли NGINX обновлять закэшированный FastCGI-контент в фоновом режиме, если контент при доступе устарел. При значении `on` это позволяет одновременно отдавать существующий закэшированный ответ, в то время как выполняется новый запрос для получения обновлённого содержимого, что особенно полезно при высокой нагрузке, когда ожидание обновления кэша может приводить к задержкам и увеличению времени загрузки. Это означает, что пользователи продолжат получать кэшированную версию, пока потенциально продолжительный запрос к бэкенду обрабатывается в фоне. Напротив, если директива установлена в `off` (по умолчанию), пользователи, запрашивающие устаревшие кэшированные ответы, будут вынуждены ждать выполнения нового запроса прежде чем получить обновлённую версию. Это менее эффективно с точки зрения пользовательского опыта и использования ресурсов. Директива может применяться в контекстах `http`, `server` или `location`, что даёт гибкость в управлении поведением кэша в зависимости от потребностей приложения или конкретных маршрутов. Правильная настройка этой директивы может значительно повысить отзывчивость и скорость веб-приложений, сильно зависящих от FastCGI-кэширования, так как она минимизирует нагрузку и время ожидания при обновлении кэша. Однако необходимо тщательно продумать стратегию инвалидизации кэша, чтобы не допустить длительной выдачи устаревшего содержимого, особенно в динамических приложениях с частыми изменениями данных.

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

location /api {
    fastcgi_pass backend;
    fastcgi_cache my_cache;
    fastcgi_cache_background_update on;
}

Описание

Директива `fastcgi_temp_path` определяет путь к файлам, в которых NGINX хранит временные данные, создаваемые в процессе обработки FastCGI. Это особенно полезно при работе с большими ответами или когда вывод от FastCGI буферизуется. Указанный путь должен быть доступен для записи рабочими процессами NGINX. Можно указать до четырёх каталогов, разделённых пробелами; NGINX будет использовать первый доступный каталог для хранения временных файлов, что позволяет распределять нагрузку по нескольким дискам при необходимости. Когда обрабатывается запрос FastCGI и ответ превышает определённые пределы буферов, NGINX записывает данные в указанные временные файлы до тех пор, пока весь ответ не будет обработан, прежде чем отправить его клиенту. Это повышает общую производительность, позволяя NGINX эффективно управлять использованием памяти и предотвращая сбои из-за чрезмерного потребления памяти. Структуру каталогов, возможно, потребуется создать заранее, и важно установить соответствующие права доступа, чтобы избежать проблем с доступом.

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

fastcgi_temp_path /var/tmp/nginx/fastcgi_temp;

Описание

Директива 'fastcgi_max_temp_file_size' задаёт максимальный размер, который могут достигать временные файлы, создаваемые NGINX для буферизации данных ответов FastCGI. Если размер ответа превышает этот предел, NGINX вернёт ошибку 502 Bad Gateway и отклонит запрос. Это особенно полезно для управления ресурсами сервера и предотвращения того, чтобы чрезмерно большие ответы FastCGI не занимали всё доступное дисковое пространство. Эта директива может применяться в нескольких контекстах, включая 'http', 'server' и 'location', что обеспечивает гибкость конфигурации в зависимости от сценария использования. Значение задаётся в байтах, и следует с осторожностью выбирать соответствующий размер, исходя из ожидаемого объёма ответов FastCGI. Слишком маленький размер может привести к увеличению числа ошибок, тогда как слишком большой — к чрезмерному использованию дискового пространства, особенно при высокой нагрузке. При применении директивы необходимо учитывать характеристики рабочей нагрузки вашего приложения и доступное дисковое пространство. Может потребоваться мониторинг и корректировка этой настройки по мере изменения размеров ответов со временем или в зависимости от закономерностей пользовательской нагрузки, чтобы приложение оставалось производительным и устойчивым к неожиданным всплескам трафика.

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

location /cgi-bin {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_max_temp_file_size 16m;
}

Описание

Директива `fastcgi_temp_file_write_size` в NGINX используется для определения максимального размера временных файлов, которые модуль FastCGI может записывать при обработке запросов. Эта директива особенно полезна при работе с большими ответами, поскольку помогает эффективно управлять использованием памяти и дискового пространства, снижая риск перегрузки сервера. Установив эту директиву, администраторы могут увеличить или уменьшить допустимый размер в зависимости от ожидаемых размеров ответов FastCGI. Директива принимает один аргумент — значение размера (байт). Если размер ответа превышает указанный предел, ответ будет записан во временный файл, а не напрямую в память. Это уменьшает всплески использования памяти и позволяет серверу эффективнее обрабатывать больше запросов, при необходимости используя диск. Эту директиву можно задавать в любом контексте: http, server или location, что делает её гибкой для разных конфигураций. Однако при настройке важно учитывать доступное дисковое пространство и влияние записи на диск на производительность. Следует выбрать подходящее значение, исходя из обычной нагрузки приложения и характеристик ответов FastCGI.

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

http {
    fastcgi_temp_file_write_size 16k;
}

Описание

Директива 'fastcgi_next_upstream' позволяет указать, при каких условиях запрос к серверу FastCGI должен быть повторно отправлен на следующий сервер из настроенной группы upstream. Эта директива может принимать один или несколько параметров, которые соответствуют конкретным сценариям, таким как тайм-ауты, не-2xx ответы и ошибки соединения. Включив эту директиву, NGINX способен более корректно обрабатывать потенциальные ошибки сервера, пытаясь выполнить запрос на альтернативном сервере, что повышает устойчивость и надёжность веб-приложений. Например, типичный сценарий использования предполагает развертывание нескольких серверов FastCGI для обработки PHP. Включив директиву 'fastcgi_next_upstream' с параметрами, такими как 'error' и 'timeout', NGINX попытается повторно отправить неудачный запрос на другой настроенный сервер FastCGI, если исходный сервер столкнулся с ошибкой или не отвечает в течение определённого времени. Эта функция особенно полезна в средах с балансировкой нагрузки, где критично поддержание высокой доступности. Полный набор параметров включает опции, такие как 'error', 'timeout', 'invalid_header', 'http_500' и другие, что позволяет тонко настроить, при каких ошибочных условиях должна срабатывать повторная отправка. Возможность повторных попыток на основе ошибок помогает смягчать последствия сбоев отдельных серверов, обеспечивая бесшовный опыт для пользователей и поддерживая высокую доступность. Однако следует внимательно настроить эту директиву, чтобы не создавать дополнительную нагрузку при возникновении ошибок.

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

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_next_upstream error timeout invalid_header;
    include fastcgi_params;
}

Описание

Директива `fastcgi_next_upstream_tries` определяет, сколько upstream‑серверов следует опробовать в случае неудачного запроса FastCGI. Установив эту директиву, NGINX позволяет распределять нагрузку между бэкенд‑серверами FastCGI, пытаясь повторно отправить запрос на указанное количество других серверов, если первоначальный сервер отказал. Это особенно полезно в сценариях, где критична высокая доступность и необходимо обеспечить работу приложения даже при недоступности одного или нескольких upstream‑серверов. При указании значения этой директивы его можно задать в контекстах http, server или location, что позволяет тонко настроить поведение в зависимости от потребностей приложения. Например, можно задать большее значение в location, более подверженном сбоям, и более низкое — в более стабильных частях приложения. Указанное значение должно быть положительным целым числом; при значении 0 функция фактически отключается, и NGINX не будет пытаться повторно обращаться к другим upstream‑серверам. Стоит отметить, что эта директива взаимодействует с другими, связанными с FastCGI, директивами, в частности с `fastcgi_next_upstream`, которая определяет условия, при которых будут происходить повторы. Совместное использование обеих директив обеспечивает комплексный контроль над тем, как NGINX обрабатывает сбои бэкенда и переключение на резервный сервер.

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

location /api {
    fastcgi_pass backend;
    fastcgi_next_upstream_tries 3;
}

Описание

Директива `fastcgi_next_upstream_timeout` задаёт продолжительность таймаута для последующих запросов FastCGI, когда первоначальный запрос завершается неудачей. Эта директива даёт тонкий контроль над тем, сколько времени сервер будет ждать, прежде чем отказаться от FastCGI upstream после неудачной первой попытки. Указание этого таймаута может быть критически важным для приложений, для которых время отклика имеет значение, и где сервер может повторно отправлять запросы на другой бэкенд для получения более быстрого ответа. Таймаут можно задавать в разных контекстах, включая http, server и location-блоки, что обеспечивает гибкость в зависимости от потребностей конфигурации. Директива принимает значение времени в качестве аргумента, обычно в секундах. Если указанный таймаут истекает без получения ответа от upstream-сервера FastCGI, NGINX прерывает запрос и аналогичным образом переходит к следующему upstream. Такое поведение гарантирует, что серверы остаются отзывчивыми и могут корректно обрабатывать сбои приложений FastCGI. Иногда разработчики могут захотеть скорректировать этот таймаут в зависимости от производительности приложения и необходимых стратегий переключения, чтобы обеспечить более высокую доступность и снизить задержки при обслуживании запросов.

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

location /api {
    fastcgi_pass backend;
    fastcgi_next_upstream_timeout 10s;
    include fastcgi_params;
}

Описание

Директива `fastcgi_param` используется в конфигурации NGINX для установки переменных окружения, которые передаются серверам FastCGI. По умолчанию она применяется в контекстах, таких как `http`, `server` и `location`, что обеспечивает гибкость при настройке поведения FastCGI для разных маршрутов приложения. Директива принимает два или три параметра: первый параметр — имя переменной, второй — её значение, а опционально третий параметр может указывать, должно ли значение браться из заголовка запроса. Когда директива `fastcgi_param` используется, она по сути передаёт информацию, относящуюся к обработке запроса FastCGI. Например, можно задать параметры, такие как `SCRIPT_FILENAME`, который указывает скрипт для выполнения на сервере FastCGI. Эта директива гарантирует, что необходимые переменные доступны приложению FastCGI для корректного ответа на запрос пользователя. Она особенно полезна, когда требуется явно определить, как определённые переменные должны обрабатываться логикой приложения FastCGI. Важно отметить, что `fastcgi_param` перезаписывает любые параметры с тем же именем, уже заданные в конфигурации, что позволяет точно контролировать окружение, передаваемое обработчику FastCGI, и тем самым избегать конфликтов или непредвиденного поведения значений переменных.

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

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

Описание

Директива 'fastcgi_pass_header' позволяет определить, какие HTTP-заголовки, полученные от FastCGI сервера, должны быть включены в ответ, отправляемый клиенту. Эта директива может быть задана несколько раз в одном и том же контексте, что позволяет передавать несколько заголовков. Когда запрос обрабатывается и FastCGI сервер возвращает заголовки, NGINX фильтрует эти заголовки на основе конфигурации, заданной с помощью 'fastcgi_pass_header'. В итоговый ответ клиенту будут включены только те заголовки, которые соответствуют указанным в этой директиве; все остальные заголовки будут проигнорированы. Это особенно полезно для контроля того, какая метаинформация или директивы возвращаются клиенту, повышая безопасность или позволяя сосредоточиться только на релевантных данных. Директива 'fastcgi_pass_header' может быть определена в контекстах 'http', 'server' и 'location', что делает ее гибкой для различных конфигураций. С помощью этой директивы администраторы могут гарантировать, что чувствительные заголовки не будут раскрыты, или что нерелевантные заголовки не будут засорять ответы. Важно отметить, что эта директива используется совместно с конфигурацией FastCGI и требует директивы 'fastcgi_pass' для направления трафика на FastCGI сервер. Важный аспект ее настройки заключается в том, что имена заголовков нечувствительны к регистру, тогда как значения могут быть чувствительны к регистру в зависимости от приложения. Поэтому при указании заголовков для передачи убедитесь, что точное написание и регистр значений остаются последовательными для корректной работы.

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

location /some_location {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_pass_header X-My-Custom-Header;
}

Описание

Директива 'fastcgi_hide_header' используется в конфигурации NGINX для указания, какие заголовки из ответа сервера FastCGI не должны отправляться клиенту. Эта директива может предотвратить раскрытие отдельных заголовков по причинам безопасности или эксплуатации, тем самым помогая поддерживать чистый интерфейс, скрывая от клиентов ненужную или конфиденциальную информацию. Она принимает один аргумент — имя HTTP-заголовка, который вы хотите скрыть. Например, указание 'fastcgi_hide_header X-Powered-By;' предотвратит возврат заголовка 'X-Powered-By' клиенту, даже если приложение FastCGI включает его в свой ответ. Эта директива может размещаться в различных контекстах, включая 'http', 'server' и 'location', что обеспечивает гибкость конфигурации в зависимости от того, где вы хотите применить подавление заголовков. Когда указанный заголовок присутствует в ответе FastCGI, NGINX просто не будет включать его в итоговый HTTP-ответ, отправляемый клиенту, тем самым не раскрывая потенциально конфиденциальную информацию. Эта функция особенно полезна при работе с приложениями, которые раскрывают информацию, которую можно использовать для атак по снятию отпечатков, либо при настройке приложений с учётом специфических требований безопасности.

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

location /api {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_hide_header X-Powered-By;
}

Описание

Директива `fastcgi_ignore_headers` используется для указания, какие заголовки из ответов FastCGI следует игнорировать NGINX при обработке ответа. По умолчанию NGINX возвращает клиенту все заголовки ответа FastCGI. Однако в некоторых ситуациях вы можете захотеть подавить отправку отдельных заголовков клиентам, например некоторых заголовков, связанных с безопасностью, или заголовков, изменяющих поведение кэширования. Эта директива принимает одно или несколько имён заголовков в качестве аргументов. Когда указанный в директиве заголовок присутствует в ответе FastCGI, NGINX полностью его игнорирует и не пересылает клиенту. Это особенно полезно для защиты приложения и управления тем, как обрабатываются определённые ответы, без изменения поведения вашего upstream-приложения. Например, игнорирование `X-Powered-By` может помочь предотвратить раскрытие используемой серверной технологии. Директиву `fastcgi_ignore_headers` можно использовать в контекстах `http`, `server` и `location`, что обеспечивает гибкость в разных конфигурациях. Вы можете указать любую комбинацию заголовков для игнорирования, что даёт тонкий контроль над тем, какая информация раскрывается клиентам.

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

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_ignore_headers X-Powered-By;
    include fastcgi_params;
}

Описание

Директива 'fastcgi_catch_stderr' используется в контекстах 'http', 'server' и 'location' для управления обработкой сообщений об ошибках, создаваемых приложениями FastCGI. Когда она включена, любые сообщения, отправленные приложением FastCGI в стандартный поток ошибок, будут перехватываться и записываться NGINX, что облегчает отладку и предоставляет видимость проблем приложения непосредственно в журнале ошибок NGINX. По умолчанию эта директива установлена в 'off', то есть NGINX перехватывает только стандартный вывод, если это явно не включено. Эта директива принимает один аргумент: 'on' или 'off'. Установив значение 'on', разработчик может получить ценную информацию об ошибках, которая может быть критически важна для диагностики проблем в приложениях FastCGI, особенно в производственных средах, где просмотр этих логов может заранее указать на возможные ошибки в выполнении кода. Важно учитывать, что чрезмерное логирование может привести к ухудшению производительности, если приложение генерирует много сообщений об ошибках, поэтому рекомендуется аккуратно управлять уровнями логирования. Правильное использование 'fastcgi_catch_stderr' повышает общую сопровождаемость приложений FastCGI, централизуя логирование ошибок через NGINX и предоставляя разработчикам ясное представление о ошибках времени выполнения, которые могут не проявляться в других местах. Тем не менее при использовании этой директивы следует учитывать компромисс с точки зрения производительности при повышенных уровнях детализации логов, особенно при высоких нагрузках.

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

location /api {
    fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_index index.php;
    fastcgi_catch_stderr on;
}

Описание

Директива `fastcgi_keep_conn` в NGINX, применимая в контекстах http, server и location, представляет собой флаг, определяющий, поддерживать ли постоянное соединение между NGINX и FastCGI-сервером после завершения запроса. По умолчанию после обработки запроса соединение с FastCGI-сервером закрывается. Однако установка этой директивы в 'on' будет поддерживать соединение открытым для последующих запросов, снижая задержку для следующих запросов и потенциально улучшая производительность в средах с высокой нагрузкой, где к одному и тому же FastCGI-серверу отправляется несколько запросов. Когда `fastcgi_keep_conn` включена, соединения переиспользуются вместо постоянного открытия и закрытия, что экономит ресурсы и повышает пропускную способность. Это особенно полезно для приложений, размещённых в конфигурациях, где часто идут последовательные запросы, например при генерации динамического контента в PHP или аналогичных технологиях. Тем не менее, удержание открытых соединений может занять ресурсы сервера, поэтому эту опцию следует использовать осторожно в зависимости от поведения приложения и общей способности сервера обрабатывать нагрузку.

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

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    include fastcgi_params;
    fastcgi_keep_conn on;
}

Описание

Директива `flv` используется в конфигурации NGINX в контексте location block для указания того, следует ли обрабатывать файлы FLV (Flash Video) при отдаче контента. Когда она включена, NGINX настраивается для корректной обработки запросов к файлам FLV, обеспечивая потоковую передачу видео с правильными заголовками и поведением, ожидаемым FLV-плеерами. Эта директива не принимает аргументов; достаточно просто включить её, чтобы активировать функцию обработки FLV в данном контексте. Реализация в исходном коде NGINX обеспечивает применение специфических заголовков ответа и правил буферизации к файлам FLV для обеспечения плавного воспроизведения. Директива может быть помещена в location block, где вы хотите отдавать контент FLV. Если она используется в server block без конкретного location, директива будет проигнорирована, если явно не заданы местоположения для файлов FLV. При отдаче файлов с правильным MIME type использование директивы `flv` гарантирует, что NGINX корректно обработает запросы и сможет оптимизировать работу для улучшения потоковой передачи. Важно отметить, что эта директива в значительной степени устарела, поскольку использование Flash заметно сократилось, и для потокового видео предпочитаются современные альтернативы.

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

location /videos {
    flv;
    root /var/www/videos;
}

Описание

Директива `geo` используется для создания сопоставления IP-адресов клиентов с переменными, которые могут применяться в различных конфигурациях NGINX. Она особенно полезна при настройке контроля доступа и управлении маршрутизацией запросов на основе географического положения. Эта директива может задавать как IPv4, так и IPv6 адреса и может располагаться внутри контекста `http`. Каждое правило сопоставления состоит из адреса (или диапазона) и необязательной переменной, которая либо содержит значение (например, '1' или '0' для разрешения или запрета доступа), либо устанавливается в 'default' для не совпадающих адресов. Внутри блока `geo` можно указывать отдельные IP-адреса, записи в нотации CIDR или географические диапазоны. NGINX будет проверять IP-адрес клиента по этим правилам в том порядке, в котором они определены. Если найдено соответствие, NGINX установит указанную переменную соответственно. Если адрес не совпал ни с одним правилом, будет применено значение, заданное директивой `default`. Это делает `geo` мощным инструментом для создания динамических конфигураций, реагирующих на разные IP-адреса клиентов, будь то для распределения нагрузки, контроля доступа или настройки приложений. Важно понимать, что директива `geo` должна быть определена в блоке `http`, и она не принимает другие связанные директивы непосредственно внутри себя, что может вызывать путаницу в сложных конфигурациях NGINX. Кроме того, эта директива работает на уровне HTTP и в основном зависит от сетевых деталей входящих запросов, поэтому её следует правильно использовать, исходя из ожидаемых характеристик клиентских запросов.

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

geo $remote_addr {
    default 0;
    192.168.1.0/24 1;
    10.0.0.0/8 2;
}

Описание

Директива `geoip_country` позволяет указать NGINX путь к базе данных GeoIP, необходимой для выполнения геолокации на основе IP-адресов клиентов. При настройке NGINX может присваивать запросам географическую информацию, такую как страна происхождения. Эта информация может впоследствии использоваться для контроля доступа или персонализации содержимого, обеспечивая адаптацию ответов сервера в зависимости от местоположения пользователей. Директива принимает один или два аргумента: путь к файлу базы данных GeoIP и необязательную опцию 'country'. Если она указана, это включает или отключает определённые функции поиска по странам или изменяет поведение при использовании базы данных. Эта функциональность важна, когда организациям необходимо применять политики по регионам, таргетировать рекламу или отдавать локализованный контент, поскольку она помогает точно определять источник входящих запросов. Интеграция с модулем GeoIP позволяет серверу динамически определять страну пользователя, что даёт возможность привязывать правила к конкретным географическим регионам. Учтите, что это требует внешней базы данных, которую необходимо регулярно обновлять для поддержания точности соответствий геолокации.

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

geoip_country /path/to/geoip.dat;

Описание

Директива `geoip_org` является частью модуля NGINX HTTP Core и облегчает управление доступом за счёт использования данных GeoIP для определения организации, связанной с конкретным IP-адресом. Используя базу данных GeoIP, NGINX может динамически предоставлять или ограничивать доступ на основании организационной принадлежности клиента, запрашивающего ресурсы. Эта директива позволяет серверу принимать меры в зависимости от информации об организации, полученной из GeoIP, что даёт администраторам возможность реализовывать пользовательскую маршрутизацию, логирование или политики доступа, основанные на субъекте, выполняющем запрос. Директива может принимать от одного до двух аргументов: либо одну строку, представляющую имя базы данных GeoIP, либо конкретное имя организации для сопоставления с входящими запросами. Наличие этих параметров обеспечивает гибкую настройку, позволяя администраторам адаптировать обработку трафика в соответствии с организационными критериями, подразумеваемыми IP-адресами. Если указан только имя организации, NGINX будет использовать его во внутреннем поиске для идентификации соединений, тогда как необязательный аргумент пути к DB облегчает привязку к пользовательским или сторонним базам данных GeoIP. В целом, `geoip_org` играет ключевую роль в расширении возможностей контроля доступа NGINX, используя технологию GeoIP для связывания запросов с организационными данными и позволяя принимать более взвешенные решения при управлении трафиком.

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

geoip_org /path/to/geoip/db GeoIP Org Name;

Описание

Директива `geoip_city` разработана для расширения возможностей HTTP-сервера NGINX по принятию географических решений на основе IP-адреса клиента путём обращения к базе данных GeoIP. Указывая путь к базе данных GeoIP city, эта директива позволяет NGINX определять и задавать переменные на основе географического положения входящих запросов. Когда директива `geoip_city` используется в контексте `http`, она принимает один или два аргумента: путь к файлу базы данных GeoIP city и, опционально, дополнительный аргумент для указания флага обработки некорректных IP-адресов. Директива обрабатывает входящие запросы, сопоставляет IP клиента с записями в указанной базе данных GeoIP и делает доступными данные геолокации на уровне города (например, название города, регион и страна) для использования в конфигурации. Эта геоинформация затем может использоваться в правилах доступа, форматировании файлов журналов и даже для персонализации содержимого. Директива обычно полезна для приложений, которым требуется целевая доставка контента в зависимости от географического положения пользователя, таких как локализованная реклама или соблюдение местных регуляций. Важно поддерживать файл базы данных GeoIP в актуальном состоянии, так как соответствия IP→местоположение могут часто меняться. Некорректные или устаревшие данные могут привести к плохому пользовательскому опыту из-за неточностей в детализации геолокации.

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

http {
    geoip_city /usr/share/GeoIP/GeoIPCity.dat;
    server {
        location / {
            if ($geoip_city) {
                add_header X-City $geoip_city;
            }
        }
    }
}

Описание

Директива `geoip_proxy` задаёт способ для NGINX использовать proxy protocol, чтобы получить исходный IP-адрес клиента, что позволяет повысить точность определения географического положения с помощью баз GeoIP. Это особенно полезно в средах, где запросы пересылаются от одного прокси-сервера к другому, поскольку адресация в запросе может не отражать реальное географическое местоположение клиента. При настройке NGINX будет читать исходный IP-адрес клиента из указанного заголовка, а не напрямую из клиентского соединения. Директива принимает один аргумент — имя заголовка, который следует проверять; обычно он содержит исходный адрес клиента (например, `X-Real-IP`). При использовании этой директивы крайне важно убедиться, что вышестоящие прокси корректно заполняют указанный заголовок допустимыми IP-адресами для точных запросов к базам GeoIP. Некорректная настройка может привести к записи неправильных географических данных в логах или к ошибкам при управлении доступом. Выполнение директивы происходит в контексте HTTP, что позволяет применять её глобально в server-блоках или в отдельных location-блоках. Заголовки корректно обрабатываются при входящих запросах, поэтому важно поддерживать единообразную конфигурацию на всех промежуточных прокси в развертывании.

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

http {
    geoip_proxy X-Forwarded-For;
}

Описание

`geoip_proxy_recursive` директива используется в контексте `http` NGINX для управления поведением прокси-запросов с поддержкой GeoIP. Когда установлено в 'on', эта директива позволяет модулю выполнять рекурсивные запросы для получения географической информации клиента. Это особенно полезно в сценариях, когда клиент подключается через несколько прокси, поскольку при определении географического местоположения сохраняется исходный IP-адрес клиента. Директива гарантирует, что модуль GeoIP получает данные из реального IP клиента, а не из IP последнего прокси. Когда директива включена, NGINX будет проверять заголовки, такие как `X-Forwarded-For` или `X-Real-IP`, чтобы получить реальный IP-адрес клиента. Если эти заголовки содержат несколько адресов, NGINX пройдет по ним, чтобы найти исходный IP-адрес, обеспечивая точные данные о местоположении для GeoIP-запросов. Эта функциональность важна для приложений, которым требуется контент, ориентированный по геолокации, или меры безопасности, основанные на географическом положении. Директива интерпретируется как флаг, то есть имеет бинарное состояние. Либо она активирована (установлена в 'on'), либо нет (установлена в 'off'). Поведение соответствует общей модели NGINX по переключению директив между включённым и выключенным состояниями, обеспечивая гибкость в зависимости от конкретных требований конфигурации окружения.

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

http {
    geoip_proxy_recursive on;
    geoip_country /path/to/GeoIP.dat;
}

Описание

Директива `grpc_pass` специально предназначена для маршрутизации gRPC-запросов внутри NGINX. Она определяет бэкенд-сервер, на который пересылаются gRPC-запросы. Директива принимает в качестве аргумента URL, который может указывать либо на группу upstream-серверов, определённую директивой `upstream`, либо на прямой адрес сервера. Когда NGINX получает gRPC-запрос, он преобразует этот запрос в необходимый формат и пересылает его указанному бэкенду, обрабатывая бинарный протокол, необходимый для gRPC-взаимодействия. В контексте конфигурации NGINX директива `grpc_pass` используется внутри блока `location`, что делает её необходимой для определения части URI, которая должна быть сопоставлена с конкретным бэкенд-сервисом. Корректная обработка заголовков ответа, управление соединениями и механизмы бинарного кодирования/декодирования автоматически выполняются NGINX, что позволяет разработчикам сосредоточиться на логике приложения, а не на тонкостях gRPC-взаимодействия. Важно убедиться, что upstream-сервер поддерживает gRPC и должным образом настроен для обработки запросов, пересылаемых из NGINX. Поскольку gRPC использует HTTP/2, директива `grpc_pass` по сути требует сборки NGINX с поддержкой HTTP/2. Это означает, что сервер должен быть правильно настроен на приём HTTP/2-соединений, что в сочетании с `grpc_pass` обеспечит полноценную поддержку gRPC-трафика.

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

location /gRPC {
    grpc_pass grpc://localhost:50051;
}

Описание

Директива `grpc_bind` используется в NGINX для определения локального адреса и порта, к которым сервер будет привязываться для обработки gRPC-запросов. Эта директива может быть установлена в контекстах `http`, `server` и `location`, что позволяет гибко настраивать конфигурацию в зависимости от потребностей маршрутизации трафика. Она принимает один или два аргумента; первый аргумент — адрес (IPv4 или IPv6), а второй аргумент — необязательный номер порта. Использование директивы без указания порта по умолчанию приводит к использованию стандартного порта для gRPC (как правило, 50051). После того как директива `grpc_bind` настроена, NGINX слушает входящие gRPC-запросы на указанном адресе и порту и пересылает их на определённый в конфигурации upstream gRPC-сервер. Это позволяет приложениям эффективно обрабатывать gRPC-трафик, используя NGINX в качестве обратного прокси для управления подключениями, балансировки нагрузки и других функций, таких как ограничение скорости или аутентификация. Следует позаботиться о том, чтобы указанный адрес и порт не были уже заняты, чтобы избежать конфликтов привязки, которые могут привести к прерыванию сервиса.

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

grpc_bind 0.0.0.0 50051;

Описание

Директива `grpc_socket_keepalive` используется для включения или отключения функции TCP keepalive для gRPC-соединений, обрабатываемых NGINX. Когда она включена, эта директива обеспечивает сохранение неактивных TCP-соединений в рабочем состоянии путем отправки периодических keepalive-зондов. Это важно для поддержания долгоживущих соединений, которые часто используются в gRPC для взаимодействия сервисов. По умолчанию во многих операционных системах TCP keepalive может быть отключён, что может привести к закрытию соединений и прерыванию связи после периода простоя. Директива принимает значение-флаг, то есть может быть установлена в 'on' (включено) или 'off' (отключено). При установке в 'on' NGINX настроит параметры сокета для keepalive, что позволит отправлять keepalive-пакеты в соответствии с настройками системы (такими как `tcp_keepalive_time`, `tcp_keepalive_intvl` и `tcp_keepalive_probes`). Поэтому для корректной работы keepalive также необходимо отрегулировать эти параметры на уровне системы. Обратите внимание, что включение этой функции без надлежащих настроек сервера может привести к проблемам с производительностью или избыточному сетевому трафику, особенно в средах с высокой нагрузкой.

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

server {
    listen 80;
    grpc_socket_keepalive on;
    location /myservice {
        grpc_pass grpc://backend;
    }
}

Описание

Директива `grpc_connect_timeout` задаёт максимальное время, отведённое на установление соединения с бэкенд-сервером gRPC, в миллисекундах. Этот тайм-аут важен для того, чтобы длительные или неотзывчивые соединения не задерживали обработку клиентских запросов на продолжительное время. Если тайм-аут истёк до успешного установления соединения, NGINX прервет попытку соединения и вернёт клиенту ошибку, что позволит вашему приложению корректно обработать сбои соединения. Директива может размещаться в контекстах `http`, `server` или `location`, что позволяет администраторам задавать тайм-ауты соединения, соответствующие конкретным требованиям архитектуры приложения. Период тайм-аута можно задать любым положительным целым значением; если установить 0, тайм-аут будет отключён полностью, что обычно не рекомендуется в рабочей среде, где критична отзывчивость клиентов. Наиболее эффективно `grpc_connect_timeout` используется для балансировки между задержкой установления соединения и производительностью приложения, позволяя быстро выполнять повторные попытки или переключаться на альтернативные механизмы отказоустойчивости, если бэкенд-сервис не отвечает.

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

http {
    server {
        location / {
            grpc_pass grpc://backend;
            grpc_connect_timeout 500ms;
        }
    }
}

Описание

Директива `grpc_send_timeout` в NGINX задаёт максимальный период времени, в течение которого сервер должен отправить gRPC-ответ клиенту после обработки запроса. Эта директива важна для того, чтобы клиентские приложения не ждали ответа бесконечно, что помогает управлять ресурсами и поддерживать производительность приложения. Директива действует в различных контекстах, таких как `http`, `server` и `location`, позволяя устанавливать разные значения таймаута в зависимости от конкретных потребностей ваших приложений. По истечении заданного периода таймаута NGINX разорвет соединение и сгенерирует код состояния gRPC, обозначающий ошибку таймаута. Это особенно полезно в средах с большим количеством микросервисов, где быстрые ответы об ошибке предпочтительнее потенциально бесконечного ожидания сильно задерживающих сервисов. Указанный таймаут применяется только для отправки ответов после того, как сервер начал их отправлять клиенту, то есть он не влияет на время обработки самого запроса, а лишь на интервал отправки финальных пакетов ответа. Синтаксис этой директивы: `grpc_send_timeout time;`, где `time` может быть задан в разных форматах, например `30s` для тридцати секунд или `1m` для одной минуты и т.д. Важно выбрать значение таймаута, которое уравновешивает предоставление достаточного времени для получения ответа и предотвращает блокировку общей работоспособности приложения из-за неотзывчивых сервисов.

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

location /api {
    grpc_pass grpc://backend_service;
    grpc_send_timeout 30s;
}

Описание

Директива `grpc_intercept_errors` в NGINX позволяет управлять тем, как gRPC‑сервисы обрабатывают ошибки. При включении NGINX перехватывает ответы об ошибках gRPC и заменяет их на пользовательские ответы в соответствии с поведением, заданным в конфигурации. Это особенно полезно для предоставления более удобочитаемых сообщений об ошибках или для стандартизации ответов об ошибках, отправляемых клиентам. Эта директива принимает булев аргумент — 'on' или 'off'. При установке в 'on' NGINX будет перехватывать ошибки от upstream gRPC‑сервиса и позволит дополнительно настроить обработку или трансформацию этих ошибок прежде чем вернуть их клиенту. Например, вы можете записать ошибку в лог или сопоставить определённые коды ошибок с более подробными сообщениями. При установке в 'off' NGINX просто пропустит код и сообщение об ошибке от backend gRPC‑сервиса без перехвата или изменений.

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

http {
    server {
        location /some-grpc-service {
            grpc_pass grpc://backend_service;
            grpc_intercept_errors on;
        }
    }
}

Описание

Директива grpc_buffer_size необходима для оптимизации производительности gRPC-приложений, обслуживаемых через NGINX. Когда NGINX выступает в роли обратного прокси для gRPC, ему нужно эффективно читать ответы от upstream servers. Эта директива определяет размер буфера, выделяемого для чтения этих ответов, что позволяет контролировать использование памяти и пропускную способность. Больший буфер может вместить более крупные ответы, но может потреблять больше памяти, тогда как меньший буфер может приводить к более быстрому выделению памяти, но при превышении размера буфера приводить к дополнительным операциям чтения. Эту директиву можно настроить в контекстах http, server или location, что обеспечивает гибкость её применения. Администраторы могут подбирать размер буфера в соответствии с конкретными потребностями своих gRPC-сервисов. Например, если ответы вашего gRPC обычно большие, увеличение размера буфера может снизить количество обращений NGINX к upstream servers за данными и, таким образом, улучшить общую задержку и производительность gRPC-сервиса. Параметры этой директивы включают одно значение, обозначающее размер буфера в байтах, либо можно использовать суффиксы размеров, такие как `k`, `m`, для указания килобайт или мегабайт. Рекомендуется тщательно настраивать этот параметр исходя из ожидаемых размеров ответов upstream gRPC services.

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

http {
    grpc_buffer_size 64k;
    server {
        location /grpc {
            grpc_pass backend;
        }
    }
}

Описание

Директива `grpc_read_timeout` определяет максимальный интервал времени, в течение которого NGINX будет ждать ответа от gRPC backend server после установления соединения. Этот таймаут критически важен для регулирования того, как долго сервер должен продолжать ожидать ответа, прежде чем отказаться и закрыть соединение. Он позволяет администраторам тонко настраивать отзывчивость сервера и управление ресурсами, избегая длительных зависаний, когда запросы висят бесконечно. Эта директива может быть указана в трёх контекстах: `http`, `server` и `location`. Её значение задаётся в формате времени (например, '30s' для 30 секунд). Значение директивы должно быть допустимым интервалом времени, который можно указать в секундах, минутах или часах. Если ответ не получен в течение указанного периода таймаута, NGINX вернёт ошибку клиенту, что обеспечивает лучшую отказоустойчивость сервисов, которые могут испытывать задержки. Установка подходящего значения `grpc_read_timeout` имеет решающее значение, особенно в производственной среде, где gRPC-сервисы могут демонстрировать различное время отклика в зависимости от нагрузки. Слишком короткий таймаут может привести к ненужным повторным попыткам или ошибкам, тогда как слишком длинный может ухудшить отзывчивость приложения, поскольку запросы могут без необходимости длительно висеть.

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

location /example {
    grpc_pass grpc://backend;
    grpc_read_timeout 30s;
}

Описание

Директива `grpc_next_upstream` используется в контексте HTTP, server или location blocks для определения условий, при которых NGINX будет пытаться отправить запрос на next upstream server, настроенный для обработки протокола gRPC. Директива принимает один или несколько аргументов, которые задают различные условия отказа, такие как истечение таймаута, сбои соединения или другие ошибки. При возникновении указанного отказа NGINX автоматически повторит запрос с использованием следующего сервера в upstream block, повышая надёжность и доступность gRPC-сервисов за счёт автоматического восстановления от временных проблем. Поведение директивы `grpc_next_upstream` обеспечивает как детализированный контроль, так и гибкость. Например, если запрос истекает по таймауту или backend server недоступен, директива позволяет NGINX бесшовно попробовать другой сервер. Параметры этой директивы могут быть заданы в соответствии с требованиями приложения, что позволяет администратору сервера тонко настроить стратегию обработки отказов. Это особенно полезно в распределённых системах, где каждый компонент сервиса может иметь разные характеристики доступности. Эта директива тесно связана с общей стратегией балансировки нагрузки NGINX, позволяя реализовывать сложные схемы, такие как активные проверки состояния и обработка недоступности сервисов. Важно настраивать эту директиву вместе с настройками upstream block, чтобы обеспечить согласованную реакцию как на стороне клиента, так и на стороне backend server, что в конечном итоге улучшает пользовательский опыт в приложениях, использующих gRPC для коммуникаций в режиме реального времени.

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

upstream grpc_backend {
    server backend1.example.com:50051;
    server backend2.example.com:50051;
}

location / {
    grpc_pass grpc://grpc_backend;
    grpc_next_upstream error timeout;  # Retry on error or timeout
}

Описание

Директива `grpc_next_upstream_tries` задаёт, сколько upstream-серверов NGINX должен попытаться опросить в случае, если предыдущий сервер не отвечает. При обработке gRPC-запроса, если первый upstream-сервер возвращает ошибку, NGINX может повторно отправить запрос на последующие серверы в соответствии со значением этой директивы. Директива полезна в балансируемых по нагрузке окружениях для обеспечения надёжности связи клиент — сервер за счёт возможности переключения на запасные серверы при возникновении проблем. Механизм повторных попыток полезен при транзиентных сбоях, но его применение следует соотносить с возможным увеличением задержки ответа клиенту. Эта директива действует в контекстах `http`, `server` и `location`. Значение, заданное для `grpc_next_upstream_tries`, должно быть положительным целым числом, обозначающим количество допустимых повторных попыток при сбое запроса к upstream. Если директива установлена в 0, повторные попытки полностью отключаются, что приводит к немедленному провалу после первого обращения к upstream-серверу. Поведение по умолчанию определяется конфигурацией администратора сервера и может быть скорректировано для балансировки производительности и надёжности в зависимости от потребностей приложения.

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

grpc_next_upstream_tries 3;

Описание

Директива `grpc_next_upstream_timeout` задаёт максимальное время ожидания подключения к следующему upstream server, когда предыдущий upstream server даёт сбой во время gRPC-запроса. Этот таймаут важен в сценариях, где несколько upstream server могут участвовать в обработке клиентского запроса. Если первоначальный upstream server сталкивается с ошибкой, сконфигурированный таймаут определяет, как долго NGINX будет пытаться подключиться к следующему доступному upstream server в стеке, прежде чем операция завершится по таймауту. Параметр для `grpc_next_upstream_timeout` задаётся в миллисекундах, что позволяет тонко контролировать скорость формирования ответа даже в неблагоприятных условиях, когда основной сервер не отвечает или работает медленно. Это напрямую влияет на эффективность и отзывчивость сервиса, особенно в случаях высокой частоты ошибок или задержек среди upstream server. Настраивая эту директиву, администраторы могут оптимизировать пользовательский опыт и использование ресурсов, балансируя между ожиданием ответа сервера и переключением на альтернативные серверы. Эту директиву можно установить в разных контекстах, таких как `http`, `server` и `location`, что делает её универсальной на разных уровнях конфигурации. Использование её в сочетании с родственными директивами, такими как `grpc_pass` или `proxy_next_upstream`, может дополнительно повысить общую функциональность и надёжность сервера.

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

location /api {
    grpc_pass grpc://my_upstream;
    grpc_next_upstream_timeout 500ms;
}

Описание

The `grpc_set_header` directive allows you to add or modify HTTP/2 headers for gRPC requests passed to a backend server. This is particularly useful in a microservices architecture where specific metadata may need to be sent along with the request. The directive takes two parameters: the first is the name of the header to be set, and the second is the value to assign to that header. This allows for dynamic generation of header values based on the context of the request or predefined variables. When the `grpc_set_header` directive is used in a particular context (http, server, or location), it will apply headers at that level of configuration. For instance, if declared in a server block, all gRPC requests handled by that server will carry the specified headers. If declared inside a location block, only those requests matching that location will have the headers set. It’s also possible to use variables within the directive to set header values dynamically, increasing flexibility in how metadata is passed to the backend services.

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

location /rpc {
    grpc_pass grpc://backend;
    grpc_set_header api-key $api_key;
    grpc_set_header user-id $http_user_id;
}

Описание

Директива `grpc_pass_header` используется для указания, какие заголовки из входящего запроса должны быть переданы на upstream gRPC server. Эта директива играет ключевую роль при проксировании gRPC, особенно когда определённые заголовки требуются gRPC-службой во время её работы. Когда она устанавливается в соответствующих контекстах (http, server, location), она позволяет тонко управлять пересылкой заголовков, давая возможность сервисам получать необходимые метаданные от клиентов. Одна из ключевых особенностей директивы `grpc_pass_header` — её способность принимать один аргумент, который задаёт имя HTTP-заголовка для пересылки. Этот аргумент нечувствителен к регистру, то есть указание `example-header` или `Example-Header` даст одинаковый результат. Директива может повторяться для пересылки нескольких заголовков при необходимости, что помогает сохранять важную метаинформацию при взаимодействии между сервисами. Использование этой директивы особенно полезно в сценариях, где требуется сохранять и передавать вместе с вызовами gRPC токены аутентификации, идентификаторы отслеживания или другие формы метаданных. Это улучшает совместимость между сервисами, которые зависят от детальной информации в заголовках для своей работы, и, следовательно, повышает общую функциональность API.

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

location /api {
    grpc_pass backend;
    grpc_pass_header Custom-Header;
}

Описание

Директива grpc_hide_header используется для управления тем, какие заголовки исключаются из ответов gRPC, обслуживаемых NGINX. Эта директива помогает управлять конфиденциальной информацией или контролировать взаимодействие с клиентом, скрывая заголовки, которые в противном случае могли бы быть раскрыты. Она принимает один аргумент, который задаёт имя заголовка, подлежащего сокрытию. Когда эта директива установлена, любой ответ от gRPC-сервера, содержащий указанный заголовок, будет отфильтрован NGINX до достижения клиента.

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

location /grpc {
    grpc_pass grpc://backend;
    grpc_hide_header X-My-Header;
}

Описание

Директива grpc_ignore_headers позволяет указать список заголовков gRPC, которые следует игнорировать при обработке запросов. Эта директива принимает в качестве аргументов одно или несколько имён заголовков, и заголовки, совпадающие с любым из указанных имён, будут исключены из обработки сервером NGINX. Это может быть полезно в ситуациях, когда определённые заголовки мешают логике приложения или когда политики безопасности требуют исключения конкретных заголовков из клиентских запросов. Директива может использоваться в http, server, or location contexts, что означает, что её действие может распространяться на весь сервер, на конкретный виртуальный хост или даже на определённый location block. Гибкость использования этой директивы позволяет тонко управлять трафиком gRPC. Если заголовки не указаны, по умолчанию игнорироваться не будут никакие заголовки, то есть все заголовки будут обрабатываться. При использовании этой директивы важно убедиться, что заголовки, которые вы решите игнорировать, не нарушат ожидаемую работу ваших приложений gRPC. Игнорирование критических заголовков может привести к непредвиденному поведению приложения, поскольку сервер может не получить необходимые данные для корректной обработки запросов.

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

location /grpc {
    grpc_pass grpc://backend;
    grpc_ignore_headers 
        x-grpc-status
        x-user-header;
}

Описание

Директива `grpc_ssl_session_reuse` настраивает повторное использование SSL-сессий для gRPC-соединений, устанавливаемых через сервер NGINX. Она принимает логическое значение; при включении gRPC-клиенты могут повторно использовать существующие SSL-сессии для установления новых соединений, что оптимизирует использование ресурсов и повышает производительность. Когда эта директива установлена в 'on', NGINX потенциально сокращает время, необходимое для SSL-рукопожатия при последующих соединениях, поскольку рукопожатие можно пропустить при повторном использовании существующей сессии. И наоборот, установка в 'off' отключает эту функциональность, что может привести к увеличению задержки при повторных соединениях из-за необходимости полного SSL-рукопожатия каждый раз. Директива применима в различных контекстах, включая `http`, `server` и `location`, что обеспечивает гибкость в зависимости от области действия gRPC-сервисов, которым требуется повторное использование сессий. Обратите внимание, что хотя повторное использование сессий может значительно улучшить производительность, оно требует соответствующей настройки и совместимости между сервером и клиентами для корректной работы. SSL session IDs должны быть общими между сервером и клиентами для успешного повторного использования, что иногда требует дополнительных мер по кэшированию сессий между несколькими экземплярами сервера, если это необходимо.

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

server {
    listen 443 ssl;
    grpc_ssl_session_reuse on;
    ssl_certificate /path/to/cert;
    ssl_certificate_key /path/to/key;
    # other configurations...
}

Описание

Директива `grpc_ssl_protocols` позволяет настроить, какие протоколы SSL и TLS доступны для gRPC-подключений, обрабатываемых NGINX. Пользователи могут указать список протоколов, которые сервер будет принимать для защищённого взаимодействия, что помогает повысить безопасность за счёт исключения устаревших и уязвимых версий протоколов. Эта директива может быть определена в разных контекстах, таких как `http`, `server` или `location`, что даёт гибкость конфигурации в зависимости от потребностей приложения. Типичными допустимыми параметрами для этой директивы обычно являются распространённые версии SSL/TLS, такие как `TLSv1`, `TLSv1.1`, `TLSv1.2` и `TLSv1.3`, что позволяет администраторам тщательно контролировать стандарты безопасности, используемые их приложениями. Кроме того, определение этой директивы в контексте `http` применит настройки ко всему серверу, тогда как определение в контекстах `server` или `location` позволит добиться более тонкого контроля, возможно включая разные настройки протоколов для разных gRPC‑сервисов. Важно располагать указанные протоколы таким образом, чтобы они соответствовали как требованиям безопасности, так и требованиям совместимости клиентских приложений.

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

server {
    listen 443 ssl;
    grpc_ssl_protocols  TLSv1.2 TLSv1.3;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
}

Описание

Директива `grpc_ssl_ciphers` в NGINX настраивает наборы шифров, которые могут использоваться для защищённых соединений в gRPC‑приложениях. Когда gRPC‑служба настроена на использование SSL/TLS, требуется защищённый канал связи между клиентом и сервером. Директива `grpc_ssl_ciphers` позволяет явно указать, какие шифры сервер должен принимать при согласовании SSL/TLS‑соединений, обеспечивая совместимость и безопасность в зависимости от потребностей вашего приложения. Директива применима в контекстах `http`, `server` и `location`, что даёт гибкость при определении наборов шифров для глобальных или конкретных случаев. Директива принимает один аргумент — двоеточием разделённый список шифров. Каждый шифр в списке должен быть допустимым согласно библиотеке SSL/TLS, используемой NGINX, обычно OpenSSL. Если указано несколько шифров, при установлении защищённого соединения они будут оцениваться в указанном порядке, что позволяет приоритизировать выбор шифров. При настройке наборов шифров важно учитывать безопасность приложения, поскольку использование слабых или устаревших шифров может подвергнуть систему уязвимостям. Кроме того, эта директива взаимодействует с другими, связанными с SSL, директивами для создания защищённой среды для gRPC‑коммуникаций.

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

server {
    listen 443 ssl;
    grpc_ssl_ciphers 'ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-SHA256';
}

Описание

Директива grpc_ssl_name используется в конфигурации NGINX для задания имени хоста, которое будет отправлено в расширении Server Name Indication (SNI) во время SSL-рукопожатия для gRPC‑соединений. Это особенно важно, когда NGINX действует как обратный прокси для нескольких gRPC‑сервисов, размещённых на одном IP‑адресе, но требующих различных SSL‑сертификатов в зависимости от имени хоста, запрашиваемого клиентом. Когда эта директива задана, NGINX будет заменять имя хоста в SSL‑контексте на указанное значение при обработке gRPC‑запросов. Это повышает безопасность и надёжность SSL‑соединений, гарантируя, что для каждого конкретного запроса к gRPC‑сервису будет представлен корректный сертификат. Директива применяется в контекстах http, server и location, что позволяет гибко настраивать конфигурацию в зависимости от структуры ваших сервисов. Аргументом этой директивы должна быть одна строка, задающая SSL‑имя хоста. Если директива опущена, NGINX по умолчанию использует исходный хост, запрошенный клиентом. Правильная настройка grpc_ssl_name необходима для конфигураций с виртуальным хостингом или при работе с несколькими gRPC‑бэкендами.

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

server {
    listen 443 ssl;
    server_name grpc.example.com;

    grpc_ssl_name backend.grpc.example.com;

    location / {
        grpc_pass grpc://backend;
    }
}

Описание

Директива `grpc_ssl_server_name` используется в конфигурациях NGINX, чтобы включить добавление имени сервера в SSL‑рукопожатие для gRPC‑соединений. Это позволяет NGINX удовлетворить требование клиента Server Name Indication (SNI), что помогает правильно направлять соединение к соответствующему бэкенд‑серверу на основе указанного имени хоста. Когда эта директива включена, сервер может обслуживать несколько SSL‑сайтов на одном и том же IP‑адресе, различая их по доменным именам. Директива может быть указана в различных контекстах, включая `http`, `server` и `location`, что обеспечивает гибкость её применения в файле конфигурации. При установке этой директивы в 'on' сервер NGINX будет использовать имя сервера, включённое в gRPC‑запрос, для своей SSL‑конфигурации, что позволит ему корректно выбирать соответствующий набор SSL‑сертификатов, совпадающих с доменным именем. Это особенно полезно в средах, где на одном сервере размещается несколько gRPC‑сервисов. Важно отметить, что включение `grpc_ssl_server_name` может потребовать тщательного управления вашими SSL‑сертификатами, чтобы обеспечить их правильную настройку для работы с SNI. Если используется несколько доменов, убедитесь, что они надёжно защищены действительными SSL‑сертификатами для обеспечения надёжной связи. Эта функция подчёркивает интероперабельность с gRPC‑клиентами, которые ожидают поддержку SNI для корректной работы.

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

server {
    listen 443 ssl;
    grpc_ssl_server_name on;
    ssl_certificate /path/to/certificate.pem;
    ssl_certificate_key /path/to/key.pem;
}

Описание

Директива `grpc_ssl_verify` используется в конфигурации сервера NGINX для управления процессом проверки SSL-сертификатов для бэкенд-серверов gRPC. Эта директива принимает флаговый аргумент, который указывает, должна ли выполняться проверка SSL-сертификата при выполнении gRPC-запросов. При установке в 'on' NGINX будет проверять SSL-сертификат, представленный upstream gRPC server, относительно сертификатов CA, настроенных в системе, что обеспечивает безопасное соединение и подтверждает подлинность сервера. Директива может располагаться в контекстах `http`, `server` или `location`, что позволяет гибко настраивать поведение в зависимости от иерархии запросов. Если проверка включена и сертификат сервера недействителен или не может быть подтвержден, NGINX откажется устанавливать соединение. Наоборот, установка директивы в 'off' отключает процесс проверки, что может быть полезно для тестирования, но представляет риск для безопасности в продуктивных средах, где возможны man-in-the-middle attacks. Учтите, что при включенном `grpc_ssl_verify` он опирается на сертификаты CA, доступные в сборке NGINX, которые можно настроить, указав директиву `ssl_trusted_certificate`. Поэтому правильная конфигурация доверенных сертификатов необходима для корректной работы этой директивы и обеспечения безопасной связи с gRPC-сервисами.

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

location /api {
    grpc_pass grpc://backend-grpc;
    grpc_ssl_verify on;
}

Описание

Директива `grpc_ssl_verify_depth` используется в конфигурации NGINX для указания максимального числа промежуточных сертификатов, которые могут присутствовать в цепочке проверки SSL при обработке gRPC-запросов. Эта директива особенно актуальна при использовании gRPC поверх SSL, так как она помогает контролировать процесс проверки сертификатов и предотвращать возможные зацикливания или чрезмерную глубину проверки. Задавая эту директиву, администраторы могут удостовериться, что клиенты подключаются к предусмотренным серверам, одновременно поддерживая баланс между безопасностью и производительностью. Директива принимает целое числовое значение, определяющее максимально допустимую глубину проверки SSL-сертификатов. Например, если установить значение '3', цепочка сертификатов может содержать до трёх промежуточных сертификатов до достижения корневого доверенного сертификата. Это полезно в конфигурациях, где выданы несколько сертификатов, и нужно управлять глубиной цепочки, чтобы не выходить за рамки установленных требований. Кроме того, если глубина проверки превысит этот предел, NGINX прервет соединение, тем самым усиливая применение политики безопасности без излишней нагрузки на процесс проверки. Эту директиву можно указывать в различных контекстах, включая `http`, `server` и `location`, что позволяет обеспечить тонкую настройку в зависимости от области действия конфигурации. Важно подбирать это значение с учётом известной структуры сертификатов, используемой на стороне сервера и клиента.

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

http {
    server {
        location / {
            grpc_pass grpc://backend;
            grpc_ssl_verify on;
            grpc_ssl_verify_depth 3;
        }
    }
}

Описание

Директива grpc_ssl_trusted_certificate используется в NGINX для указания файла, содержащего доверенный корневой сертификат, применяемый при установлении защищённых gRPC‑соединений. Это особенно важно, когда gRPC‑сервисы работают поверх TLS, поскольку директива позволяет клиенту проверять подлинность SSL‑сертификата сервера. Указанный файл сертификата обычно содержит публичные сертификаты Certificate Authorities (CAs), которым доверяют при подписывании сертификатов сервера, что даёт NGINX возможность проверять цепочку доверия при установлении защищённого соединения. При настройке этой директивы нужно указать путь к файлу сертификата в качестве аргумента. Файл должен быть в формате PEM и содержать полную цепочку сертификатов, необходимую для верификации. Также важно убедиться, что права доступа к этому файлу позволяют NGINX читать его. Если директивы заданы в контекстах server или location, они будут применяться ко всем gRPC‑соединениям, обрабатываемым этими блоками, обеспечивая единообразную проверку SSL/TLS для всего проходящего через них трафика gRPC.

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

server {
    listen 443 ssl;
    grpc_ssl_trusted_certificate /etc/nginx/certs/ca.crt;
    # Additional configuration...
}

Описание

Директива `grpc_ssl_crl` используется в конфигурациях NGINX для указания файла списка отозванных сертификатов (CRL), который сервер использует для проверки действительности клиентских SSL-сертификатов при gRPC-соединениях. Это особенно важно для обеспечения защищённого канала связи, так как позволяет серверу отклонять сертификаты, отозванные до истечения срока их действия. Директива применима в контекстах `http`, `server` и `location`, что даёт гибкость в области применения настроек для разных частей конфигурации. Когда клиент пытается подключиться к серверу, NGINX обращается к указанному файлу CRL для проверки сертификатов, предъявляемых клиентом. Если сертификат клиента найден в CRL, NGINX отклонит подключение, повышая безопасность и не позволяя использовать отозванные сертификаты для установления доверия. Крайне важно поддерживать файл CRL в актуальном состоянии, чтобы он отражал текущий статус сертификатов; обычно его получают от удостоверяющего центра (CA), который управляет подписями и отзывами. Эта директива принимает один аргумент — путь к файлу CRL — и должна использоваться совместно с другими SSL-директивами, такими как `ssl_certificate` и `ssl_certificate_key`, как часть полной gRPC SSL-конфигурации.

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

server {
    listen 443 ssl;
    ssl_certificate     /etc/ssl/certs/server.crt;
    ssl_certificate_key /etc/ssl/private/server.key;
    grpc_ssl_crl       /etc/ssl/crl/my_crl.pem;
}

Описание

Директива `grpc_ssl_certificate` в NGINX используется для указания пути к файлу SSL-сертификата, который будет применяться для шифрования gRPC-коммуникаций поверх HTTPS. Эта директива необходима для обеспечения безопасности данных, передаваемых по gRPC-соединениям, предоставляя шифрование для конфиденциальной информации, пересылаемой по сети. Когда эта директива задана, NGINX будет использовать указанный SSL-сертификат при обработке входящих gRPC-запросов. Эту директиву можно размещать в контекстах `http`, `server` или `location`, что обеспечивает гибкость настройки SSL на разных уровнях внутри архитектуры сервера. Конфигурация ожидает один аргумент, который должен быть корректным путем к файлу с сертификатом в PEM-формате. Если указанный файл не может быть прочитан или не является действительным сертификатом, NGINX не сможет запуститься, тем самым применяя строгие меры для обеспечения защищенной связи. Кроме того, использование директивы должно сопровождаться соответствующими настройками SSL, такими как `grpc_ssl_certificate_key`, чтобы корректно установить и защитить SSL-рукопожатие во время сеансов.

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

server {
    listen 443 ssl;
    grpc_ssl_certificate /etc/ssl/certs/my_cert.crt;
    grpc_ssl_certificate_key /etc/ssl/private/my_key.key;
    location /grpc {
        grpc_pass grpc://backend_service;
    }
}

Описание

Директива `grpc_ssl_certificate_key` используется для определения файла закрытого ключа, необходимого для установления защищённых gRPC-подключений. Эта директива особенно важна, когда сервер должен аутентифицировать себя перед клиентами с помощью SSL/TLS. В качестве параметра следует указать путь к файлу в кодировке PEM, который содержит закрытый ключ, связанный с SSL-сертификатом, определённым директивой `grpc_ssl_certificate`. Когда gRPC-клиент пытается подключиться, он будет использовать SSL-сертификат и закрытый ключ для установления защищённого соединения, обеспечивая шифрование и безопасность передаваемых данных. Директиву можно использовать на уровнях `http`, `server` или `location`. Такая гибкость позволяет точно настраивать SSL-конфигурации в зависимости от потребностей разных частей веб-сервера. Важно учитывать, что при отсутствии действительного сертификата и соответствующего закрытого ключа клиенты могут не суметь установить соединение, что приведёт к сбоям в коммуникации. Поэтому корректная настройка этой директивы необходима для gRPC-служб, для которых требуются конфиденциальность и целостность посредством шифрования SSL/TLS.

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

server {
    listen 443 ssl;
    grpc_ssl_certificate     /etc/ssl/certs/server.crt;
    grpc_ssl_certificate_key /etc/ssl/private/server.key;
}

Описание

Директива grpc_ssl_certificate_cache в NGINX предназначена для повышения эффективности gRPC-коммуникаций путем кэширования сертификатов SSL. Она позволяет администраторам указать механизм кэша для хранения сертификатов SSL, часто используемых в gRPC-соединениях, снижая необходимость многократной загрузки и разбора этих сертификатов. Это может значительно снизить задержку и повысить производительность за счет минимизации накладных расходов при повторном установлении защищенных соединений благодаря кэшированию. Эта директива может принимать от 1 до 3 параметров: размер кэша, TTL (Time To Live) для кэшируемых сертификатов и необязательный максимальный размер. Первый параметр задает размер кэша, обычно выражаемый в байтах (например, 10m для 10 мегабайт). TTL определяет, как долго сертификаты остаются действительными в кэше, прежде чем их удалят и заново загрузят. Администраторы могут настраивать эти параметры в зависимости от конкретной нагрузки на сервер и требований к производительности. Гибкость директивы позволяет создавать конфигурации, соответствующие различным требованиям gRPC-приложений, обеспечивая безопасную и эффективную доставку сервисов.

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

grpc_ssl_certificate_cache 10m 2m 1h;

Описание

Директива `grpc_ssl_password_file` используется в конфигурации NGINX для чтения пароля из указанного файла. Этот пароль важен при работе с зашифрованными SSL-сертификатами, которые часто требуются для защищённых gRPC-подключений. При настройке NGINX получит доступ к паролю во время инициализации SSL-контекста, что позволит ему расшифровывать соответствующие SSL-сертификаты. Путь к файлу с паролем должен быть передан в качестве аргумента этой директивы. С точки зрения контекста, директива `grpc_ssl_password_file` может быть размещена в блоках `http`, `server` или `location` файла конфигурации NGINX. Использование директивы критично при работе с gRPC-приложениями, которые полагаются на защищённые каналы. Если указанный файл с паролем отсутствует или недоступен для чтения, NGINX не сможет запуститься, и будет записана ошибка, указывающая на проблему с инициализацией SSL-сертификата. Также крайне важно обеспечить защиту файла с паролем с помощью соответствующих прав доступа в файловой системе, чтобы предотвратить несанкционированный доступ, поскольку он содержит конфиденциальную информацию, необходимую для работы защищённых gRPC-коммуникаций. В производственных средах управление безопасностью таких файлов критично для поддержания целостности и конфиденциальности SSL-коммуникаций.

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

server {
    listen 443 ssl;
    grpc_ssl_password_file /etc/ssl/private/grpc_password.txt;
    ssl_certificate /etc/ssl/certs/grpc_cert.pem;
    ssl_certificate_key /etc/ssl/private/grpc_key.pem;
}

Описание

Директива grpc_ssl_conf_command используется для задания конкретных параметров SSL для gRPC‑связи внутри NGINX. Эту директиву можно включать в контексты http, server или location, что обеспечивает гибкость конфигурации. Она принимает два аргумента, которые представляют команду для выполнения и соответствующее значение. Важным аспектом этой директивы является её возможность изменять настройки SSL специально для gRPC‑подключений, отдельно от стандартных конфигураций HTTP, что имеет решающее значение для обеспечения защищённых каналов связи в архитектуре микросервисов, основанной на gRPC. При использовании grpc_ssl_conf_command каждая указанная команда влияет на обработку входящих gRPC‑запросов и делает это с учётом контекста. Это означает, что в зависимости от уровня иерархии (http, server, location) команды могут применяться более локально или глобально, что позволяет администраторам тонко настраивать операции SSL в соответствии с различными требованиями безопасности для разных частей экосистемы NGINX. Директива особенно полезна для пользовательских конфигураций, которые не покрываются параметрами SSL по умолчанию, и потому необходима для пользователей, желающих улучшить свои gRPC‑развёртывания. Важно отметить, что для корректной работы необходимо указывать правильные значения; неверные аргументы могут привести к неверной конфигурации SSL, что может поставить под угрозу безопасность соединений или вызвать сбои в работе сервиса. Поэтому при использовании этой директивы рекомендуется внимательно сверяться как с документацией по SSL для NGINX, так и с требованиями gRPC.

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

grpc_ssl_conf_command valid_commands value;

Описание

Директива `gunzip` используется в NGINX для управления тем, должен ли сервер автоматически распаковывать тела HTTP-ответов, сжатых gzip, перед отправкой их клиенту. Когда она включена, NGINX будет распаковывать содержимое, позволяя клиентам, которые не поддерживают сжатие gzip, корректно интерпретировать ответ без дополнительной обработки на их стороне. Эта директива важна для обеспечения совместимости с различными клиентами, которые могут не уметь правильно обрабатывать кодирование gzip.\n\nДиректива `gunzip` принимает флаг в качестве аргумента, где `on` включает распаковку, а `off` отключает её. Эту директиву можно использовать в контекстах `http`, `server` и `location`, что позволяет тонко настроить, когда ответы должны распаковываться в зависимости от конфигурации. Важно использовать эту директиву осмотрительно: например, включение её для некоторых `location`, которые обслуживают ресурсы, которые могут быть сжаты, может сократить трафик и улучшить время загрузки, но при этом привести к дополнительным накладным расходам для очень маленьких файлов.\n\nПоскольку NGINX использует заголовок `Content-Encoding` для определения того, сжат ли ответ, директива `gunzip` работает в связке с директивами, связанными с gzip, которые контролируют процесс сжатия. Если ответ не сжат (то есть он не содержит заголовка `Content-Encoding: gzip`), установка `gunzip` не окажет никакого эффекта, и исходное содержимое будет отправлено как есть, независимо от состояния директивы. Пользователям следует убедиться, что при включении `gunzip` upstream‑сервер или приложение корректно устанавливают заголовки, чтобы сжатие могло полноценно применяться.

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

server {
    listen       80;
    server_name  example.com;

    location / {
        gunzip on;
        proxy_pass http://backend;
    }
}

Описание

`gunzip_buffers` директива указывает количество и размер буферов, используемых для хранения декомпрессированных данных из HTTP-ответов. Эта директива особенно полезна при работе с Gzip-сжатым содержимым, отправляемым клиенту, так как позволяет NGINX эффективно управлять распределением памяти для декомпрессированных данных. Первый параметр задаёт количество буферов, а второй параметр указывает размер каждого буфера в байтах. Когда обрабатывается Gzip-сжатый ответ, NGINX использует эти буферы для временного хранения распакованных данных перед отправкой клиенту. Использование директивы `gunzip_buffers` может улучшить производительность за счёт оптимизации использования памяти во время процесса декомпрессии. По умолчанию директива может быть не задана, что означает, что NGINX будет использовать встроенные размеры буферов для обработки декомпрессированных данных. Администраторам может потребоваться настроить эти параметры в соответствии с особенностями их приложения, особенно при обработке больших файлов или при высокой нагрузке, где правильные размеры буферов могут предотвратить узкие места в производительности. В итоге эта директива универсальна и может повысить эффективность обработки ответов в NGINX при работе с Gzip-сжатым содержимым.

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

http {
    gunzip on;
    gunzip_buffers 8 16k;
}

Описание

Директива 'gzip' в модуле HTTP Core NGINX используется для управления сжатием gzip для ответов, отправляемых клиентам. Включив эту директиву, NGINX будет сжимать ответы с помощью алгоритма gzip, что может существенно уменьшить размер передаваемых данных и улучшить время загрузки у клиентов. Сервер проверяет допустимые типы содержимого и возможности клиента (например, наличие заголовка 'Accept-Encoding: gzip'), чтобы определить, следует ли отвечать сжатым содержимым. Эта директива принимает булево значение: при установке в 'on' сжатие gzip включается, а 'off' отключает его. Кроме того, NGINX предоставляет несколько параметров конфигурации, которые могут уточнять поведение сжатия gzip, таких как 'gzip_types', задающий MIME-типы файлов для сжатия, и 'gzip_vary', указывающий, добавлять ли заголовок Vary к ответам, чтобы обозначить наличие другой версии для клиентов, которые не поддерживают gzip. Использование gzip может быть полезно для сокращения затрат на трафик и улучшения пользовательского опыта, особенно для текстовых файлов, таких как HTML, CSS и JavaScript. Важно использовать сжатие gzip осознанно, поскольку не все типы содержимого выигрывают от сжатия, и чрезмерное его применение может привести к ненужной нагрузке на CPU сервера.

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

http {
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
}

Описание

Директива gzip_buffers задаёт количество и размер буферов, выделяемых для хранения сжатых данных при использовании gzip-сжатия ответов, отправляемых NGINX. Эта директива принимает два параметра: первый задаёт число буферов, а второй — размер каждого буфера. Например, конфигурация `gzip_buffers 16 8k;` означает, что будет выделено 16 буферов по 8 килобайт каждый. Эти буферы используются для хранения сжатого вывода перед отправкой клиенту, и оптимизация этих значений может существенно повлиять на производительность, особенно при высокой нагрузке. Выбор большего размера буфера может уменьшить количество операций записи в выходной поток, что повышает пропускную способность за счёт увеличенного использования памяти. Напротив, меньшие размеры буферов могут привести к более частым операциям записи, но снизить потребление памяти. Важно учитывать, что общий объём буферов также определяется общим количеством выделенной памяти, которое может быть ограничено системными настройками или объёмом памяти, занятой приложением. Неправильная настройка этих значений может привести к неэффективному использованию памяти или узким местам в производительности, особенно при работе с большими ответами или при высоких объёмах трафика.

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

gzip on;
gzip_buffers 16 8k;

Описание

Директива `gzip_types` в NGINX используется для определения списка MIME-типов, которые должны сжиматься при включённом модуле `gzip`. Эта директива позволяет более точно контролировать, какие типы файлов подвергаются сжатию, оптимизируя доставку определённых типов содержимого и при этом потенциально исключая те, для которых сжатие может не дать значительного уменьшения размера. Директива принимает в качестве аргументов один или несколько MIME-типов. Указывая эти типы, вы гарантируете, что сжимаются только нужные типы содержимого, такие как текстовые файлы, что улучшает время загрузки и экономит трафик, не обрабатывая излишне нерелевантные типы файлов. Когда модуль gzip включён, он сравнивает заголовок ответа `Content-Type` с указанными MIME-типами в `gzip_types`. Если найдено совпадение, ответ сжимается перед отправкой клиенту. Эта функция особенно важна для текстового содержимого, такого как HTML, CSS, JavaScript и XML, поскольку позволяет существенно уменьшить размер и, следовательно, ускорить загрузку страниц. Тем не менее важно перечислять все релевантные MIME-типы, которые вы хотите сжимать, чтобы максимально повысить эффективность. Кроме того, следует учитывать особенности конкретных форматов файлов; например, некоторые бинарные форматы уже могут быть сжаты, из-за чего дополнительное сжатие с помощью gzip может быть малоэффективным или даже контрпродуктивным.

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

gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml;

Описание

Директива `gzip_comp_level` внутри NGINX HTTP Core module позволяет администраторам указать уровень сжатия, применяемого при отдаче содержимого, закодированного с помощью gzip. Допустимые значения находятся в диапазоне от 1 до 9, где 1 означает наименьшее сжатие (и наивысшую скорость обработки), а 9 указывает на максимальный уровень сжатия (что более ресурсоёмко для CPU). По умолчанию `gzip_comp_level` установлен в 1, то есть содержимое будет слабо сжиматься. Повышение этого значения улучшает коэффициент сжатия, что может сэкономить трафик; однако это также приводит к увеличению использования CPU в процессе сжатия. Этот компромисс необходимо тщательно учитывать, особенно для сайтов с большим трафиком, где чрезмерная нагрузка на CPU может повлиять на производительность. Кроме того, уровень сжатия применяется только к данным, подходящим для gzip-сжатия, таким как файлы HTML, CSS и JavaScript, как указано в других директивах `gzip`. Эта директива чувствительна к контексту и может быть определена в контекстах `http`, `server` или `location`, что позволяет гибко настраивать поведение в зависимости от конкретных потребностей. Установка её в контексте `http` применит указанный уровень сжатия глобально, тогда как настройки в контекстах `server` или `location` могут переопределять глобальную настройку для более тонкого контроля.

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

http {
    gzip on;
    gzip_comp_level 5;
}

Описание

Директива gzip_window настраивает максимальный размер скользящего окна, используемого алгоритмом сжатия zlib, когда в NGINX включено сжатие Gzip. Она указывает, какую часть входных данных можно хранить в памяти при сжатии ответа. Больший размер окна может повысить эффективность сжатия, позволяя ссылаться на больше данных при обработке каждого байта выходных данных, что приводит к лучшим коэффициентам сжатия. Однако это также увеличивает использование памяти рабочими процессами NGINX, что может быть нежелательно в средах с ограниченными ресурсами памяти. Эта директива принимает один аргумент, который должен быть указан в bytes, то есть, возможно, его нужно задать как числовое значение без суффикса. При установке директивы включается использование указанного размера окна для сжатия Gzip, что повышает общую производительность и эффективность доставки контента по HTTP. Если директива не настроена, будет применена настройка по умолчанию, которая, в зависимости от типа и размера сжимаемого контента, может не полностью задействовать потенциал алгоритма Gzip. На практике пользователям следует тщательно оценивать объём памяти сервера перед увеличением этого значения, особенно в условиях высокой нагрузки или при обработке больших ответов, так как чрезмерное выделение памяти может привести к её исчерпанию и ухудшению производительности.

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

gzip on;
 gzip_window 32k;  
 location / {
     gzip_types text/plain text/css application/json; 
     # any other configurations 
 }

Описание

Директива `gzip_hash` является частью модуля HTTP Core NGINX, который управляет тем, как NGINX обрабатывает gzip-сжатие HTTP-ответов. Задавая метод хеширования, она оптимизирует хранение и извлечение параметров gzip для кэшированного содержимого, что обеспечивает лучшую производительность при высокой нагрузке. Эту директиву можно настроить с использованием различных алгоритмов хеширования, таких как `md5`, `sha1` или `crc32`, что позволяет администратору адаптировать отзывчивость и использование ресурсов при gzip-сжатии в зависимости от возможностей сервера и ожидаемого типа содержимого. Выбор метода хеширования может повлиять как на производительность, так и на размер сохраняемых флагов gzip, а следовательно — на общий объём потребляемой памяти. NGINX анализирует контекст сжатия и генерирует значения хеша на основе настроенных параметров, чтобы гарантировать уникальные идентификаторы для сжатого содержимого в соответствии с выбранной хеш-функцией. Директиву `gzip_hash` можно разместить в контекстах `http`, `server` или `location`, что даёт гибкость в конфигурации. Важно учитывать, что выбор более сложной хеш-функции может повысить уникальность записей, но при этом потреблять дополнительные CPU-циклы, поэтому рекомендуется учитывать конкретные потребности вашего приложения и ожидаемую нагрузку при её настройке.

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

http {
    gzip on;
    gzip_hash sha1;
}

Описание

Директива 'postpone_gzipping' в NGINX указывает, следует ли откладывать gzip-сжатие тел ответов до момента отправки заголовков ответа. По умолчанию сериализация данных ответа в формате gzip выполняется немедленно. Однако при установке в 'on' NGINX откладывает сжатие до отправки HTTP-заголовков, что может быть полезно в случаях, когда сервер должен отдать приоритет своевременной отправке заголовков клиенту по сравнению с затратами на сжатие. Эта настройка может оптимизировать использование ресурсов и улучшить воспринимаемую задержку, особенно для больших ответов. Директива может использоваться в различных контекстах, включая http, server и location блоки. При применении она принимает один аргумент — 'on' или 'off'. Если установлено 'on', NGINX отложит процесс gzip, что даёт гибкость в обработке определённых типов ответов или в конкретных фазах обработки запроса. Напротив, установка в 'off' или отсутствие указания приведёт к тому, что NGINX будет выполнять gzip немедленно, применяя любые настроенные параметры сжатия сразу после формирования тела ответа.

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

http {
    gzip on;
    postpone_gzipping on;
}

Описание

Директива `gzip_no_buffer` в NGINX используется для управления буферизацией вывода для ответов, сжимаемых gzip. При установке в 'on' эта директива позволяет NGINX отправлять сжатый вывод напрямую клиенту без предварительного буферизации всего ответа в памяти. Такое поведение особенно полезно для больших ответов или при необходимости потоковой передачи данных в реальном времени, поскольку оно снижает использование памяти и потенциально повышает пропускную способность за счёт отправки данных клиенту по мере их генерации. Напротив, установка директивы в 'off' (что является значением по умолчанию) включает буферизацию и позволяет удерживать весь ответ в памяти до его сжатия и отправки, что может быть выгодно для оптимизации доставки ответов, особенно когда сервер извлекает выгоду из дедупликации данных и эффективности сжатия. Директива принимает один флаговый аргумент: 'on' или 'off'. Когда она активирована, ответы отправляются напрямую без буферизации, тогда как при выключенной опции происходит стандартное буферизированное поведение. Важно отметить, что отключение буферизации может повлиять на производительность в отдельных сценариях, особенно при обработке большого числа одновременных запросов или больших ответов, поскольку накладные расходы на динамическое сжатие данных могут увеличить нагрузку на систему.

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

http {
    gzip on;
    gzip_no_buffer on;
}

Описание

`gzip_min_length` директива управляет минимальным размером тела ответа, при превышении которого оно может быть сжато с помощью Gzip в NGINX. Когда формируется ответ, если размер тела меньше указанной длины, оно не будет сжато. Это полезно для оптимизации производительности, поскольку сжатие небольших ответов может быть более ресурсоёмким по CPU, чем простая отправка их несжатыми. Директива принимает аргумент, определяющий минимальную длину в байтах, и может быть установлена в контекстах `http`, `server` или `location`. Это позволяет задавать разные конфигурации для различных уровней иерархии сервера. Путём настройки этого значения администраторы могут найти баланс между накладными расходами на сжатие и экономией сетевого трафика. Это особенно важно в сценариях, где ответы состоят из небольших ресурсов (например, изображений или скриптов), которые могут не получать существенной выгоды от Gzip-сжатия. Чтобы задать эту директиву, достаточно указать числовое значение, представляющее порог в байтах. Например, установка `gzip_min_length 1000;` означает, что любое тело ответа меньше 1000 байт будет отправлено несжатым, а более крупные тела будут сжаты. Такое поведение помогает смягчить падение производительности, вызванное обработкой большого количества маленьких сжатых файлов.

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

http {
    gzip on;
    gzip_min_length 1000;
}

Описание

Директива `gzip_static` позволяет NGINX отдавать предварительно сжатые файлы с расширением `.gz` вместо сжатия файлов на лету. При включённой опции, если поступает запрос на сжатый ресурс, NGINX сначала проверит наличие соответствующего файла `.gz` в указанном расположении. Если такой файл найден, он будет отдан напрямую, минуя сжатие модуля `gzip` во время работы. Такой предварительно сжатый файл повышает производительность, особенно в периоды пиковой нагрузки, поскольку снижает нагрузку на CPU, связанную с динамическим сжатием `gzip`. Директива принимает один аргумент — `on` или `off`, указывающий, включить или выключить эту функцию. При установке в `on` NGINX проверяет наличие версий файлов, сжатых `gzip` (обычно с суффиксом `.gz`), при обработке запроса. Если такой файл недоступен, NGINX вернётся к отдаче обычного файла (если он существует) или вернёт ошибку, если не найден ни один из файлов. Такое поведение повышает эффективность доставки ресурсов, особенно для текстового содержимого, такого как HTML, CSS или JavaScript, где `gzip`-сжатие обычно даёт значительное уменьшение размера. Стоит отметить, что для эффективной работы `gzip_static` его часто комбинируют с директивой `gzip`, настроенной так, чтобы сжатие применялось к файлам на этапе сборки или развертывания. Кроме того, необходимо правильно управлять заголовками кэша, чтобы избежать отдачи устаревших данных при обновлении статических файлов.

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

http {
    gzip_static on;

    server {
        location / {
            root /var/www/html;
        }
    }
}

Описание

Директива 'expires' используется для установки времени жизни статических ресурсов, обслуживаемых NGINX. Определяя, как долго ресурс должен считаться актуальным, она помогает в кэшировании в браузере и оптимизации времени загрузки за счёт уменьшения количества запросов к серверу. Директива принимает в качестве аргумента значение времени, которое можно задать в секундах (например, '30s'), минутах (например, '5m'), часах (например, '12h') или днях (например, '1d'). Также доступны дополнительные опции: можно указать 'max' для неограниченного срока или 'epoch', чтобы установить время в прошлое. При установке директива 'expires' автоматически формирует соответствующие заголовки ответа для клиентских запросов. Её можно настроить в различных контекстах, включая 'http', 'server' и 'location'. Примечательно, что её также можно использовать внутри условных конструкций 'if' в блоке 'location' для более тонкого управления. Политики кэширования можно адаптировать для разных типов ресурсов, применяя несколько директив 'expires' в разных контекстах, что обеспечивает эффективную отдачу статических файлов.

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

location /images {
    expires 30d;
}

Описание

Директива `add_header` позволяет включать определённые HTTP-заголовки в ответы, отправляемые NGINX. Это особенно полезно для параметров конфигурации, таких как политики безопасности (`Strict-Transport-Security`, `Content-Security-Policy`) или для управления поведением кэширования (`Cache-Control`, `Expires`). При указании она устанавливает заголовки для заданного контекста (http, server или location). Можно определить несколько заголовков с помощью нескольких директив `add_header`, и если заголовок уже существует, его значение можно изменить с помощью этой директивы. Важная особенность: `add_header` не перезаписывает существующие заголовки, если не используется параметр `always`, который гарантирует включение добавленных заголовков даже когда код ответа указывает на ошибку (например, 4xx или 5xx). Это позволяет управлять видимостью заголовков независимо от логики ответа приложения.

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

server {
    listen 80;
    server_name example.com;
    add_header X-Frame-Options "DENY";
    location / {
        add_header Content-Security-Policy "default-src 'self'";
    }
}

Описание

Директива `add_trailer` используется для указания пользовательских полей заголовков, которые включаются в секцию трейлера ответа в ответах HTTP/2 и HTTP/3. Трейлеры — это дополнительные HTTP-заголовки, отправляемые после тела сообщения. Это может быть полезно для включения метаданных или информации о статусе, которые определяются только после отправки основного полезного содержимого. Эта директива принимает 2–3 параметра: первый параметр — имя добавляемого заголовка, а последующие параметры — значения, которые нужно связать с этим заголовком. Значения могут включать variables, что делает директиву гибкой для динамического содержимого заголовков. Если указано несколько значений, они будут объединены через запятую. Важно отметить, что не все клиенты корректно обрабатывают трейлеры, поэтому разработчикам следует убедиться, что их приложения могут правильно работать с ответами, которые содержат информацию в трейлерах. Кроме того, при использовании этой директивы следует проявлять осторожность, так как она может повлиять на кэширование и поведение клиента в зависимости от добавляемых заголовков.

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

server {
    location /example {
        add_trailer X-Custom-Trailer "Trailer Value";
    }
}

Описание

Директива `add_header_inherit` управляет наследованием директив заголовков, установленных с помощью `add_header`. Когда эта директива задана, она позволяет любым директивам `add_header`, определённым в родительском контексте (например, http или server), наследоваться дочерними контекстами (например, location). Это особенно полезно для обеспечения согласованности заголовков на разных уровнях конфигурации без необходимости повторно определять заголовки в каждом контексте, что упрощает управление конфигурацией. Директива принимает один аргумент, который указывает, следует ли включить или отключить это наследование: значение `on` разрешает наследование, а `off` — запрещает его. По умолчанию наследование отключено, если оно явно не включено. Когда наследование включено, любые заголовки, добавленные в родительском контексте, автоматически будут включены в ответы дочернего контекста, что позволяет серверу поддерживать единообразные заголовки, такие как заголовки безопасности, политики кэширования или пользовательские заголовки, которые вы хотите применить глобально в конкретном блоке конфигурации. Это повышает как безопасность, так и производительность за счёт уменьшения избыточности определений заголовков в нескольких блоках контекста или в location.

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

http {
    add_header X-Frame-Options "DENY";
    server {
        add_header_inherit on;
        location /api {
            # /api will inherit the X-Frame-Options header
        }
    }
}

Описание

Директива `add_trailer_inherit` предоставляет механизм для настройки того, как обрабатываются трейлерные заголовки (заголовки, отправляемые после основного тела ответа) в контексте проксируемого сервера. Когда директива включена, она позволяет наследовать эти трейлерные заголовки из ответа upstream-сервера и включать их в ответ, направляемый клиенту. Это особенно полезно при работе с кодировками передачи, такими как chunked, когда дополнительные заголовки нужно отправить в конце ответа, чтобы передать клиенту необходимые метаданные. Директива принимает один аргумент, который является логическим значением: либо 'on', либо 'off'. Если установлено 'on', NGINX включит любые трейлерные заголовки, полученные от upstream-сервера, в ответ, отправляемый клиенту. Если установлено 'off', эти заголовки включены не будут. Важно понимать, что наследование трейлерных заголовков может повлиять на поведение клиента, особенно в сценариях, связанных с HTTP/1.1 chunked-передачами. Поэтому при использовании этой директивы следует внимательно учитывать конфигурацию upstream-сервера и ожидания клиентов.

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

http {
    server {
        location /example {
            proxy_pass http://upstream_server;
            add_trailer_inherit on;
        }
    }
}

Описание

Директива `image_filter` является частью модуля фильтрации изображений NGINX, который предоставляет возможности обработки файлов изображений с помощью заданных фильтров. Эту директиву можно использовать внутри блока `location`, чтобы включить операции, такие как изменение размера, обрезка и изменение формата изображений, отдаваемых веб‑сервером. Директива принимает от одного до трёх аргументов: тип фильтра, его параметры и необязательные флаги конфигурации. Фильтры могут включать такие опции, как изменение размера изображения до заданных размеров или изменение формата для оптимизации времени загрузки и уменьшения использования ресурсов. В зависимости от указанных фильтров и их конфигурации NGINX обрабатывает файлы изображений динамически при запросе, вместо выдачи статических копий, что может значительно улучшить производительность и гибкость.

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

location /images {
    image_filter resize 800 600;
    image_filter_jpeg_quality 85;
    image_filter_cache on;
}

Описание

Директива `image_filter_jpeg_quality` позволяет указать качество JPEG-изображений при их обработке модулем фильтра изображений NGINX. Она принимает один аргумент, указывающий желаемый уровень качества в диапазоне от 1 до 100. Более низкое значение приводит к более сильному сжатию и ухудшению качества изображения, тогда как более высокое значение обеспечивает лучшее качество изображения, но увеличивает размер файлов. Если вы задаёте эту директиву в контексте `http`, `server` или `location`, NGINX применит указанную настройку качества ко всем JPEG-изображениям, обрабатываемым модулем фильтра изображений. Это особенно полезно для оптимизации доставки изображений за счёт баланса между размером файла и визуальным качеством, что может привести к улучшению времени загрузки и экономии пропускной способности для веб-приложений. Важно отметить, что эта директива будет работать только если модуль фильтра изображений включён и подключён в конфигурации NGINX. Особенность директивы в том, что при обслуживании изображений на сайте, где важны быстрые времена загрузки для пользователей, вам может потребоваться поэкспериментировать с настройкой качества, чтобы найти наилучший баланс между производительностью и внешним видом. Кроме того, изменения этой директивы потребуют перезагрузки конфигурации NGINX для вступления в силу.

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

http {
    location /images {
        image_filter jpeg;
        image_filter_jpeg_quality 85;
    }
}

Описание

`image_filter_webp_quality` директива используется для определения уровня качества изображений WebP, которые создаются при использовании модуля image_filter в NGINX. Эта директива принимает один аргумент — целое число, задающее качество (от 0 до 100) выходного изображения WebP: 100 соответствует наивысшему качеству и наименьшей компрессии, а 0 даёт наименьшее качество и максимальную компрессию. Директива должна быть включена в файлы конфигурации в контекстах `http`, `server` или `location`, так как она предназначена для управления тем, как изображения обрабатываются и отдаются. При настройке `image_filter_webp_quality` расширяет возможности NGINX по обслуживанию изображений за счёт преобразования входящих изображений в формат WebP, который часто имеет меньший размер по сравнению с другими форматами, такими как JPEG или PNG, без значительной потери визуального качества. Эта конвертация выполняется на лету, если клиент поддерживает формат WebP, что определяется по заголовку `Accept` в HTTP-запросе. Правильная установка параметра качества позволяет разработчикам балансировать между чёткостью изображений и эффективностью размера файлов в зависимости от конкретных потребностей приложения, тем самым улучшая время загрузки и производительность для страниц с большим количеством изображений.

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

location /images {
    image_filter png;
    image_filter_webp on;
    image_filter_webp_quality 85;
}

Описание

Директива 'image_filter_sharpen' используется в HTTP-сервере NGINX для применения эффекта повышения резкости к изображениям, обрабатываемым модулем фильтра изображений. Эта директива может улучшить внешний вид изображений, увеличивая контраст на краях и в мелких деталях. Она принимает один параметр, задающий величину повышения резкости, который контролирует степень усиления резкости изображения. Чем выше значение, тем резче становится изображение, но чрезмерная резкость может привести к артефактам. При правильной настройке директива 'image_filter_sharpen' может размещаться в разных контекстах, таких как блоки http, server и location. Директиву следует использовать совместно с модулем фильтра изображений, который обрабатывает файлы изображений, отсылаемые NGINX. Если изображение не обрабатывается или модуль фильтра не включен, директива не окажет никакого эффекта. Эффективность повышения резкости также может варьироваться в зависимости от исходного качества изображения. Важно, чтобы пользователи указывали числовые значения (обычно в диапазоне от 0 до 100) для тонкой настройки степени применения эффекта повышения резкости. Правильная установка значения в соответствии с требованиями визуального вывода может значительно улучшить четкость изображения при сохранении естественного вида и предотвращении чрезмерной резкости.

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

location /images {
    image_filter brighten 0.1;
    image_filter_sharpen 10;
}

Описание

Директива 'image_filter_transparency' позволяет задавать уровень прозрачности изображений, обрабатываемых модулем фильтра изображений NGINX. Эта директива принимает булев флаг, который, при включении, указывает NGINX отображать изображения с применёнными настройками прозрачности. Это особенно полезно при отдаче изображений, которым необходимо сохранять прозрачный фон для веб‑элементов, таких как логотипы или иконки, гарантируя, что заданная прозрачность в файле изображения будет соблюдена при доставке. Когда эта директива установлена в 'on', фильтр изображений будет обрабатывать изображения так, чтобы сохранять или применять прозрачные области в соответствии с альфа-каналом файла изображения. Эта настройка полезна веб‑разработчикам, стремящимся оптимизировать отображение изображений в различных браузерах и на разных платформах. Она служит простым переключателем, изменяющим способ хранения и передачи данных изображения без необходимости дополнительной обработки или манипуляций на стороне клиента. Директива влияет на то, как рендерятся изображения, но не позволяет настраивать уровни прозрачности помимо двоичного выбора включения или отключения функции. В контексте конфигурации её можно задать внутри блоков http, server или location, что обеспечивает гибкое применение в разных областях настройки. Правильное использование этой директивы в сочетании с другими директивами модуля фильтра изображений может существенно повлиять на визуальное качество изображений, отдаваемых экземпляром NGINX, и, как следствие, улучшить общий пользовательский опыт веб‑приложений.

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

location /images/ {
    image_filter on;
    image_filter_transparency on;
    try_files $uri =404;
}

Описание

Директива image_filter_interlace используется для управления тем, как изображения отдаются клиентам, особенно в отношении прогрессивного отображения. Когда интерлейсинг включён, изображения отправляются в браузер таким образом, что они могут загружаться и отображаться постепенно, улучшая восприятие пользовательского интерфейса при работе с большими изображениями на медленных соединениях. Директива принимает булев флаг: 'on' включает интерлейсинг, а 'off' отключает его. Это позволяет разработчикам выбирать, отдавать ли изображения в формате, позволяющем прогрессивное отображение, исходя из конкретного сценария использования и требований к производительности. Команду можно настроить в контекстах http, server или location, что позволяет применить её глобально или ограничить действие для отдельных мест. Например, включение этой директивы может быть особенно полезно при отдаче изображений галереи на сайте, поскольку пользователи будут видеть низкокачественную версию изображения во время загрузки, а не ждать полного рендеринга высококачественной версии. Важно учесть, что интерлейсинг обычно поддерживается только некоторыми форматами изображений (такими как PNG и JPEG) и может не приносить выигрыша во всех случаях. В средах, где производительность загрузки изображений критична, имеет смысл протестировать оба варианта, чтобы определить, какой обеспечивает наилучший пользовательский опыт.

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

location /images/ {
    image_filter on;
    image_filter_interlace on;
}

Описание

Директива `image_filter_buffer` настраивает объём памяти, выделяемой для обработки изображений при использовании модуля фильтра изображений NGINX. Эта директива важна при работе с крупными изображениями, так как позволяет эффективно их обрабатывать и избегать чрезмерного выделения памяти, что могло бы привести к снижению производительности. Размер буфера позволяет веб‑серверу NGINX временно удерживать данные изображения в памяти при выполнении операций, таких как изменение размера, обрезка или модификация изображений, перед их отправкой клиентам. Эту директиву можно задавать в контекстах `http`, `server` или `location`. При указании она принимает один аргумент, обозначающий размер буфера в байтах. Если указанный размер недостаточен для обработки изображения, NGINX может вернуть ошибку или не суметь корректно обработать изображение. Поэтому важно убедиться, что буфер настроен соответствующим образом в зависимости от размера и типа изображений, которые обслуживаются или обрабатываются. На практике эта директива помогает поддерживать эффективность использования ресурсов сервера, одновременно обеспечивая возможность беспрепятственного выполнения операций с изображениями. При установке этого значения следует учитывать доступную память сервера и ожидаемую нагрузку, чтобы найти баланс между производительностью и потреблением памяти.

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

location /images/ {
    image_filter buffer 16k;
    image_filter resize 200x200;
}

Описание

Директива 'index' в NGINX указывает файл по умолчанию, который должен возвращаться, когда клиент запрашивает директорию. Эта директива особенно полезна в случаях, когда в директории нет файла 'index', указанного пользователем, или когда пользователь прямо запрашивает путь директории. Сервер будет искать указанные файлы 'index' в том порядке, в котором они перечислены, до тех пор, пока один не будет найден, либо пока не исчерпаются все варианты. Это позволяет настраивать поведение по умолчанию в зависимости от потребностей приложения. Можно указать несколько файлов 'index', разделяя их пробелами, и NGINX будет проверять наличие каждого файла в заданном порядке. Если ни один из указанных файлов 'index' не найден, NGINX вернёт ошибку 403 Forbidden или 404 Not Found в зависимости от настроек конфигурации. Такая гибкость делает директиву 'index' ключевой частью возможности NGINX бесшовно обслуживать динамические веб-приложения и статический контент.

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

location / {
    index index.php index.html index.htm;
}

Описание

Директива 'limit_conn_zone' используется в контексте HTTP для определения зоны памяти, где можно отслеживать количество подключений по заданному ключу (например, по удалённому адресу). Она позволяет установить ограничения на количество одновременно открытых подключений с одного IP‑адреса или по любому другому параметру, что помогает уменьшить злоупотребления или исчерпание ресурсов из‑за чрезмерного числа подключений. Директива принимает два аргумента: первый — ключ, который обычно использует переменные, такие как '$binary_remote_addr' для ссылки на удалённый адрес клиента, или '$servername' для ограничений по имени сервера. Второй аргумент определяет размер зоны разделяемой памяти (например, '10m' для 10 мегабайт). Эта зона памяти используется для хранения счётчиков подключений для указанных клиентов, обеспечивая эффективное отслеживание и ограничение подключений в реальном времени. В сочетании с директивой 'limit_conn' администраторы могут указать, сколько одновременных подключений разрешено для каждого ключа, повышая безопасность и производительность. Установленные ограничения по памяти гарантируют, что это отслеживание будет эффективным без чрезмерного потребления ресурсов.

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

http {
    limit_conn_zone $binary_remote_addr zone=addr:10m;
    server {
        location / {
            limit_conn addr 10;
        }
    }
}

Описание

Директива `limit_conn` в NGINX используется для ограничения количества одновременных подключений, которые могут быть установлены с одного IP address к конкретному серверу или блоку location. Это важно для предотвращения злоупотреблений или перегрузки, вызванной слишком большим числом подключений, что может ухудшить производительность сервера. Директива принимает два аргумента: имя зоны и максимальное число подключений, разрешённых для каждого IP address. Директива работает совместно с `limit_conn_zone`, которая определяет разделяемую область памяти для отслеживания количества подключений с IP address. Когда поступает запрос, NGINX увеличивает счётчик подключений для исходного IP address в заданной зоне. Если количество подключений превышает установленный лимит, клиент получит ошибку 503 Service Unavailable. Счётчик подключений ведётся по каждому IP address и обычно хранится в памяти, что обеспечивает быструю проверку лимитов подключений без необходимости в постоянном хранилище. Это помогает управлять перегрузками и обеспечивает справедливое распределение ресурсов сервера между пользователями. Для реализации директивы администраторам необходимо задать лимит в соответствующем контексте (http, server или location) и убедиться, что настроена соответствующая директива `limit_conn_zone`. Баланс между определением зоны и установкой лимита в соответствии с ожидаемым трафиком является ключевым для эффективного использования этой директивы.

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

http {
    limit_conn_zone $binary_remote_addr zone=addr:10m;
    server {
        location / {
            limit_conn addr 1;
        }
    }
}

Описание

Директива `limit_conn_log_level` используется для определения уровня логирования событий, когда число подключений превышает допустимый лимит, заданный директивой `limit_conn`. Это может помочь при отладке и мониторинге, поскольку позволяет администраторам оценивать серьёзность ситуации, регулируя степень подробности записей в журнале. Директива принимает один аргумент — уровень логирования, который может быть одним из предопределённых уровней NGINX, таких как `error`, `warn`, `info`, `notice` и т.д. В зависимости от выбранного уровня будет логироваться разное количество информации о нарушении ограничения подключений, что полезно для оперативного анализа и диагностики. Устанавливая эту директиву в разных контекстах, таких как HTTP, server или location blocks, вы получаете детальный контроль над тем, как регистрируются проблемы с лимитом подключений в различных частях вашего веб-приложения. Это целенаправленное логирование помогает выявлять конкретные проблемы на разных уровнях архитектуры вашего веб-сервера.

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

http {
    limit_conn_zone $binary_remote_addr zone=addr:10m;
    limit_conn addr 10;
    limit_conn_log_level warn;
    # Other settings...
}

Описание

Директива `limit_conn_status` в NGINX задаёт код состояния HTTP, который будет возвращён клиентам, если их запрос превысит настроенные ограничения на количество подключений для данного контекста (http, server, or location). Эта директива позволяет администраторам настроить поведение ответа, обеспечивая более информативный интерфейс для пользователей, которые могут непреднамеренно попытаться установить больше подключений, чем разрешено конфигурацией NGINX. Когда нарушается лимит, заданный с помощью `limit_conn`, вместо возврата стандартного ответа 503 (Сервис недоступен), который может не дать пользователям понятной информации, может быть возвращён указанный код состояния. Это повышает ясность и помогает в процессе обработки ошибок для клиентских приложений. Код состояния должен быть допустимым HTTP-кодом, и, как правило, разумно избегать распространённых кодов успеха или перенаправления, чтобы не вводить в заблуждение. Для эффективного использования этой директивы рекомендуется оценить ожидаемое поведение клиентских приложений при превышении лимитов, поскольку код состояния, отличный от 503, может изменить то, как клиенты реагируют на проблемы с пропускной способностью. Например, код 429 (Слишком много запросов) может быть уместен, указывая, что пользователя ограничивают за чрезмерный доступ к ресурсам. Эта директива также может сочетаться с логами, адаптированными для мониторинга нарушений ограничений подключений.

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

http {
    limit_conn_zone $binary_remote_addr zone=addr:10m;
    limit_conn addr 10;
    limit_conn_status 429;
}

Описание

Директива `limit_conn_dry_run` — это функция, позволяющая администраторам тестировать настройки лимитов соединений без фактического отказа в соединении. Когда она включена, сервер не блокирует соединения, превышающие заданные лимиты, но фиксирует в логах случаи, в которых эти лимиты были бы применены. Это особенно полезно при настройке и валидации конфигураций без влияния на опыт пользователей, поскольку позволяет администратору собрать данные о возможных последствиях введения лимитов до их полного применения. Директива может быть задана в контекстах `http`, `server` или `location` и принимает в качестве аргумента флаг (on/off). Когда она включена (установлена в 'on'), NGINX будет симулировать применение лимитов без блокировки дополнительных соединений. Важно отметить, что пока эта директива активна, реальные соединения не будут отклоняться, что даёт ясное представление об использовании относительно лимитов без нарушения работы. Тем не менее, администраторам следует проявлять осторожность при использовании этой директивы в продуктивной среде, поскольку сервер по‑прежнему будет записывать в логи случаи превышения лимитов, что может ввести в заблуждение при наблюдении, если директиву принять за реальное принудительное ограничение. Идеально использовать её временно при оценке конфигураций.

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

http {
    limit_conn_zone $binary_remote_addr zone=addr:10m; 
    server {
        limit_conn addr 10;
        limit_conn_dry_run on;
    }
}

Описание

Директива 'limit_req_zone' используется внутри контекста http конфигурации NGINX для определения области общей памяти, которая связана с механизмом ограничения скорости запросов. Она принимает три параметра: ключ, определяющий контекст, в котором будут учитываться запросы (например, IP-адрес клиента или переменная), имя зоны, в которой хранятся счётчики запросов, и максимальный размер этой области общей памяти. При правильной настройке NGINX группирует входящие запросы на основе заданного ключа и подсчитывает эти запросы с течением времени. Например, если ключ — IP-адрес клиента, NGINX будет отслеживать, сколько запросов поступает с каждого отдельного IP. Это позволяет администраторам предотвращать злоупотребления и ограничивать чрезмерное использование конкретных ресурсов. Функция ограничения запросов работает с использованием двух основных опций, burst и nodelay, которые можно указать совместно с директивой 'limit_req' для управления обработкой избыточных запросов. Выбранные параметры должны отражать потребности вашего развертывания, так как разные приложения могут требовать более высоких или низких лимитов и могут быть затронуты одновременными всплесками запросов от пользователей. Поэтому правильная настройка этих параметров критична, чтобы не ограничивать невольно легитимных пользователей, при этом эффективно смягчая злоупотребления.

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

limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;

Описание

Директива 'limit_req' используется в NGINX для ограничения числа запросов, которые клиент может отправить на сервер за указанный период времени. Эта директива является частью HTTP Core Module и может применяться в разных контекстах, включая http, server, and location blocks. Основная цель этой директивы — контролировать трафик и предотвращать злоупотребления со стороны клиентов, отправляющих слишком много запросов, что может повлиять на производительность и стабильность сервера. Директива 'limit_req' принимает от одного до трёх параметров: 1. **zone** (обязательно): общая область памяти, в которой хранится конфигурация ограничения скорости запросов. 2. **burst** (опционально): позволяет обработать определённое количество избыточных запросов немедленно (без задержки), когда лимит кратковременно превышен. Значение burst допускает всплески трафика. 3. **nodelay** (опционально): если указано, избыточные запросы будут обработаны немедленно, если они не превышают значение burst; в противном случае они задерживаются в соответствии с ограничением скорости. Пользователям необходимо определить общую область памяти с помощью директивы 'limit_req_zone' перед использованием 'limit_req'. Ограничение скорости основано на параметрах, заданных в этих зонах, которые определяют, сколько запросов может исходить от определённого ключа (например, IP address) за указанный период.

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

limit_req_zone $binary_remote_addr zone=mylimit:10m rate=1r/s;
server {
    location /api {
        limit_req zone=mylimit burst=5 nodelay;
    }
}

Описание

Директива `limit_req_log_level` позволяет администраторам указать уровень серьёзности логирования, при котором нарушения лимитов запросов будут фиксироваться. Эта директива может быть определена в контекстах `http`, `server` или `location` и принимает один аргумент, задающий уровень логирования. Доступные уровни включают `error`, `warn`, `info`, `debug` и т.д. По умолчанию, если не настроено иначе, NGINX использует уровень логирования `error` для записей о лимитировании запросов. Когда лимиты запросов, определённые с помощью директивы `limit_req_zone`, превышаются, NGINX может логировать эти события согласно указанному уровню логирования. Это важно для мониторинга: позволяет настроить подробность логов в соответствии с оперативными требованиями или устранять проблемы, связанные с ограничением трафика. Особенно полезно в средах с высоким трафиком, где избыточное логирование может скрывать критически важную информацию. Механизм логирования интегрирован с возможностями логирования ошибок NGINX, поэтому вы можете просматривать эти журналы, чтобы выявлять закономерности и предпринимать соответствующие действия для оптимизации обработки запросов.

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

http {
    limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;
    limit_req_log_level warn;
}

Описание

Директива `limit_req_status` является частью модуля NGINX HTTP Core и используется совместно с механизмами ограничения скорости, реализованными директивой `limit_req`. Когда клиент превышает допустимую частоту запросов, в ответ на отклонённые механизмом ограничения запросов обращения возвращается указанный HTTP-код состояния. Это позволяет отправлять пользовательское сообщение, например 503 Service Unavailable, чтобы уведомить клиента о применённом ограничении вместо простого отказа в обработке его запросов. Эта директива принимает один аргумент: требуемый HTTP-код состояния, который будет отправлен в ответе при превышении лимитов запросов. Пользователи могут указать любой допустимый HTTP-код состояния, что обеспечивает гибкость в зависимости от требований их приложения. Чаще всего используются коды 503 (недоступность сервиса) или 429 (слишком много запросов). Важно отметить, что директива влияет только на те запросы, которые не обрабатываются из-за ограничений, и не затрагивает успешно обработанные запросы, находящиеся в пределах лимитов. Как директива конфигурации она может быть определена на уровнях контекстов `http`, `server` или `location`, что даёт возможность применять разные коды состояния в зависимости от области приложения. Разработчикам следует убедиться, что указанный код состояния согласуется с логикой обработки ошибок их приложения и ожиданиями пользователей при применении ограничения скорости.

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

limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;

server {
    location / {
        limit_req zone=one;
        limit_req_status 503;
    }
}

Описание

Директива limit_req_dry_run специально разработана для упрощения разработки и тестирования конфигураций ограничения частоты запросов в NGINX. При включении она фактически моделирует эффект ограничения частоты запросов, обрабатывая запросы без применения реальных ограничений. Это особенно полезно в ситуациях, когда администраторы хотят наблюдать, сколько запросов было бы обработано и потенциально отклонено из‑за превышения лимитов, не влияя на рабочий трафик. Эта директива принимает бинарный аргумент — либо on, либо off. При установке в on NGINX выполняет проверки ограничения частоты запросов в соответствии с другими директивами, такими как limit_req_zone, но не отклоняет запросы на основании этих лимитов. Вместо этого в логах будет отмечено, были ли превышения. Это позволяет тонко настраивать параметры ограничения частоты запросов и убеждаться, что всё работает как предсказано перед полноценным развёртыванием. Директива чувствительна к контексту и может быть сконфигурирована внутри блоков http, server или location в конфигурациях NGINX. Используя limit_req_dry_run, администраторы могут собирать данные о поведении и шаблонах запросов, что помогает эффективно определить подходящие лимиты частоты, которые следует применить после отключения директивы. Однако важно помнить, что при включённом режиме тестирования фактическое ограничение частоты запросов не будет действовать, что может привести к незамеченным всплескам трафика, если лимиты будут установлены слишком высоко после начала принудительного применения.

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

http {
    limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;

    server {
        location / {
            limit_req zone=one;
            limit_req_dry_run on;
        }
    }
}

Описание

Директива 'log_format' используется в контексте 'http' для указания того, как должны форматироваться записи логов. Каждая запись журнала может включать переменные, представляющие различные параметры запроса и сервера, такие как IP-адрес клиента, метод запроса, статус ответа и другие. По умолчанию записи логов генерируются в простом формате, но использование директивы 'log_format' позволяет настроить формат в соответствии с конкретными потребностями логирования. Эта директива требует как минимум двух аргументов, включая имя формата лога и собственно строку формата, задающую желаемый макет вывода для записей логов. Строка формата может включать различные переменные (например, $remote_addr для IP клиента, $request_time для длительности запроса) и статический текст. Параметры также могут включать условные значения и специальные параметры форматирования для повышения детализации логирования. Кроме того, после определения формата лога он может быть использован в директиве 'access_log', которая управляет тем, куда записываются логи. В одной конфигурации NGINX можно определить несколько форматов логов, что обеспечивает гибкость для различных сценариев логирования.

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

log_format main '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"';

access_log /var/log/nginx/access.log main;