Skip to content

Nginx Шпаргалка

Высокопроизводительный HTTP-сервер и обратный прокси.

01

С чего начать

Базовая конфигурация

Конфигурация Nginx использует иерархическую структуру блоков. worker_processes задаёт число процессов. Блок http содержит блоки server, а те — блоки location. Всегда проверяйте конфигурацию через nginx -t перед перезагрузкой.

nginx
# /etc/nginx/nginx.conf
worker_processes auto;

events {
    worker_connections 1024;
}

http {
    server {
        listen 80;
        server_name example.com;

        location / {
            root /var/www/html;
            index index.html;
        }
    }
}

# Test config: nginx -t
# Reload: nginx -s reload
# Start: systemctl start nginx

Директивы и контексты

Контексты вложены: main > events/http/mail > server > location. Простые директивы заканчиваются точкой с запятой, блочные используют фигурные скобки. Некоторые директивы допустимы только в определённых контекстах.

nginx
# Contexts are hierarchical blocks
# Global context (main) - outside any block
user nginx;
worker_processes auto;

# events context
events {
    worker_connections 1024;
}

# http context
http {
    # server context
    server {
        listen 80;
        # location context
        location / {
            root /var/www/html;
        }
    }
}

# Directives: simple (name value;) or block (name { ... })

Проверка и перезагрузка

nginx -t проверяет синтаксис И пытается открыть указанные файлы (сертификаты, логи). Всегда запускайте её перед перезагрузкой. reload посылает SIGHUP: воркеры завершают текущие запросы, затем перезагружаются. restart вызывает кратковременный простой.

nginx
# test configuration for syntax errors
nginx -t

# test and print full config
nginx -T

# reload config without dropping connections
nginx -s reload

# stop gracefully (finishes current requests)
nginx -s quit

# stop immediately
nginx -s stop

# reopen log files (after log rotation)
nginx -s reopen

# systemd alternative
systemctl reload nginx
systemctl restart nginx

Main против HTTP-контекста

worker_processes и events живут в контексте main. Маршрутизация, проксирование, кеширование и блоки server — в http. SSL, логирование и gzip можно задать в http, и они наследуются server/location.

nginx
# main context - global settings
user nginx;
worker_processes auto;
worker_rlimit_nofile 65535;
pid /var/run/nginx.pid;

events {
    worker_connections 4096;
}

http {
    # all HTTP-related config lives here
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    sendfile      on;
    keepalive_timeout 65;

    include /etc/nginx/conf.d/*.conf;
}

Include-файлы

include-файлы делают конфигурацию модульной. Глоб conf.d (*.conf) — современное соглашение. sites-enabled с симлинками — паттерн Debian/Ubuntu. mime.types сопоставляет расширения файлов с Content-Type.

nginx
# main config: /etc/nginx/nginx.conf
http {
    include /etc/nginx/mime.types;
    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}

# /etc/nginx/conf.d/default.conf
server {
    listen 80;
    server_name example.com;
    root /var/www/html;
}

# Disable a site: remove the file from sites-enabled/
# Available sites kept in sites-available/, symlinked into enabled/

Операции в командной строке

nginx -V показывает параметры сборки, включая встроенные модули. -g задаёт директивы, переопределяющие конфигурацию. -c удобен для проверки альтернативных конфигов без изменения конфигурации по умолчанию.

nginx
# start nginx (if not managed by systemd)
nginx

# specify a custom config file
nginx -c /path/to/nginx.conf

# set a global directive from command line
nginx -g "worker_processes 4;"

# test config
nginx -t

# print version and build configuration
nginx -V

# send signal to master process
nginx -s reload
nginx -s stop
02

Server-блоки

Базовый server-блок

Блок server определяет виртуальный хост. listen задаёт порт. server_name сопоставляется с заголовком Host. root задаёт корень документов. index указывает, какие файлы отдавать при запросе каталога.

nginx
server {
    listen 80;
    server_name example.com www.example.com;
    root /var/www/example;
    index index.html index.htm;

    location / {
        try_files $uri $uri/ =404;
    }
}

Несколько имён сервера

Nginx сопоставляет server_name сначала точно, затем по шаблону (*.foo.com), затем по regex. Запрос обрабатывает первый подходящий блок server. Для разных приложений на одном порту используйте отдельные блоки.

nginx
server {
    listen 80;
    server_name example.com www.example.com;
    # ...
}

server {
    listen 80;
    server_name api.example.com;
    # ...
}

# Wildcard: matches any single-level subdomain
server_name *.example.com;

# Regex (starts with ~)
server_name ~^www\d+\.example\.com$;

Сервер по умолчанию

default_server обрабатывает запросы, чей заголовок Host не совпал ни с одним server_name. Подчёркивание — соглашение (недопустимое имя хоста, которое никогда не совпадёт с реальным трафиком). return 444 закрывает соединение без ответа.

nginx
# mark a server block as default for the port
server {
    listen 80 default_server;
    server_name _;
    return 444;  # drop connection (no response)
}

# handles all requests that don't match another server_name
# _ is an invalid hostname, used as catch-all convention
# useful to block requests with no matching Host header

Директива listen

listen может привязаться к конкретному адресу, IPv6, UNIX-сокету или установить default_server. Параметр ssl включает TLS для этого слушателя. В одном блоке server допускается несколько директив listen.

nginx
# listen on port 80
listen 80;

# IPv6
listen [::]:80;

# HTTPS (ssl flag)
listen 443 ssl;
listen [::]:443 ssl;

# specific address
listen 127.0.0.1:8080;

# default server for this port
listen 80 default_server;

# listen on UNIX socket
listen unix:/var/run/nginx.sock;

Сопоставление server_name

Приоритет сопоставления: точное > с ведущим шаблоном > с завершающим шаблоном > regex. Regex проверяются в порядке конфигурации, поэтому побеждает первое совпадение. Увеличьте размер хеш-корзины, если имена серверов длинные или их много.

nginx
# Order of precedence (highest to lowest):
# 1. Exact name: example.com
# 2. Longest wildcard starting with *: *.example.com
# 3. Longest wildcard ending with *: www.*
# 4. First matching regex (in config order): ~^www\d+\.

# If nothing matches, the default_server handles it

# Tune hash sizes for many server names
http {
    server_names_hash_bucket_size 64;
    server_names_hash_max_size 512;
}

Catch-all сервер

Catch-all не даёт запросам с произвольным заголовком Host добраться до ваших приложений. return 301 перенаправляет на известный хост. return 444 сбрасывает соединение — полезно против сканеров, обращающихся напрямую по IP.

nginx
# catch all requests regardless of host header
server {
    listen 80 default_server;
    server_name _;  # invalid name, never matches real host

    return 301 https://$host$request_uri;
}

# or drop the connection silently
server {
    listen 80 default_server;
    server_name _;
    return 444;
}

# redirect unknown subdomains to main site
server {
    listen 80 default_server;
    return 301 https://example.com;
}
03

Блоки location

Модификаторы location

Модификаторы меняют поведение сопоставления: = (точное), ^~ (префикс, пропустить regex), ~ (regex с учётом регистра), ~* (regex без учёта регистра), без модификатора (префикс). Regex лучше для расширений файлов, префикс — для деревьев путей.

nginx
# exact match - fastest, stops search if matched
location = /favicon.ico {
    log_not_found off;
}

# prefix match with ^~ - skips regex if longest prefix matches
location ^~ /static/ {
    root /var/www;
}

# case-sensitive regex
location ~ \.php$ {
    fastcgi_pass unix:/run/php/php-fpm.sock;
}

# case-insensitive regex
location ~* \.(jpg|jpeg|png|gif|ico)$ {
    expires 30d;
}

# prefix match (no modifier)
location / {
    try_files $uri $uri/ /index.php;
}

Приоритет location

Nginx сначала проверяет точное совпадение (=), затем префиксные (побеждает самый длинный), затем regex в порядке конфигурации. ^~ заставляет префиксное совпадение пропустить проверку regex. Понимание этого порядка избавляет от сюрпризов с пересекающимися location.

nginx
# Priority order (highest to lowest):
# 1. =     exact match
# 2. ^~    prefix match (skips regex if matched)
# 3. ~ ~*  regex (first match in config order)
# 4. (none) prefix match (longest wins)

location = /api {
    # exact, highest priority
}

location ^~ /assets/ {
    # prefix, beats regex
}

location ~ \.php$ {
    # regex
}

location /api/ {
    # prefix, lowest of these
}

root против alias

root добавляет URI к своему значению; alias заменяет совпавший префикс. Используйте root, когда location соответствует подкаталогу дерева. Используйте alias, когда путь URI отличается от пути в файловой системе. alias с regex требует захвата $1.

nginx
# root: appends the full URI to the path
# request /img/cat.png -> /var/www/img/cat.png
location /img/ {
    root /var/www;
}

# alias: replaces the matched location part
# request /img/cat.png -> /data/images/cat.png
location /img/ {
    alias /data/images/;
}

# alias with regex requires capturing the path
location ~ ^/img/(.*)$ {
    alias /data/images/$1;
}

try_files

try_files проверяет каждый аргумент по порядку; последний — запасной вариант (без проверки файла). $uri проверяет файл, $uri/ — каталог. Запасным вариантом может быть URI, =код или @имя. Необходим для маршрутизации SPA и CMS.

nginx
# try files in order, fall back to last option
location / {
    try_files $uri $uri/ /index.html;
}

# serve index.php if file/dir not found (pretty URLs)
location / {
    try_files $uri $uri/ /index.php?$query_string;
}

# return 404 if nothing matches
location / {
    try_files $uri =404;
}

# named location as fallback
location / {
    try_files $uri $uri/ @drupal;
}

Именованные location

Именованные location (@name) только внутренние: URI запроса никогда не сопоставляется с ними напрямую. Они служат целями для try_files, error_page и rewrite. Отлично подходят для переиспользования блока конфигурации (например, обработчика запасного варианта) в нескольких location.

nginx
# named locations start with @, can't be reached externally
# used as try_files fallback or rewrite target

location / {
    try_files $uri $uri/ @app;
}

location @app {
    fastcgi_pass unix:/run/php.sock;
    # ... fastcgi config
}

# useful for organizing common error logic
location @error_page {
    return 500 "Internal Server Error";
}

# can also be used with error_page
error_page 404 @fallback;
location @fallback {
    proxy_pass http://backend;
}

Вложенные location

Location могут вкладываться. Внутренние наследуют директивы внешних и могут их переопределять. Полезно для особой обработки пути внутри более широкого префикса (например, увеличенный размер тела для загрузок или раздача статики из одного подпути).

nginx
location /api {
    # /api/users, /api/posts handled here
    proxy_pass http://backend;

    location /api/upload {
        # override for upload endpoint
        client_max_body_size 50M;
        proxy_pass http://upload_backend;
    }

    location ~ ^/api/static/(.*)$ {
        # regex inside prefix location
        root /var/www;
    }
}
04

Обратный прокси

Базовый proxy_pass

proxy_pass передаёт запросы на upstream-сервер. Завершающий слэш в proxy_pass приводит к замене совпавшего префикса location. Без завершающего слэша исходный URI передаётся без изменений.

nginx
server {
    listen 80;
    server_name app.example.com;

    location / {
        proxy_pass http://localhost:3000;
    }
}

# proxy_pass with URI replacement (trailing slash matters)
location /api/ {
    proxy_pass http://backend/;  # /api/foo -> /foo
}

# without trailing slash, URI is preserved
location /api/ {
    proxy_pass http://backend;   # /api/foo -> /api/foo
}

Заголовки прокси

По умолчанию nginx не передаёт IP клиента и исходный хост. Установка X-Real-IP и X-Forwarded-For позволяет бэкенду определить настоящего клиента. X-Forwarded-Proto сообщает исходную схему — критично для логики редиректов на HTTPS.

nginx
location / {
    proxy_pass http://backend;

    # preserve original host
    proxy_set_header Host $host;

    # real client IP (not nginx's)
    proxy_set_header X-Real-IP $remote_addr;

    # forwarded-for chain
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    # scheme (http or https)
    proxy_set_header X-Forwarded-Proto $scheme;

    # original host
    proxy_set_header X-Forwarded-Host $host;
}

Upstream-прокси

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

nginx
# define a named pool of backend servers
upstream backend {
    server 10.0.0.1:8080;
    server 10.0.0.2:8080;
    server 10.0.0.3:8080;
}

server {
    listen 80;

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

# useful upstream variables:
# $upstream_addr, $upstream_status,
# $upstream_response_time, $upstream_cache_status

Таймауты прокси

proxy_connect_timeout — лимит TCP-рукопожатия; таймауты чтения и отправки относятся к периодам простоя при передаче данных. Увеличивайте read_timeout для медленных эндпоинтов (экспорт, инференс ИИ). keepalive в upstream переиспользует соединения, снижая задержку.

nginx
location / {
    proxy_pass http://backend;

    # connect timeout (TCP handshake to upstream)
    proxy_connect_timeout 5s;

    # time between reads from upstream (response)
    proxy_read_timeout 60s;

    # time between writes to upstream (request body)
    proxy_send_timeout 60s;

    # for slow backends (large uploads/downloads)
    proxy_read_timeout 300s;
}

# keepalive connections to upstream
upstream backend {
    server 10.0.0.1:8080;
    keepalive 32;
}

Буферизация прокси

Буферизация сохраняет ответ upstream в памяти или на диске перед отправкой клиенту — эффективно для медленных клиентов, но ломает стриминг. Отключайте её для SSE, WebSocket и потоковой передачи чанками. buffer_size — первая часть (заголовки); buffers хранят остальное.

nginx
location / {
    proxy_pass http://backend;

    # enable buffering (default on)
    proxy_buffering on;
    proxy_buffer_size 4k;
    proxy_buffers 8 4k;

    # busy buffers during streaming
    proxy_busy_buffers_size 16k;

    # disable for streaming/SSE
    proxy_buffering off;
    proxy_cache off;
}

# Server-Sent Events or streaming responses
location /events {
    proxy_pass http://backend;
    proxy_buffering off;
    proxy_cache off;
    chunked_transfer_encoding on;
}

Апгрейд до WebSocket

WebSocket требует HTTP/1.1 плюс заголовки Upgrade и Connection. Блок map преобразует заголовок Upgrade в правильное значение Connection (upgrade или close). Большой proxy_read_timeout не даёт простаивающим WebSocket-соединениям закрываться.

nginx
# Map the Upgrade header to a Connection value
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;

    location /ws {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        # keepalive for long-lived connections
        proxy_read_timeout 3600s;
    }
}
05

Балансировка нагрузки

Блок upstream

Блок upstream определяет серверы бэкенда. Балансировка по умолчанию — round-robin. max_fails и fail_timeout настраивают пассивные проверки здоровья: после max_fails неудач в течение fail_timeout сервер помечается недоступным на fail_timeout секунд.

nginx
upstream backend {
    server backend1.example.com weight=5;
    server backend2.example.com;
    server backend3.example.com max_fails=3 fail_timeout=30s;
}

server {
    location / {
        proxy_pass http://backend;
    }
}

# default algorithm: round-robin
# max_fails: failed attempts before marking server down
# fail_timeout: window for counting fails AND downtime duration

Методы балансировки

round-robin распределяет равномерно; least_conn отправляет на наименее загруженный сервер; ip_hash закрепляет клиента за одним сервером (липкие сессии по IP); hash распределяет по пользовательскому ключу. Параметр consistent минимизирует перераспределение при добавлении или удалении серверов.

nginx
# round-robin (default) - even distribution
upstream backend {
    server s1.example.com;
    server s2.example.com;
}

# least connections - fewest active connections
upstream backend {
    least_conn;
    server s1.example.com;
    server s2.example.com;
}

# ip_hash - sticky by client IP (session persistence)
upstream backend {
    ip_hash;
    server s1.example.com;
    server s2.example.com;
}

# generic hash (key-based, e.g., by URI or header)
upstream backend {
    hash $request_uri consistent;
    server s1.example.com;
    server s2.example.com;
}

Взвешенный round-robin

weight пропорционально управляет распределением трафика. Вес по умолчанию — 1. Ставьте больший вес более мощным серверам, чтобы они брали большую долю. Веса работают с round-robin, least_conn и ip_hash.

nginx
upstream backend {
    server s1.example.com weight=3;  # 3x traffic
    server s2.example.com weight=2;  # 2x traffic
    server s3.example.com weight=1;  # 1x traffic (default)
}

# total weight = 6
# s1 gets 3/6 = 50%, s2 gets 2/6 = 33%, s3 gets 1/6 = 17%

# useful when servers have different capacity
# e.g., a 4-core server gets weight=4, a 2-core gets weight=2

Проверки здоровья

Открытый nginx использует пассивные проверки здоровья (max_fails/fail_timeout) по реальным отказам запросов. NGINX Plus добавляет активные проверки, периодически опрашивающие URI. Сервер должен пройти 'passes' проверок подряд, чтобы снова считаться здоровым.

nginx
upstream backend {
    server s1.example.com max_fails=3 fail_timeout=30s;
    server s2.example.com max_fails=3 fail_timeout=30s;

    # passive health check (default behavior):
    # 3 failures within 30s marks the server down
    # it stays down for fail_timeout (30s) before retry
}

# NGINX Plus active health check
upstream backend {
    server s1.example.com;
    server s2.example.com;
    health_check interval=10s fails=3 passes=2;
    health_check uri=/health;
}

Сохранение сессий

ip_hash обеспечивает липкие сессии по IP клиента, но ломается при смене IP (мобильные сети). Директива hash с consistent даёт минимальное перераспределение ключей при изменении пула. sticky cookie (Plus) устанавливает cookie, закрепляя клиента за сервером.

nginx
# ip_hash: routes by client IP (uses first 3 IPv4 octets)
upstream backend {
    ip_hash;
    server s1.example.com:8080;
    server s2.example.com:8080;
}

# sticky cookie (NGINX Plus only)
upstream backend {
    sticky cookie srv_id expires=1h domain=.example.com path=/;
    server s1.example.com;
    server s2.example.com;
}

# hash with consistent parameter for minimal redistribution
upstream backend {
    hash $http_x_session_id consistent;
    server s1.example.com;
    server s2.example.com;
}

Резервные серверы

Помеченные параметром backup серверы получают трафик, только когда все основные серверы отказали. Частый паттерн: основные обслуживают приложение, резервный отдаёт статическую страницу обслуживания. Резервные серверы исключены из обычной балансировки нагрузки.

nginx
upstream backend {
    server s1.example.com;
    server s2.example.com;

    # used only when all primaries are down
    server s3.example.com backup;
    server s4.example.com backup;
}

# backup servers receive traffic ONLY when all
# non-backup servers are unavailable
# useful for a maintenance page or DR fallback

upstream backend {
    server primary.example.com;
    server standby.example.com backup;
}
06

Настройка SSL/TLS

Базовый HTTPS-сервер

Параметр ssl в listen включает TLS. ssl_certificate указывает на цепочку сертификатов (сертификат сервера + промежуточные), ssl_certificate_key — на приватный ключ. Всегда используйте fullchain.pem, чтобы клиенты могли проверить цепочку.

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

    ssl_certificate     /etc/ssl/certs/example.com.crt;
    ssl_certificate_key /etc/ssl/private/example.com.key;

    root /var/www/html;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

Настройка SSL-сертификата

Let's Encrypt хранит сертификаты в /etc/letsencrypt/live/<domain>/. fullchain.pem включает промежуточные сертификаты; privkey.pem — приватный ключ. nginx поддерживает несколько типов сертификатов на сервер, выбирая по возможностям клиента.

nginx
# Let's Encrypt paths
ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

# multiple cert types (RSA + ECDSA) on one server
server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate     /etc/ssl/example.com.rsa.crt;
    ssl_certificate_key /etc/ssl/example.com.rsa.key;

    ssl_certificate     /etc/ssl/example.com.ecdsa.crt;
    ssl_certificate_key /etc/ssl/example.com.ecdsa.key;
}

Редирект с HTTP на HTTPS

Самый чистый паттерн — отдельный сервер на порту 80, который делает редирект. $host сохраняет исходное имя хоста. Использование if ($scheme) в объединённом блоке работает, но подход с отдельным сервером предпочтительнее и избегает ловушек «if is evil».

nginx
# redirect all HTTP traffic to HTTPS
server {
    listen 80;
    server_name example.com www.example.com;
    return 301 https://$host$request_uri;
}

# single server block handling both
server {
    listen 80;
    listen 443 ssl;
    server_name example.com;

    ssl_certificate     /etc/ssl/example.com.crt;
    ssl_certificate_key /etc/ssl/example.com.key;

    if ($scheme != "https") {
        return 301 https://$host$request_uri;
    }
}

Протоколы и шифры SSL

Отключите устаревшие протоколы (SSLv3, TLSv1.0/1.1). TLS 1.3 — самый быстрый и безопасный. Используйте Mozilla SSL Configuration Generator для проверенного профиля. shared:SSL ускоряет возобновление сессий между воркерами.

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

    ssl_certificate     /etc/ssl/example.com.crt;
    ssl_certificate_key /etc/ssl/example.com.key;

    # modern configuration (Mozilla SSL Config Generator)
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;

    # session settings
    ssl_session_tickets off;
    ssl_session_timeout 1d;
    ssl_session_cache shared:SSL:50m;
}

HSTS

HSTS говорит браузерам всегда использовать HTTPS для домена, предотвращая атаки SSL-stripping. max-age задаётся в секундах (31536000 = 1 год). includeSubDomains охватывает все поддомены. preload добавляет сайт во встроенный список браузеров — практически необратимо, используйте осторожно.

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

    # HSTS: force HTTPS for 1 year (include subdomains)
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    # preload list (be very careful — requires permanent HTTPS)
    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
}

# Preload commits your domain to a browser-baked HTTPS-only list.
# Only enable preload after verifying all subdomains work on HTTPS.

OCSP Stapling

OCSP stapling позволяет nginx получать и отдавать статус отзыва сертификата, экономя клиенту сетевой обход к OCSP-респондеру. ssl_trusted_certificate нужен для проверки ответа OCSP. Для доступа к OCSP-серверу требуется resolver.

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

    ssl_certificate     /etc/ssl/example.com/fullchain.pem;
    ssl_certificate_key /etc/ssl/example.com/privkey.pem;

    ssl_stapling on;
    ssl_stapling_verify on;

    # trust chain for verification
    ssl_trusted_certificate /etc/ssl/example.com/chain.pem;

    # DNS resolver needed for OCSP requests
    resolver 8.8.8.8 8.8.4.4 valid=300s;
    resolver_timeout 5s;
}
07

Раздача статики

Раздача статических файлов

root задаёт корень документов; nginx отображает URI запроса в путь к файлу. try_files проверяет файл, затем каталог, затем возвращает 404. Задание root на уровне server позволяет всем location унаследовать его, но можно переопределить в каждом location.

nginx
server {
    listen 80;
    server_name example.com;
    root /var/www/html;

    location / {
        try_files $uri $uri/ =404;
    }
}

# root set at server level is inherited by all locations
# request /images/logo.png -> /var/www/html/images/logo.png
# request /css/style.css   -> /var/www/html/css/style.css

Директива index

index перечисляет файлы, которые нужно попробовать, когда запрошен каталог. Отдаётся первый существующий файл. Если ни одного нет и autoindex выключен, nginx возвращает 403. Порядок важен — предпочитаемые файлы указывайте первыми.

nginx
server {
    listen 80;
    root /var/www/html;

    # try these files in order when request targets a directory
    index index.html index.htm index.php;

    location / {
        try_files $uri $uri/ =404;
    }
}

# request / -> tries /var/www/html/index.html, then index.htm
# request /about/ -> tries /var/www/html/about/index.html
# if no index file found and autoindex off -> 403 Forbidden

try_files для SPA

SPA используют клиентскую маршрутизацию, поэтому неизвестные пути должны отдавать index.html. try_files $uri $uri/ /index.html делает именно это. Кешируйте хешированные ресурсы на год с immutable: имена на основе содержимого гарантируют новый URL при изменении содержимого.

nginx
# Single Page Application (React, Vue, Angular)
server {
    listen 80;
    root /var/www/spa;

    location / {
        # serve static files, fall back to index.html for client routing
        try_files $uri $uri/ /index.html;
    }

    # cache static assets aggressively (filename usually hashed)
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

Autoindex (листинг каталога)

autoindex генерирует HTML-листинг каталога. Полезно для сайтов с файлами. Отключите exact_size для читаемости и включите localtime для правильных меток времени. Никогда не включайте в каталогах с чувствительными файлами — всегда сочетайте с контролем доступа.

nginx
location /files/ {
    autoindex on;
    autoindex_exact_size off;  # human-readable sizes (KB, MB)
    autoindex_localtime on;    # show local time instead of UTC
    root /var/www;
}

# /files/        -> directory listing
# /files/doc.pdf -> downloads the file
# /files/sub/    -> listing of subdirectory

# disable for security on sensitive directories
location /private/ {
    autoindex off;
    deny all;
}

Заголовки expires

expires задаёт max-age в Cache-Control. immutable сообщает браузерам, что файл никогда не меняется (без повторной проверки). Для хешированных ресурсов (file.abc123.js) идеально 1y + immutable. HTML должен всегда ревалидироваться, чтобы пользователи сразу получали обновления.

nginx
# cache static assets for a year
location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
    access_log off;
}

# never cache HTML (always revalidate)
location ~* \.html$ {
    add_header Cache-Control "no-cache, no-store, must-revalidate";
}

# short cache for API responses
location /api/ {
    add_header Cache-Control "no-cache";
}

Отключение логов для статики

Запросы статических ресурсов, favicon и robots засоряют access-логи. access_log off останавливает логирование; log_not_found off подавляет записи о 404. Это держит логи сфокусированными на значимом трафике и снижает нагрузку на диск на загруженных сайтах.

nginx
# don't log requests for static assets
location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ {
    access_log off;
    log_not_found off;
    expires 1y;
}

# don't log favicon requests (often 404 from browsers)
location = /favicon.ico {
    log_not_found off;
    access_log off;
}

# don't log robots.txt
location = /robots.txt {
    log_not_found off;
    access_log off;
}
08

Сжатие Gzip

Включение Gzip

gzip сжимает ответы, снижая трафик. gzip_vary добавляет 'Vary: Accept-Encoding' для кешей. gzip_proxied any сжимает проксируемые запросы. comp_level 6 балансирует CPU и размер. min_length 256 пропускает крошечные ответы (накладные расходы больше выигрыша).

nginx
http {
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_min_length 256;
    gzip_types
        text/plain
        text/css
        text/xml
        application/json
        application/javascript
        application/xml+rss
        application/atom+xml
        image/svg+xml;
}

Типы для Gzip

gzip_types перечисляет MIME-типы для сжатия. text/html сжимается всегда по умолчанию. Не сжимайте двоичные форматы, которые уже сжаты (изображения, видео, архивы): вы тратите CPU без выигрыша в размере и можете даже увеличить вывод.

nginx
http {
    gzip on;
    gzip_types
        text/plain
        text/css
        text/xml
        text/javascript
        application/javascript
        application/x-javascript
        application/json
        application/xml
        application/xml+rss
        application/rss+xml
        application/atom+xml
        image/svg+xml
        font/ttf
        font/otf
        application/vnd.ms-fontobject;

    # text/html is always compressed (implicitly, cannot disable)
    # DON'T compress already-compressed: jpg, png, gif, mp4, zip, gz
}

Уровень сжатия Gzip

comp_level обменивает CPU на сжатие. 6 — оптимальная точка: 9 тратит гораздо больше CPU ради <2% меньшего результата. min_length избегает сжатия крошечных ответов, где накладные расходы заголовка gzip превышают экономию. gzip_disable исключает устаревший IE6 со сломанной поддержкой gzip.

nginx
http {
    gzip on;
    gzip_comp_level 6;  # 1-9, higher = more compression, more CPU

    # level 1: fast, low compression
    # level 6: good balance (recommended default)
    # level 9: slow, marginal size gain

    # minimum response size to compress (bytes)
    gzip_min_length 256;

    # disable gzip for old browsers
    gzip_disable "MSIE [1-6]\.";
}

Gzip Static

gzip_static отдаёт заранее собранные .gz-файлы, исключая затраты CPU на сжатие во время работы. Шаг сборки создаёт .gz рядом с оригиналами. nginx отдаёт .gz клиентам с Accept-Encoding: gzip, остальным — оригинал. Идеально для конвейеров статических ресурсов.

nginx
# serve pre-compressed .gz files (no runtime compression cost)
# requires ngx_http_gzip_static_module

location / {
    gzip_static on;
    # on:     serve .gz if it exists
    # always: serve .gz even without Accept-Encoding header

    root /var/www/html;
}

# pre-compress files at build time:
# find /var/www/html -type f ( -name "*.css" -o -name "*.js" \
#   -o -name "*.html" ) -exec gzip -k -9 {} \;
# creates file.css.gz, file.js.gz alongside the originals

Brotli

Brotli превосходит gzip для текстового контента, особенно на высоких уровнях сжатия. Требуется сторонний модуль ngx_brotli. brotli_static отдаёт заранее собранные .br-файлы. Современные браузеры указывают 'br' в Accept-Encoding, поэтому nginx выбирает лучший доступный вариант.

nginx
# requires ngx_brotli module (not built-in)
http {
    brotli on;
    brotli_comp_level 6;
    brotli_types
        text/plain
        text/css
        application/javascript
        application/json
        image/svg+xml;

    # serve pre-compressed .br files
    brotli_static on;
}

# Brotli typically 10-20% smaller than gzip for text
# supported by all modern browsers (not IE)
# nginx can serve both .br and .gz; picks based on Accept-Encoding

Сжатие проксируемых ответов

По умолчанию nginx не сжимает проксируемые ответы (чтобы не сжимать дважды уже сжатые upstream). gzip_proxied any включает это для всех проксируемых запросов. gzip_vary гарантирует, что кеши хранят отдельные версии для сжатых и несжатых клиентов.

nginx
http {
    gzip on;
    gzip_proxied any;
    # gzip_proxied controls compression for proxied requests:
    # off:           never compress proxied requests
    # expired:       compress if response has Expires header
    # no-cache:      compress if Cache-Control: no-cache
    # no-store:      compress if Cache-Control: no-store
    # private:       compress if Cache-Control: private
    # no_last_modified: compress if no Last-Modified header
    # no_etag:       compress if no ETag header
    # auth:          compress if Authorization header present
    # any:           compress all proxied requests

    gzip_vary on;  # add "Vary: Accept-Encoding" header
}
09

Кеширование

Кеш прокси

proxy_cache сохраняет ответы upstream на диске. keys_zone определяет разделяемую область памяти для ключей кеша (10m ~= 80 000 ключей). max_size ограничивает место на диске; inactive удаляет записи, к которым не обращались указанное время. use_temp_path=off пишет прямо в кеш ради скорости.

nginx
http {
    # define cache zone on disk
    proxy_cache_path /var/cache/nginx levels=1:2
        keys_zone=api_cache:10m
        max_size=1g
        inactive=60m
        use_temp_path=off;

    server {
        location /api/ {
            proxy_pass http://backend;
            proxy_cache api_cache;
            proxy_cache_valid 200 10m;
            proxy_cache_valid 404 1m;
        }
    }
}

Зона кеша

levels=1:2 создаёт двухуровневое дерево каталогов из MD5-хеша ключа кеша, чтобы не держать слишком много файлов в одном каталоге. Отдельные зоны по типам контента позволяют независимо настраивать max_size и inactive: статика кешируется дольше, API — ненадолго.

nginx
http {
    proxy_cache_path /var/cache/nginx
        levels=1:2              # directory hierarchy depth
        keys_zone=my_cache:10m  # zone name + shared memory size
        max_size=1g             # max disk size for cache
        inactive=60m            # remove if not accessed in 60min
        use_temp_path=off;      # write directly (faster, no temp copy)

    # multiple zones for different content types
    proxy_cache_path /var/cache/static levels=1:2
        keys_zone=static:10m max_size=500m inactive=24h;
    proxy_cache_path /var/cache/api levels=1:2
        keys_zone=api:10m max_size=200m inactive=10m;
}

Ключ кеша

Ключ кеша определяет уникальность записи. Ключ по умолчанию может вызывать коллизии между виртуальными хостами — включайте $host. Для контента под пользователя включайте идентификатор пользователя. proxy_cache_bypass пропускает чтение кеша (но всё равно сохраняет); proxy_no_cache не сохраняет ответ.

nginx
location / {
    proxy_pass http://backend;
    proxy_cache api_cache;

    # default key: $scheme$proxy_host$request_uri
    proxy_cache_key "$scheme$request_method$host$request_uri";

    # include user-specific data to avoid cross-user leaks
    proxy_cache_key "$scheme$host$request_uri$http_x_user_id";

    # bypass cache for authenticated users
    proxy_cache_bypass $http_authorization;
    proxy_no_cache $http_authorization;
}

Срок жизни кеша

proxy_cache_valid задаёт TTL для каждого кода статуса. 0s или отсутствие статуса запрещает его кеширование. proxy_cache_lock сериализует одновременные промахи по одному ключу: только один запрос идёт к upstream, остальные ждут закешированного ответа.

nginx
location / {
    proxy_pass http://backend;
    proxy_cache api_cache;

    # cache by response status code
    proxy_cache_valid 200 302 10m;
    proxy_cache_valid 404 1m;
    proxy_cache_valid 500 502 503 504 0s;  # don't cache errors

    # fallback for any other status
    proxy_cache_valid any 1m;

    # cache lock: collapse concurrent misses into one upstream call
    proxy_cache_lock on;
    proxy_cache_lock_timeout 5s;
}

Обход кеша

proxy_cache_bypass пропускает чтение кеша (идёт к upstream), но всё равно может сохранить ответ. proxy_no_cache пропускает сохранение. Заголовок X-Cache-Status бесценен для отладки: HIT означает ответ из кеша, MISS — получен от upstream.

nginx
location / {
    proxy_pass http://backend;
    proxy_cache api_cache;

    # bypass cache (always go to upstream)
    proxy_cache_bypass $http_authorization $arg_nocache;

    # don't store in cache
    proxy_no_cache $http_authorization;

    # add header showing cache status for debugging
    add_header X-Cache-Status $upstream_cache_status;
}

# $upstream_cache_status values:
# MISS, BYPASS, EXPIRED, STALE, UPDATING, REVALIDATED, HIT

Кеширование в браузере

Кеширование в браузере сокращает задержку повторных визитов. immutable полностью пропускает ревалидацию (безопасно только для имён на основе содержимого). no-cache означает ревалидацию каждый раз (условный GET всё же разрешён). no-store означает никогда не сохранять. Сочетайте с ETag для эффективных ответов 304.

nginx
# cache static assets in the browser
location ~* \.(jpg|jpeg|png|gif|ico|css|js|woff2?)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

# HTML - revalidate always
location ~* \.html$ {
    add_header Cache-Control "no-cache, must-revalidate";
    etag on;
}

# API responses - never cache
location /api/ {
    add_header Cache-Control "no-store";
}

# public:    any cache (browser, CDN) may store
# private:   only the browser may store
# immutable: file never changes, skip revalidation
# no-store:  never cache
10

Переписывание URL

Директива return

return — простейший способ сделать редирект или ответить. Он немедленно прекращает обработку. Используйте 301 для постоянных и 302 для временных редиректов. Можно вернуть код статуса с телом (200, 418) или редирект на URL. Для редиректов предпочитайте return, а не rewrite.

nginx
# simplest redirect/rewrite - return stops processing
server {
    location /old {
        return 301 /new;
    }

    location /external {
        return 301 https://example.com$request_uri;
    }

    location /api {
        return 200 "OK\n";
    }

    location /teapot {
        return 418 "I'm a teapot";
    }
}

# return is preferred over rewrite for simple redirects

Директива rewrite

rewrite сопоставляет URI с regex и заменяет его. last заново запускает сопоставление location с новым URI (как будто всё начинается сначала). break прекращает переписывание, но остаётся в текущем location. redirect/permanent отправляют редирект в браузер.

nginx
# rewrite regex replacement [flag]
server {
    # rewrite /old/* to /new/* preserving the captured part
    rewrite ^/old/(.*)$ /new/$1 permanent;

    # rewrite old blog URLs to new structure
    rewrite ^/blog/(\d{4})/(\d{2})/(.*)$ /articles/$1/$2/$3 last;

    # capture with named groups
    rewrite ^/download/(.*)$ /assets/$1 last;
}

# flags:
# last:      re-search locations with the new URI
# break:     stop rewrite, continue in current location
# redirect:  302 temporary redirect
# permanent: 301 permanent redirect

Флаги rewrite

last против break — самая путаная часть. last повторяет поиск location (полезно, когда rewrite нацелен на другой location). break прекращает переписывание, но остаётся на месте (полезно, когда rewrite лишь корректирует внутренний путь). redirect/permanent меняют URL в браузере.

nginx
location / {
    # last: restart location matching with new URI
    rewrite ^/api/(.*)$ /backend/$1 last;

    # break: stop processing rewrites, stay in current location
    rewrite ^/static/(.*)$ /assets/$1 break;

    # redirect: 302 temporary redirect (browser URL changes)
    rewrite ^/old/(.*)$ /new/$1 redirect;

    # permanent: 301 permanent redirect (browser URL changes)
    rewrite ^/old/(.*)$ /new/$1 permanent;
}

# avoid rewrite inside if blocks - use location + try_files instead

Именованные захваты

Именованные захваты (?<name>pattern) создают переменные ($name), которые понятнее позиционных $1, $2. Они работают и в regex location, и в rewrite. Захваченные значения доступны в proxy_pass, fastcgi_param, add_header и log_format внутри этого location.

nginx
# named captures in regex locations
location ~ ^/users/(?<username>[a-z]+)/?$ {
    proxy_pass http://backend/users/$username;
}

# named captures in rewrite
location / {
    rewrite ^/articles/(?<year>\d{4})/(?<slug>[a-z-]+)/?$
        /blog?year=$year&slug=$slug last;
}

# named captures become variables: $year, $slug, $username
# accessible in proxy_pass, fastcgi_pass, headers, etc.
# safer than $1, $2 positional captures for readability

Директива map

map строит таблицу соответствия одной переменной другой, вычисляемую лениво. Это гораздо эффективнее и читаемее цепочек if. Ветка default обрабатывает несовпавшие значения. Regex-совпадения (с префиксом ~) проверяются по порядку.

nginx
# map creates a new variable based on another variable's value
map $http_host $backend {
    default            "http://default.backend";
    "a.com"            "http://a.backend";
    "b.com"            "http://b.backend";
    "~^.*\.app\.com$" "http://app.backend";
}

server {
    server_name a.com b.com;
    location / {
        proxy_pass $backend;
    }
}

# map is evaluated lazily and cached per request
# more efficient than if/else chains

Директива if (осторожно)

if ведёт себя неожиданно внутри блоков location: он может непредсказуемо переписывать конфигурацию. Универсально безопасны только return и rewrite. Для проверки существования файлов используйте try_files. Для сложной логики — map или отдельные location. См. wiki: «If Is Evil».

nginx
# "if is evil" — use sparingly! Only safe for:
# return / rewrite, and with these checks:
#   -f, -d, -e, -x (file/dir/exists/executable)
#   =, !=, ~, ~* (string/regex comparison)

location / {
    if ($request_method = POST) {
        return 405;
    }

    if ($http_user_agent ~* "bot") {
        return 403;
    }

    # BAD: don't do this inside if
    # if (-f $request_filename) { ... }
    # use try_files instead
    try_files $uri $uri/ /index.html;
}
11

Редиректы

Постоянный редирект (301)

301 означает «перемещено навсегда»: браузеры и поисковые системы его кешируют, поэтому используйте только для действительно постоянных изменений. Сначала тестируйте редиректы через 302, чтобы не зафиксировать ошибку. 301 передаёт ссылочный вес (SEO) на новый URL.

nginx
# 301 - permanent redirect (cached by browsers indefinitely)
server {
    listen 80;
    server_name old-domain.com;

    # redirect entire site to a new domain
    return 301 https://new-domain.com$request_uri;
}

location /old-page {
    return 301 /new-page;
}

# 301 caches indefinitely in browsers — test with 302 first!
# Search engines treat 301 as a permanent move and update indexes.

Временный редирект (302)

302 меняет POST на GET при редиректе (историческое поведение). 307 и 308 сохраняют метод — важно при повторной отправке POST. 303 явно преобразует в GET (полезно после отправки формы, чтобы избежать двойной отправки при обновлении). Выбирайте по тому, нужно ли сохранять метод.

nginx
# 302 - temporary redirect (not cached by default)
location /maintenance {
    return 302 /maintenance.html;
}

# 307 - temporary, preserves HTTP method (POST stays POST)
location /api/v1 {
    return 307 /api/v2;
}

# 308 - permanent, preserves HTTP method
location /api/v1 {
    return 308 /api/v2;
}

# 303 - see other (always uses GET for the new request)
location /form-submit {
    return 303 /success;
}

Редирект с www на без www

Выберите одну каноническую форму (с www или без) и перенаправляйте другую. Два блока server — самый чистый паттерн: неканонический только перенаправляет. $request_uri сохраняет путь и строку запроса. Та же логика применяется к редиректам на HTTPS.

nginx
# www to non-www
server {
    listen 80;
    server_name www.example.com;
    return 301 https://example.com$request_uri;
}

server {
    listen 80;
    server_name example.com;
    # ... main site config
}

# non-www to www (reverse direction)
server {
    listen 80;
    server_name example.com;
    return 301 https://www.example.com$request_uri;
}

Редирект с HTTP на HTTPS

$host сохраняет исходное имя хоста, поэтому редирект работает для любого server_name. $request_uri сохраняет путь и запрос. Для нестандартных портов добавьте :port к $host. Отдельный блок server на порту 80 чище, чем проверки if в каждом location.

nginx
server {
    listen 80;
    server_name example.com www.example.com;
    return 301 https://$host$request_uri;
}

# with a non-standard HTTPS port
server {
    listen 8080;
    return 301 https://$host:8443$request_uri;
}

# redirect only a specific path
location /secure {
    if ($scheme = http) {
        return 301 https://$host$request_uri;
    }
}

Редирект на другой домен

При миграции домена $request_uri сохраняет полный путь и запрос, чтобы ссылки не ломались. Используйте rewrite с захватом, когда меняется структура пути. 301 верен для постоянных миграций: он передаёт SEO-рейтинг новому домену.

nginx
# domain migration — preserve all paths
server {
    listen 80;
    server_name old.com www.old.com;
    return 301 https://new.com$request_uri;
}

# preserve path and query string
location /docs/ {
    return 301 https://docs.new.com$request_uri;
}

# with path rewrite using capture groups
location /old-blog/ {
    rewrite ^/old-blog/(.*)$ https://blog.new.com/$1 permanent;
}

Редиректы по пути

Редиректы по пути полезны для чистки URL (удаление завершающих слэшей, расширений файлов) и переноса контента. Regex-location с захватами ($1) позволяют гибко переписывать пути. Редиректы по параметрам запроса используют $arg_name для чтения отдельных параметров.

nginx
# redirect specific paths
location /promo/2023 {
    return 301 /promo/2024;
}

# remove trailing slash
location ~ ^/(.*)/$ {
    return 301 /$1;
}

# remove .html extension
location ~ ^/(.*)\.html$ {
    return 301 /$1;
}

# redirect based on query parameter
location /download {
    if ($arg_version = "1") {
        return 301 /download?v=2;
    }
}
12

FastCGI (PHP-FPM)

Базовая настройка PHP-FPM

fastcgi_pass отправляет PHP-запросы в PHP-FPM через UNIX-сокет (быстрее, только локально) или TCP-порт. include fastcgi_params задаёт стандартные переменные CGI. SCRIPT_FILENAME сообщает PHP, какой файл выполнять, — он объединяет корень документов с путём к скрипту.

nginx
server {
    listen 80;
    server_name example.com;
    root /var/www/laravel/public;
    index index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        # or: fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}

Параметры FastCGI

fastcgi_params задаёт переменные окружения, передаваемые в PHP. SCRIPT_FILENAME — важнейшая из них: без неё PHP не найдёт скрипт. Пользовательские параметры (APP_ENV, DB_HOST) позволяют внедрять конфигурацию, не меняя приложение. PATH_INFO включает чистые URL в некоторых фреймворках.

nginx
location ~ \.php$ {
    fastcgi_pass unix:/run/php/php-fpm.sock;

    # standard CGI parameters
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param PATH_INFO $fastcgi_path_info;

    # custom application parameters
    fastcgi_param APP_ENV production;
    fastcgi_param DB_HOST db.internal;

    # flag for HTTPS (so PHP knows the original scheme)
    fastcgi_param HTTPS $https_flag;
}

Кеш FastCGI

fastcgi_cache сохраняет ответы PHP, резко снижая нагрузку для кешируемых страниц. fastcgi_cache_use_stale отдаёт устаревший закешированный ответ, если бэкенд ошибается или не отвечает, — повышает устойчивость. Осторожно: не кешируйте контент под пользователя или аутентифицированные страницы.

nginx
http {
    fastcgi_cache_path /var/cache/nginx/php
        levels=1:2
        keys_zone=phpcache:100m
        max_size=1g
        inactive=60m;

    server {
        location ~ \.php$ {
            fastcgi_pass unix:/run/php/php-fpm.sock;
            include fastcgi_params;
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

            fastcgi_cache phpcache;
            fastcgi_cache_valid 200 10m;
            fastcgi_cache_key $scheme$host$request_uri;
            fastcgi_cache_use_stale error timeout invalid_header;
        }
    }
}

Буферы FastCGI

Буферы держат ответ PHP перед отправкой клиенту. Маленькие буферы заставляют nginx писать на диск (медленно) для больших ответов. Если вы видите ошибки 'upstream sent too big header', увеличьте fastcgi_buffer_size. Для больших ответов API используйте буферы побольше и поменьше числом.

nginx
location ~ \.php$ {
    fastcgi_pass unix:/run/php/php-fpm.sock;

    # buffer settings
    fastcgi_buffering on;
    fastcgi_buffer_size 16k;
    fastcgi_buffers 16 16k;
    fastcgi_busy_buffers_size 32k;

    # for large responses (e.g., PHP generating big JSON)
    fastcgi_buffers 64 16k;
    fastcgi_buffer_size 32k;

    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

Таймауты FastCGI

fastcgi_read_timeout — сколько nginx ждёт, пока PHP выдаст вывод. Долгим скриптам (импорт данных, генерация отчётов, вызовы ИИ) нужно большее значение. Убедитесь, что max_execution_time в PHP не меньше, иначе PHP оборвётся первым.

nginx
location ~ \.php$ {
    fastcgi_pass unix:/run/php/php-fpm.sock;

    fastcgi_connect_timeout 5s;
    fastcgi_read_timeout 300s;    # for long-running scripts
    fastcgi_send_timeout 300s;

    # increase for very slow PHP scripts (imports, exports, reports)
    fastcgi_read_timeout 600s;
}

# also adjust max_execution_time in php.ini to match
# otherwise PHP kills the script before nginx times out

try_files с PHP

try_files $uri $uri/ /index.php?$args — стандартный паттерн для PHP-фреймворков (WordPress, Laravel, Drupal). Он отдаёт реальные файлы и каталоги, иначе направляет в index.php со строкой запроса. $args сохраняет исходные параметры запроса.

nginx
# WordPress-style pretty URLs
server {
    root /var/www/wordpress;

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

    # deny access to sensitive files
    location ~* /wp-config.php {
        deny all;
    }
}
13

Прокси WebSocket

Прокси WebSocket

WebSocket требует HTTP/1.1 плюс заголовки Upgrade и Connection. Блок map преобразует заголовок Upgrade клиента в правильное значение Connection: 'upgrade' для WebSocket, 'close' для обычного HTTP. Большой read_timeout держит простаивающие WebSocket-соединения живыми.

nginx
# Map the Upgrade header to a Connection value
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    server_name ws.example.com;

    location / {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        proxy_read_timeout 3600s;  # 1 hour
        proxy_send_timeout 3600s;
    }
}

Заголовки Upgrade

HTTP/1.1 обязателен для WebSocket (HTTP/2 управляет мультиплексированием иначе). Connection можно жёстко задать как 'upgrade', но подход с переменной map также обрабатывает обычные запросы в том же location. Передавайте Host, чтобы бэкенд мог проверить заголовок Origin.

nginx
location /ws {
    proxy_pass http://backend;

    # HTTP/1.1 is required for the Upgrade mechanism
    proxy_http_version 1.1;

    # pass the Upgrade header through
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    # preserve host for origin checks on the backend
    proxy_set_header Host $host;

    # real client IP
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

Таймаут WebSocket

proxy_read_timeout по умолчанию (60 с) закрывает простаивающие WebSocket-соединения. Ставьте его большим (86400 с = 24 ч), чтобы соединения жили между сообщениями. proxy_buffering off гарантирует, что сообщения доходят до клиента сразу, а не пачками.

nginx
location /ws {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;

    # WebSocket connections are long-lived
    # default 60s would close them during idle periods
    proxy_read_timeout 86400s;  # 24 hours
    proxy_send_timeout 86400s;

    # disable buffering for real-time messages
    proxy_buffering off;
}

Прокси Socket.io

Socket.io начинает с HTTP long-polling, затем переключается на WebSocket, если он доступен. Оба транспорта идут через один proxy_pass, поэтому один location обрабатывает всё. Передача X-Forwarded-Proto сообщает socket.io, что он за HTTPS, и тот строит правильные URL.

nginx
server {
    listen 80;
    server_name socket.example.com;

    location / {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;

        proxy_read_timeout 86400s;

        # socket.io needs these for correct client IP and scheme
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# socket.io uses both polling (HTTP) and WebSocket transports
# both are handled by the proxy_pass above

Несколько WebSocket-путей

Разные WebSocket-сервисы можно маршрутизировать по пути к разным бэкендам. Каждому location нужны одинаковые заголовки upgrade. Блок map определяется один раз на уровне http и переиспользуется. Настраивайте read_timeout под сервис: чат может быть активен часто, уведомления — простаивать часами.

nginx
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;

    # chat application
    location /ws/chat/ {
        proxy_pass http://chat_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_read_timeout 3600s;
    }

    # notifications service
    location /ws/notify/ {
        proxy_pass http://notify_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_read_timeout 86400s;
    }
}

WSS (защищённый WebSocket)

WSS — это WebSocket поверх TLS. nginx терминирует TLS (обрабатывает сертификат) и проксирует обычный WebSocket на бэкенд. Бэкенду не нужна настройка TLS. Это стандартная продакшен-схема: браузеры требуют WSS для HTTPS-страниц (правила смешанного контента).

nginx
server {
    listen 443 ssl;
    server_name ws.example.com;

    ssl_certificate     /etc/ssl/ws.example.com.crt;
    ssl_certificate_key /etc/ssl/ws.example.com.key;

    location / {
        proxy_pass http://backend:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 86400s;
    }
}

# browser connects with wss://ws.example.com
# nginx terminates TLS, proxies plain WebSocket to the backend
14

Заголовки безопасности

X-Frame-Options

X-Frame-Options не даёт встраивать ваш сайт в iframe, блокируя кликджекинг. SAMEORIGIN разрешает вашим страницам встраивать сами себя. Современная замена — CSP frame-ancestors, он гибче. always гарантирует отправку заголовка и в ответах с ошибками.

nginx
# prevent clickjacking (your site embedded in an iframe)
add_header X-Frame-Options "SAMEORIGIN" always;

# options:
# DENY          - no framing at all
# SAMEORIGIN    - only same-site can frame
# ALLOW-FROM    - deprecated, use CSP frame-ancestors instead

# modern equivalent via Content-Security-Policy
add_header Content-Security-Policy "frame-ancestors 'self'" always;

X-Content-Type-Options

nosniff велит браузерам доверять заголовку Content-Type и не «сниффить» содержимое. Без него браузер может выполнить загруженное изображение как HTML, если обнаружит в нём HTML. Это дешёвый и очень полезный заголовок — включайте всегда.

nginx
# prevent MIME-type sniffing
add_header X-Content-Type-Options "nosniff" always;

# forces the browser to respect the declared Content-Type
# prevents XSS via uploaded files (e.g., an image containing HTML
# being executed as a script)

# related: block Adobe Flash / PDF cross-domain policies
add_header X-Permitted-Cross-Domain-Policies "none" always;

Content-Security-Policy

CSP — самая мощная защита от XSS: он задаёт белый список разрешённых источников для скриптов, стилей, изображений и т. д. Начните с Report-Only, чтобы найти нарушения, ничего не ломая, затем включите принудительно. 'self' означает тот же источник; 'unsafe-inline' разрешает встроенные скрипты и стили (нужно многим приложениям).

nginx
# strict CSP — restricts where resources can load from
add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' https://fonts.gstatic.com; connect-src 'self' https://api.example.com; frame-ancestors 'none'; base-uri 'none'; form-action 'self'" always;

# report-only mode (logs violations without blocking)
add_header Content-Security-Policy-Report-Only "default-src 'self'; report-uri /csp-report" always;

X-XSS-Protection

X-XSS-Protection включал встроенный фильтр отражённого XSS в браузере. Современные браузеры удалили эту функцию в пользу CSP. Режим mode=block предотвращал «санитизацию» (которая могла создавать новые уязвимости) и просто блокировал страницу. Безвреден для старых браузеров, но настоящая защита — CSP.

nginx
# legacy XSS auditor (older browsers)
add_header X-XSS-Protection "1; mode=block" always;

# values:
# 0              - disable the filter
# 1              - enable (sanitize)
# 1; mode=block  - enable and block the page entirely

# NOTE: deprecated in modern browsers (Chrome, Edge, Safari removed it)
# CSP is the modern replacement, but this doesn't hurt to include
# for legacy browser support

Referrer-Policy

Referrer-Policy управляет тем, сколько информации об URL утекает через заголовок Referer при переходе по ссылкам. strict-origin-when-cross-origin (значение по умолчанию в браузерах) отправляет полный URL для запросов того же источника, только origin для кросс-доменных и ничего при переходе на HTTP.

nginx
# control what the Referer header contains
add_header Referrer-Policy "strict-origin-when-cross-origin" always;

# options:
# no-referrer                  - never send Referer
# no-referrer-when-downgrade   - default; no Referer on HTTPS->HTTP
# same-origin                  - only same-site
# origin                       - send only scheme+host
# strict-origin                - origin, but not on downgrade
# origin-when-cross-origin     - full for same, origin for cross
# strict-origin-when-cross-origin - recommended default
# unsafe-url                   - send full URL (not recommended)

Permissions-Policy

Permissions-Policy позволяет отключить функции браузера (камера, микрофон, геолокация и т. д.), даже если страница их запрашивает. Пустые скобки () полностью отключают функцию. Это ограничивает радиус поражения при XSS: скомпрометированный скрипт не включит камеру, если политика запрещает.

nginx
# control which browser features the page can use
# (formerly Feature-Policy)
add_header Permissions-Policy "geolocation=(), microphone=(), camera=(), payment=(), usb=(), magnetometer=(), gyroscope=()" always;

# allow only for same origin
add_header Permissions-Policy "geolocation=(self), microphone=(self)" always;

# allow for specific origins
add_header Permissions-Policy "camera=(self https://trusted.com)" always;
15

Контроль доступа

Allow/Deny по IP

Правила allow/deny проверяются по порядку; побеждает первое совпадение. Финальный deny all блокирует всё, что явно не разрешено. Это удобно для привязки админ-панелей к корпоративным IP. Правила принимают CIDR-диапазоны или отдельные IP и поддерживают IPv4 и IPv6.

nginx
location /admin {
    allow 192.168.1.0/24;     # internal network
    allow 10.0.0.0/8;         # VPN range
    allow 203.0.113.5;        # specific IP
    deny all;

    proxy_pass http://backend;
}

# rules are checked in order — first match wins
# if no rule matches, access is allowed by default

Deny All

deny all блокирует всех; сочетайте с allow для белого списка. Обратное — запретить конкретные IP, разрешить остальным — это чёрный список. Белые списки безопаснее (запрет по умолчанию). Без явных allow/deny доступ разрешён, поэтому для закрытых зон всегда завершайте deny all.

nginx
# deny all access to a location
location /private {
    deny all;
    return 403;
}

# deny specific IPs, allow everyone else
location / {
    deny 192.168.1.100;        # block one IP
    deny 203.0.113.0/24;       # block a range
    allow all;
}

# deny a range, allow the rest
location /api {
    deny 10.0.0.0/8;
    allow all;
    proxy_pass http://backend;
}

Разрешение подсети

Приватные диапазоны IP (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) не маршрутизируются в интернете, поэтому их разрешение ограничивает доступ внутренними сетями. Для IPv6 ::1 — это localhost. Сочетайте с VPN для безопасного удалённого доступа к внутренним инструментам.

nginx
# allow only local/private networks
location /internal {
    allow 192.168.0.0/16;     # private class B
    allow 172.16.0.0/12;      # private class B range
    allow 10.0.0.0/8;         # private class A
    deny all;

    root /var/www/internal;
}

# IPv6
location / {
    allow 2001:db8::/32;      # example IPv6 range
    allow ::1;                # IPv6 localhost
    deny all;
}

Модуль geo

geo оптимизирован для поиска по IP с помощью radix-дерева — гораздо быстрее длинного списка allow/deny. Он задаёт переменную (здесь $allowed_ip) по IP клиента. Форма 'ranges' поддерживает диапазоны IP от начала до конца. Используйте переменную в if() или map для гибкого контроля доступа.

nginx
# map IPs to values (binary search, very fast)
geo $allowed_ip {
    default        0;
    192.168.0.0/24 1;
    10.0.0.0/8     1;
    203.0.113.5    1;
}

server {
    location /admin {
        if ($allowed_ip = 0) {
            return 403;
        }
        proxy_pass http://backend;
    }
}

# geo with IP ranges (uses 'ranges' directive)
geo $country_code {
    ranges;
    default                 ZZ;
    10.0.0.0-10.255.255.255 US;
}

Ограничение по IP (limit_req)

limit_req_zone задаёт частоту на IP с использованием $binary_remote_addr (компактно). limit_req применяет её. burst допускает короткие всплески (очередь до 20). nodelay обслуживает всплеск немедленно, а не притормаживает его, — хорошо для API. Без nodelay избыточные запросы задерживаются, а не отклоняются.

nginx
http {
    # define rate limit zone (10 requests/sec per IP)
    limit_req_zone $binary_remote_addr zone=mylimit:10m rate=10r/s;

    server {
        location /api/ {
            limit_req zone=mylimit burst=20 nodelay;
            proxy_pass http://backend;
        }
    }
}

# $binary_remote_addr uses binary form (more memory-efficient)
# 10m zone stores ~160,000 unique IP addresses
# rate=10r/s: 10 requests per second per IP
# burst=20: allow 20 requests to queue
# nodelay: serve the burst immediately (no artificial delay)

Блокировка по странам (GeoIP)

Модуль GeoIP сопоставляет IP клиентов с кодами стран по базе MaxMind. Вместе с map можно блокировать или разрешать целые страны. Учтите: бесплатная GeoLite2 от MaxMind требует стороннего модуля maxminddb (устаревший модуль GeoIP использует старый формат .dat). Точность не 100% — используйте только для грубой фильтрации.

nginx
# requires the GeoIP module and a MaxMind database
geoip_country /usr/share/GeoIP/GeoIP.dat;

map $geoip_country_code $allowed_country {
    default yes;
    CN no;
    RU no;
    KP no;
}

server {
    location / {
        if ($allowed_country = no) {
            return 403;
        }
        proxy_pass http://backend;
    }
}

# GeoIP2 (maxminddb module) for the newer GeoLite2 format
# maxminddb /etc/nginx/geoip2/GeoLite2-Country.mmdb;
# $geoip2_country_code source=$remote_addr country iso_code;
16

Аутентификация

Базовая аутентификация

auth_basic вызывает встроенное окно ввода логина и пароля в браузере. Строка realm ('Admin Area') показывается пользователю. auth_basic_user_file указывает на файл htpasswd. Используйте auth_basic off, чтобы отключить аутентификацию в публичном подразделе.

nginx
location /admin {
    auth_basic "Admin Area";
    auth_basic_user_file /etc/nginx/.htpasswd;

    proxy_pass http://backend;
}

location /public {
    # disable auth inherited from parent location
    auth_basic off;
}

# create users with htpasswd (apache2-utils / httpd-tools):
# htpasswd -c /etc/nginx/.htpasswd user1   (create file)
# htpasswd /etc/nginx/.htpasswd user2      (append, no -c)

Файл htpasswd

Файл htpasswd хранит пары логин:хеш. bcrypt (-B) — самый стойкий хеш; MD5 (-m, по умолчанию) приемлем; SHA1 (-s) слаб; PLAIN небезопасен. Ограничьте права на файл, чтобы его мог читать только nginx: в нём хеши паролей, которые не должны утечь.

nginx
# /etc/nginx/.htpasswd format:
# user1:$apr1$qHR...$hashedpassword
# user2:{PLAIN}plaintext       (insecure!)
# user3:{SHA}base64sha1hash

# generate with htpasswd:
# -c  create new file (overwrites!)
# -B  bcrypt (most secure, recommended)
# -m  MD5 (default, APR1)
# -s  SHA1

# bcrypt (recommended)
# htpasswd -B /etc/nginx/.htpasswd user1

# protect the file permissions
chown root:nginx /etc/nginx/.htpasswd
chmod 640 /etc/nginx/.htpasswd

Аутентификация для отдельного location

auth_basic наследуется вложенными location. Чтобы сделать подпуть публичным, задайте auth_basic off. Это удобно, когда большая часть /admin требует аутентификации, а /admin/health (эндпоинт проверки здоровья) должен быть доступен без учётных данных для систем мониторинга.

nginx
server {
    # no auth at server level

    location /admin {
        auth_basic "Admin";
        auth_basic_user_file /etc/nginx/.htpasswd;
    }

    location /admin/api {
        # inherits auth from /admin
        proxy_pass http://admin_api;
    }

    location /admin/public {
        # explicitly disable inherited auth
        auth_basic off;
        proxy_pass http://public_api;
    }
}

Allow/Deny вместе с аутентификацией

satisfy any означает, что доступ даёт либо проверка IP, ЛИБО аутентификация, — удобно для внутренних пользователей (без пароля), при этом внешние всё равно должны вводить пароль. satisfy all требует оба условия — самый строгий вариант, полезный для особо чувствительных зон.

nginx
# satisfy: ALL (default) or ANY
location / {
    # allow corporate IPs without password
    # require password from outside the corporate network
    satisfy any;

    allow 192.168.0.0/16;
    deny all;

    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;

    proxy_pass http://backend;
}

# satisfy all: must pass BOTH IP check AND auth
# satisfy any: pass EITHER IP check OR auth

Модуль auth_request

auth_request отправляет внутренний подзапрос сервису аутентификации перед основным запросом. Сервис проверяет токен (JWT, сессионную cookie и т. п.) и возвращает 2xx (разрешить) или 401/403 (запретить). internal закрывает /auth от внешнего доступа. Это отделяет аутентификацию от приложения.

nginx
# delegate authentication to a subrequest (OAuth, JWT, etc.)
location / {
    auth_request /auth;
    proxy_pass http://backend;
}

location = /auth {
    internal;                    # can't be called directly
    proxy_pass http://auth-service/validate;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}

# auth-service returns:
# 2xx -> allow (continue to backend)
# 401/403 -> deny (return to client)
# other -> error

Аутентификация JWT

Проверку JWT можно выполнять в процессе через njs (JavaScript-модуль nginx) для низкой задержки или делегировать внешнему сервису через auth_request. njs исполняет подмножество JavaScript внутри nginx — быстро, но ограниченно. Подход с auth_request гибче и не зависит от языка.

nginx
# requires the njs (nginx JavaScript) module
js_import auth.js;

location /api/ {
    js_content auth.validateJwt;
    proxy_pass http://backend;
}

# auth.js defines the validateJwt function:
# function validateJwt(r) {
#     var token = r.headersIn.Authorization;
#     if (!token || !verifyJwt(token)) {
#         r.return(401);
#         return;
#     }
# }

# alternative: use auth_request with an external JWT validator service
# more portable than njs, but adds a network hop per request
17

Логирование

Access-лог

access_log записывает каждый запрос. log_format определяет, какие поля захватывать. Формат 'combined' по умолчанию совместим с Apache. Для нагруженных сайтов buffer+flush снижает нагрузку на диск, группируя записи. syslog отправляет логи на центральный сервер для агрегации.

nginx
http {
    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;
    # or use the built-in 'combined' format
    access_log /var/log/nginx/access.log combined;
}

# disable access log
access_log off;

# log to syslog
access_log syslog:server=localhost,facility=local7 main;

# buffer writes (reduce I/O)
access_log /var/log/nginx/access.log main buffer=32k flush=5s;

Error-лог

error_log фиксирует ошибки nginx и проблемы upstream. Уровень фильтрует важность: warn — хорошее значение по умолчанию. debug очень подробен (только для диагностики) и требует debug-сборки. memory: буферизует логи в RAM — полезно для диагностики проблем запуска, которые не попадут в дисковый лог.

nginx
# error log location and severity level
error_log /var/log/nginx/error.log warn;

# levels (low to high severity):
# debug, info, notice, warn, error, crit, alert, emerg

# debug requires nginx built with --with-debug
error_log /var/log/nginx/error.log debug;

# log to memory (for debugging, lost on restart)
error_log memory:32m debug;

# disable (NOT recommended — hides real errors)
error_log /dev/null crit;

Форматы логов

Пользовательские форматы логов захватывают то, что важно вам. request_time — общее время обработки; upstream_response_time выделяет бэкенд. escape=json выдаёт корректный JSON для агрегаторов логов (ELK, Loki, Datadog). Без escape=json спецсимволы в URI могли бы сломать разбор JSON.

nginx
http {
    # combined (Apache-compatible, the default)
    log_format combined '$remote_addr - $remote_user [$time_local] '
                        '"$request" $status $body_bytes_sent '
                        '"$http_referer" "$http_user_agent"';

    # main with upstream timing
    log_format main '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent" '
                    'rt=$request_time uct="$upstream_connect_time" '
                    'urt="$upstream_response_time"';

    # JSON format for log aggregation (ELK, Loki, etc.)
    log_format json escape=json
        '{"time":"$time_iso8601",'
        '"remote":"$remote_addr",'
        '"method":"$request_method",'
        '"uri":"$request_uri",'
        '"status":$status,'
        '"bytes":$body_bytes_sent,'
        '"ua":"$http_user_agent"}';
}

Условное логирование

Параметр if= включает логирование по условию на переменной. map $status позволяет логировать только ошибки (4xx/5xx), снижая шум и расход диска на нагруженных сайтах. Переменная должна быть 0 или пустой, чтобы пропустить логирование, и ненулевой, чтобы писать.

nginx
http {
    # don't log successful 2xx/3xx, only errors
    map $status $loggable {
        ~^[23]  0;
        default 1;
    }

    server {
        access_log /var/log/nginx/access.log main if=$loggable;
    }
}

# skip logging for static assets
map $request_uri $log_skip {
    default                    1;
    ~*\.(jpg|png|gif|css|js)$  0;
}
access_log /var/log/nginx/access.log main if=$log_skip;

Ротация логов

logrotate переименовывает и сжимает старые логи. postrotate посылает nginx сигнал USR1, и тот переоткрывает файлы логов: без этого nginx продолжит писать в переименованный файл. sharedscripts запускает postrotate один раз (а не на каждый файл). delaycompress сжимает со второго оборота, поэтому последний лог остаётся несжатым.

nginx
# logrotate config: /etc/logrotate.d/nginx
/var/log/nginx/*.log {
    daily
    missingok
    rotate 14
    compress
    delaycompress
    notifempty
    create 0640 www-data adm
    sharedscripts
    postrotate
        if [ -f /var/run/nginx.pid ]; then
            kill -USR1 $(cat /var/run/nginx.pid)
        fi
    endscript
}

# USR1 signal tells nginx to reopen log files
# without dropping connections
# nginx -s reopen does the same thing

Отключение логирования

Отключение access_log для проверок здоровья и статики заметно снижает шум в логах и нагрузку на диск. log_not_found off подавляет записи о 404 (полезно для favicon.ico). Всегда оставляйте error_log включённым хотя бы на уровне 'error': молчаливые сбои трудно диагностировать.

nginx
# disable access log entirely
access_log off;

# disable for a specific location
location /health {
    access_log off;
    return 200 "ok\n";
}

# disable for static assets
location ~* \.(jpg|png|gif|ico|css|js)$ {
    access_log off;
    log_not_found off;
}

# only log errors (reduce error log verbosity)
error_log /var/log/nginx/error.log error;
18

Ограничение частоты запросов

limit_req_zone

limit_req_zone определяет лимит с ключом по переменной (обычно IP клиента). Размер зоны (10m) определяет, сколько уникальных ключей можно отслеживать. rate — допустимая частота запросов. Определяйте зоны в контексте http, применяйте в контексте location через limit_req.

nginx
http {
    # 10 requests per second per IP
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

    # 1 request per second per IP (for login)
    limit_req_zone $binary_remote_addr zone=login:10m rate=1r/s;

    # 100 requests per minute per IP
    limit_req_zone $binary_remote_addr zone=general:10m rate=100r/m;
}

# $binary_remote_addr uses binary form (more memory-efficient than text)
# 10m zone stores ~160,000 unique IP addresses
# rate can be per second (r/s) or per minute (r/m)

limit_req

limit_req применяет зону к location. burst допускает короткие всплески (очередь до N избыточных запросов). nodelay обслуживает всплеск на полной скорости, а не растягивает его, — хорошо для API, где важна задержка. Без burst каждый запрос сверх лимита отклоняется сразу.

nginx
http {
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

    server {
        location /api/ {
            limit_req zone=api burst=20 nodelay;
            proxy_pass http://backend;
        }

        location /login {
            limit_req zone=api burst=5 nodelay;
            proxy_pass http://backend;
        }
    }
}

# burst: max number of requests allowed to queue
# nodelay: serve the burst immediately (no artificial throttling)
# without burst: requests exceeding the rate get 503 immediately

limit_conn

limit_conn ограничивает одновременные соединения, а не частоту запросов. Полезно, чтобы один IP не открывал сотни одновременных скачиваний. Вместе с limit_req (частота) даёт защиту и от всплесков, и от параллелизма. limit_conn_zone использует тот же паттерн зон по ключу.

nginx
http {
    # limit concurrent connections per IP
    limit_conn_zone $binary_remote_addr zone=conn_per_ip:10m;

    # limit total connections per server name
    limit_conn_zone $server_name zone=conn_per_server:10m;

    server {
        limit_conn conn_per_ip 10;
        limit_conn conn_per_server 1000;

        location /download {
            limit_conn conn_per_ip 1;  # one download at a time per IP
            proxy_pass http://backend;
        }
    }
}

Очередь burst

burst — размер очереди для избыточных запросов. nodelay обслуживает весь всплеск сразу (хорошо для API). delay=N обслуживает N сразу, а остальные притормаживает до заданной частоты (плавнее). Без nodelay все избыточные запросы задерживаются под частоту, равномерно распределяя нагрузку.

nginx
http {
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

    server {
        location /api/ {
            # burst=20: allow 20 requests to queue
            # nodelay: serve them immediately (no artificial delay)
            limit_req zone=api burst=20 nodelay;

            # delay: first 10 immediate, next 10 delayed, rest rejected
            limit_req zone=api burst=20 delay=10;

            proxy_pass http://backend;
        }
    }
}

# without burst: requests over rate get 503 immediately
# with burst: excess requests queue (default delayed)
# nodelay: queue served at full speed (allows spikes)
# delay=N: first N immediate, rest throttled to the rate

Лимит по IP

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

nginx
http {
    # different limits for different endpoints
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
    limit_req_zone $binary_remote_addr zone=auth:10m rate=1r/s;
    limit_req_zone $binary_remote_addr zone=upload:10m rate=2r/m;

    server {
        location /api/ {
            limit_req zone=api burst=20 nodelay;
        }

        location /login {
            limit_req zone=auth burst=5 nodelay;
        }

        location /upload {
            limit_req zone=upload burst=3 nodelay;
            client_max_body_size 100M;
        }
    }
}

Свой ответ при превышении лимита

По умолчанию запросы сверх лимита получают 503 (Service Unavailable). 429 (Too Many Requests) семантически корректнее и ожидается большинством API. Используйте error_page, чтобы вернуть JSON с объяснением лимита. Добавьте заголовок Retry-After, чтобы клиенты знали, когда отступить.

nginx
http {
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
    limit_req_status 429;  # default is 503

    server {
        location /api/ {
            limit_req zone=api burst=20 nodelay;

            # custom error response
            error_page 429 = @rate_limited;
        }

        location @rate_limited {
            default_type application/json;
            return 429 '{"error":"rate_limit_exceeded","retry_after":60}';
        }
    }
}

# also available: limit_conn_status 429;
19

Настройка производительности

worker_processes

worker_processes должен соответствовать числу ядер CPU — значение auto делает это автоматически. Каждый воркер — однопоточный процесс, обслуживающий множество соединений через цикл событий. worker_cpu_affinity привязывает воркеры к конкретным ядрам, улучшая локальность кеша. Автоматическая привязка оставляет решение планировщику ОС.

nginx
# main context
worker_processes auto;  # one per CPU core (recommended)

# or set an explicit count
worker_processes 4;

# each worker handles connections independently
# 'auto' uses the number of available CPU cores

# CPU affinity (pin workers to specific cores)
worker_processes auto;
worker_cpu_affinity auto;

# or manual bitmask (one mask per worker)
worker_processes 4;
worker_cpu_affinity 0001 0010 0100 1000;

worker_connections

worker_connections задаётся на воркер; общая ёмкость — worker_processes * worker_connections. Она также ограничена лимитом файловых дескрипторов ОС (worker_rlimit_nofile). Нужно поднять и лимит nginx, и лимит ОС (limits.conf или LimitNOFILE в systemd). multi_accept забирает все ожидающие соединения разом.

nginx
events {
    # connections per worker process
    worker_connections 4096;

    # accept multiple connections at once under high load
    multi_accept on;
}

# total max connections = worker_processes * worker_connections
# but also bounded by worker_rlimit_nofile (file descriptor limit)

# main context — raise the FD limit
worker_rlimit_nofile 65535;

# also raise system limits (outside nginx):
# /etc/security/limits.conf:
#   * soft nofile 65535
#   * hard nofile 65535

keepalive_timeout

Keepalive клиента переиспользует соединения для нескольких запросов, снижая задержку. keepalive_timeout — сколько простаивающее соединение остаётся открытым. Keepalive upstream (директива keepalive в upstream) кеширует соединения к бэкендам: установите Connection в пустую строку, чтобы nginx не отправлял 'close'.

nginx
http {
    # keep-alive timeout (client side)
    keepalive_timeout 65s;
    keepalive_requests 1000;  # max requests per connection

    # upstream keepalive (reuse connections to backends)
    upstream backend {
        server 10.0.0.1:8080;
        keepalive 32;  # cache of 32 idle upstream connections
    }

    location / {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";  # clear to enable keepalive
    }
}

sendfile и tcp_nopush

sendfile использует zero-copy путь на уровне ядра, минуя буферы пользовательского пространства, — гораздо быстрее для статики. tcp_nopush работает вместе с sendfile, отправляя заголовки и начало файла одним пакетом. tcp_nodelay отключает алгоритм Нейгла ради низкой задержки. aio threads снимает дисковый ввод-вывод с цикла событий.

nginx
http {
    # use kernel sendfile() for static files (zero-copy)
    sendfile on;

    # send headers + start of file in one TCP packet
    tcp_nopush on;

    # disable Nagle's algorithm (send small packets immediately)
    tcp_nodelay on;

    # for static file serving
    location /static/ {
        sendfile on;
        tcp_nopush on;
        aio threads;  # asynchronous I/O via thread pool
        root /var/www;
    }
}

# sendfile: zero-copy file transfer (kernel space, no user-space copy)
# tcp_nopush: coalesce headers + file data into one packet
# tcp_nodelay: don't wait to batch small packets (low latency)

Размеры буферов

Настраивайте буферы под свой трафик. client_max_body_size ограничивает размер загрузки (по умолчанию 1M — слишком мало для файлов). Буферы proxy/fastcgi держат ответы upstream; слишком маленькие сбрасываются на диск. large_client_header_buffers обрабатывают длинные URL и cookie. Следите за ошибками 'buffer overflow'.

nginx
http {
    # client body buffer (in-memory before writing to disk)
    client_body_buffer_size 16k;
    client_max_body_size 50m;

    # client header buffers
    client_header_buffer_size 1k;
    large_client_header_buffers 4 8k;

    # proxy buffers (responses from upstream)
    proxy_buffer_size 4k;
    proxy_buffers 8 4k;
    proxy_busy_buffers_size 16k;

    # fastcgi buffers (responses from PHP-FPM, etc.)
    fastcgi_buffer_size 4k;
    fastcgi_buffers 8 4k;
}

# if a request body exceeds client_body_buffer_size,
# nginx writes it to a temp file (slower)

Кеш открытых файлов

open_file_cache кеширует файловые дескрипторы и метаданные, избегая повторных системных вызовов open()/stat() для популярных файлов. Это заметно ускоряет раздачу статики. valid определяет, как часто nginx перепроверяет файл (ловит обновления). min_uses не даёт кешировать разовые запросы. Кешируйте и ошибки, чтобы не повторять неудачные открытия.

nginx
http {
    open_file_cache max=10000 inactive=20s;
    open_file_cache_valid 30s;
    open_file_cache_min_uses 2;
    open_file_cache_errors on;

    server {
        root /var/www/html;

        location / {
            open_file_cache max=10000 inactive=20s;
            open_file_cache_valid 30s;
            try_files $uri $uri/ =404;
        }
    }
}

# caches file descriptors, sizes, modification times
# reduces stat() and open() syscalls for popular files
# max=10000: cache up to 10000 files
# inactive=20s: remove if not accessed in 20 seconds
# min_uses=2: only cache files accessed 2+ times
# valid=30s: re-validate cache every 30s
20

Развёртывание в Docker

Nginx в Docker

Официальный образ nginx по умолчанию отдаёт /usr/share/nginx/html и читает конфигурацию из /etc/nginx. Монтируйте конфигурацию и контент как тома. :ro (только чтение) не даёт контейнеру менять файлы хоста. nginx -s reload подхватывает изменения конфигурации без пересоздания контейнера.

nginx
# run the official nginx image
docker run -d --name nginx \
    -p 80:80 -p 443:443 \
    -v /etc/nginx/nginx.conf:/etc/nginx/nginx.conf:ro \
    -v /var/www/html:/usr/share/nginx/html:ro \
    -v /etc/nginx/conf.d:/etc/nginx/conf.d:ro \
    nginx:latest

# interactive shell into the running container
docker exec -it nginx sh

# reload config without restarting the container
docker exec nginx nginx -s reload

# view logs
docker logs nginx
docker logs -f nginx

Docker Compose

Docker Compose оркестрирует nginx с его бэкендами. expose открывает порт для связанных сервисов (но не для хоста). depends_on гарантирует, что бэкенд стартует первым. restart: unless-stopped переживает перезагрузки, но уважает ручные остановки. Монтируйте логи с правом записи (без :ro), чтобы nginx мог их писать.

nginx
version: '3.8'
services:
  nginx:
    image: nginx:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./conf.d:/etc/nginx/conf.d:ro
      - ./html:/usr/share/nginx/html:ro
      - ./certs:/etc/nginx/certs:ro
      - ./logs:/var/log/nginx
    depends_on:
      - backend
    restart: unless-stopped

  backend:
    image: myapp:latest
    expose:
      - "3000"

Собственный образ Nginx

Запекание конфигурации в образ делает развёртывания неизменяемыми и воспроизводимыми — монтирование томов во время работы не нужно. Вариант alpine держит образ крошечным (~7 МБ база). Идеально для Kubernetes или CI/CD, где нужен самодостаточный артефакт. Пересобирайте для обновления конфигурации.

nginx
# Dockerfile
FROM nginx:alpine

# copy custom config
COPY nginx.conf /etc/nginx/nginx.conf
COPY conf.d/ /etc/nginx/conf.d/

# copy static files
COPY html/ /usr/share/nginx/html/

# copy SSL certificates
COPY certs/ /etc/nginx/certs/

# build and run
# docker build -t mynginx .
# docker run -d -p 80:80 mynginx

# alpine is ~7MB; the image stays small
# bake config in for immutable deployments

Монтирование томов

Тома позволяют менять конфигурацию без пересборки образа — идеально для разработки. Монтирование каталога надёжно; монтирование отдельного файла может сломаться, если файла на хосте нет (Docker создаст каталог). Именованные тома сохраняются между пересозданиями контейнера и управляются Docker.

nginx
# mount config and content as volumes (dev workflow)
docker run -d --name nginx \
    -p 80:80 \
    -v $(pwd)/nginx.conf:/etc/nginx/nginx.conf:ro \
    -v $(pwd)/conf.d:/etc/nginx/conf.d:ro \
    -v $(pwd)/html:/usr/share/nginx/html:ro \
    -v $(pwd)/logs:/var/log/nginx \
    nginx:alpine

# read-only mounts (:ro) for security
# logs need write access (no :ro)
# use named volumes for persistent data:
#   -v nginx_logs:/var/log/nginx

# IMPORTANT: mounting a single file (nginx.conf) requires
# the file to exist on the host, or Docker creates a directory

Обратный прокси в Docker

В Docker Compose сервисы находят друг друга по имени сервиса (app1, app2). Upstream nginx может ссылаться на эти имена напрямую — IP-адреса не нужны. Это делает nginx мощным балансировщиком для контейнеризованных приложений. Используйте сеть Compose по умолчанию или определите собственную для изоляции.

nginx
# nginx as reverse proxy for other containers
version: '3.8'
services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - app1
      - app2
    restart: unless-stopped

  app1:
    image: myapp:latest

  app2:
    image: myapp:latest

# nginx.conf:
# upstream apps {
#     server app1:3000;
#     server app2:3000;
# }
# server {
#     listen 80;
#     location / { proxy_pass http://apps; }
# }

Проверка здоровья

Healthcheck позволяет Docker (и оркестраторам вроде Swarm) узнать, действительно ли nginx обслуживает запросы, а не просто запущен. wget --spider проверяет HTTP-статус, не скачивая тело. start_period откладывает первую проверку, чтобы nginx успел запуститься. В Kubernetes используйте readiness/liveness probe вместо Docker HEALTHCHECK.

nginx
# Dockerfile with a health check
FROM nginx:alpine

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD wget --quiet --tries=1 --spider http://localhost/ || exit 1

COPY nginx.conf /etc/nginx/nginx.conf

# docker-compose health check
version: '3.8'
services:
  nginx:
    image: nginx:alpine
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost/"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 5s

# start_period gives nginx time to boot before checking
# a failed health check marks the container unhealthy

Was this helpful?