Шпаргалка по Nginx: команды, фрагменты конфигурации и исправление ошибок

10 мин чтения·Matthieu
web-servernginxreverse-proxycheatsheetlinux

Быстрый справочник по ежедневным операциям с Nginx на Debian 12 и Ubuntu 24.04. Организован по задачам, чтобы быстро найти нужное. Полное руководство: Администрирование Nginx на VPS.

Как управлять сервисом Nginx?

Используй systemctl для управления Nginx через systemd или отправляй сигналы напрямую через nginx -s. Systemctl — стандарт на современных Debian и Ubuntu. Нативные команды nginx -s общаются с мастер-процессом через PID-файл. Оба способа работают. Systemctl лучше для автоматизации и сохранения настроек при загрузке.

Соответствие сигналов и команд

Действие Команда systemctl Эквивалент nginx -s Unix-сигнал Что происходит с воркерами
Запуск sudo systemctl start nginx (неприменимо) - Мастер-процесс стартует, порождает воркеры
Остановка (graceful) sudo systemctl stop nginx sudo nginx -s quit SIGQUIT Воркеры завершают текущие запросы и останавливаются
Остановка (немедленная) sudo systemctl kill nginx sudo nginx -s stop SIGTERM Воркеры разрывают соединения и останавливаются
Перезагрузка конфига sudo systemctl reload nginx sudo nginx -s reload SIGHUP Новые воркеры запускаются с новым конфигом. Старые завершают свои запросы и останавливаются. Потерянных соединений нет.
Переоткрытие логов (не встроено) sudo nginx -s reopen SIGUSR1 Воркеры переоткрывают файловые дескрипторы логов. Используй после ротации логов.
Включить автозапуск + запустить sudo systemctl enable --now nginx (неприменимо) - Создаёт симлинк для автозапуска, запускает немедленно
Отключить + остановить sudo systemctl disable --now nginx (неприменимо) - Удаляет симлинк автозапуска, немедленно останавливает

enable --now обеспечивает выживание Nginx после перезагрузки и запускает его сразу. Всегда используй эту команду вместо простого start.

Reload vs restart

reload отправляет SIGHUP. Мастер-процесс читает новый конфиг, порождает новые воркеры и даёт старым завершить активные соединения. Нулевой простой.

restart отправляет SIGTERM (остановка), затем стартует заново. Все активные соединения обрываются. Используй restart только при смене портов прослушивания, загрузке новых модулей или обновлении бинарника Nginx.

Всегда тестируй перед перезагрузкой:

sudo nginx -t && sudo systemctl reload nginx

Если nginx -t завершается с ошибкой, перезагрузка не выполняется. Рабочий конфиг остаётся нетронутым.

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

После перезагрузки:

sudo systemctl status nginx

● nginx.service - A high performance web server and a reverse proxy server
     Loaded: loaded (/usr/lib/systemd/system/nginx.service; enabled; preset: enabled)
     Active: active (running) since Thu 2026-03-20 10:15:32 UTC; 2s ago

enabled в строке Loaded означает, что сервис запустится при загрузке. Установка Nginx на Debian 12 и Ubuntu 24.04 из официального репозитория

Как проверить и просмотреть конфигурацию Nginx?

Запусти nginx -t для проверки синтаксиса без воздействия на работающий сервер. nginx -T проверяет и выводит полный разобранный конфиг в stdout. nginx -V показывает модули и флаги компиляции.

Команда Назначение
sudo nginx -t Проверить синтаксис конфига, убедиться что указанные файлы существуют
sudo nginx -t -q То же, но подавляет вывод без ошибок (полезно в скриптах)
sudo nginx -T Проверка + вывод полного разобранного конфига в stdout
sudo nginx -V Версия, компилятор, аргументы configure, встроенные модули
sudo nginx -v Только номер версии

Вывод и поиск по рабочему конфигу

sudo nginx -T 2>/dev/null | grep -A5 "server_name example.com"

Эта команда выводит полный конфиг (все включённые файлы объединены) и фильтрует конкретный блок server. Быстрее, чем открывать файлы вручную, когда у тебя десятки include.

Проверка скомпилированных модулей

sudo nginx -V 2>&1 | tr ' ' '\n' | grep module

--with-http_ssl_module
--with-http_v2_module
--with-http_realip_module
--with-http_gzip_static_module
--with-http_stub_status_module

Директиву нельзя использовать, если её модуль не скомпилирован. Это первое, что стоит проверить при ошибке «unknown directive».

Где находятся конфиги и логи Nginx?

На Debian 12 и Ubuntu 24.04 пакетный менеджер ставит всё в /etc/nginx/. Логи пишутся в /var/log/nginx/. Полная структура:

Путь Назначение
/etc/nginx/nginx.conf Основной конфиг. Задаёт количество воркеров, events, блок http, includes
/etc/nginx/sites-available/ Файлы блоков server (доступные, но не обязательно активные)
/etc/nginx/sites-enabled/ Симлинки на sites-available. Nginx загружает их.
/etc/nginx/conf.d/ Дополнительные фрагменты конфига. Загружаются через include в nginx.conf
/etc/nginx/snippets/ Переиспользуемые сниппеты конфига (параметры SSL, заголовки безопасности)
/etc/nginx/mime.types Таблица MIME-типов
/var/log/nginx/access.log Лог запросов
/var/log/nginx/error.log Лог ошибок
/run/nginx.pid PID-файл мастер-процесса

Включить сайт:

sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Отключить сайт:

sudo rm /etc/nginx/sites-enabled/example.com
sudo nginx -t && sudo systemctl reload nginx

Подробнее о структуре каталогов: Структура конфигурационных файлов Nginx.

Какие сниппеты конфигурации Nginx используются чаще всего?

Каждый сниппет ниже — минимальный рабочий пример. Скопируй, подставь свои значения, проверь через nginx -t, перезагрузи. Полные руководства по каждой теме — по внутренним ссылкам.

Как настроить базовый блок server?

Блок server (виртуальный хост) привязывает домен к корневой директории документов. Помести это в /etc/nginx/sites-available/example.com.

server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;

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

    server_tokens off;

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

server_tokens off скрывает версию Nginx из заголовков ответа. Раскрытие версии помогает атакующим нацеливаться на известные уязвимости.

Создай симлинк в sites-enabled и перезагрузи. Nginx Server Blocks: несколько доменов на одном VPS

Как перенаправить HTTP на HTTPS?

server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;

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

return 301 быстрее, чем rewrite для полных URL-редиректов. Nginx обрабатывает return до обращения к файловой системе.

Как настроить Nginx как обратный прокси?

Перенаправляй запросы на бэкенд, работающий на порту 3000. Помести это в блок server HTTPS.

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Завершающий слеш имеет значение. proxy_pass http://127.0.0.1:3000; (без завершающего слеша) передаёт полный исходный URI. proxy_pass http://127.0.0.1:3000/; (с завершающим слешем) отсекает префикс location. Это причина множества сломанных прокси-конфигураций.

Настройка Nginx как обратного прокси

Как включить сжатие gzip?

Добавь в блок http {} в /etc/nginx/nginx.conf или в файл-сниппет:

gzip on;
gzip_vary on;
gzip_proxied any;
gzip_min_length 1024;
gzip_comp_level 5;
gzip_types
    text/plain
    text/css
    text/javascript
    application/json
    application/javascript
    application/xml
    image/svg+xml;

gzip_min_length 1024 пропускает файлы меньше 1 КБ. Сжимать маленькие файлы — лишняя нагрузка на CPU без заметного уменьшения размера. gzip_comp_level 5 — хороший баланс между степенью сжатия и нагрузкой на CPU. Выше 6 отдача уменьшается.

Тюнинг производительности Nginx на VPS

Как добавить ограничение частоты запросов?

Определи зону в блоке http {}, затем примени её в блоке location или server.

# In http {} block
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

# In server or location block
location /api/ {
    limit_req zone=api burst=20 nodelay;
    proxy_pass http://127.0.0.1:8080;
}

$binary_remote_addr использует 4 байта на IPv4-адрес. Зона 10 МБ вмещает около 160 000 адресов. burst=20 допускает кратковременные всплески. nodelay обслуживает burst-запросы немедленно, а не ставит их в очередь.

Rate limiting в Nginx и защита от DDoS

Как проксировать WebSocket-соединения?

location /ws/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 86400s;
}

proxy_http_version 1.1 обязателен. HTTP/1.0 не поддерживает заголовок Upgrade. proxy_read_timeout 86400s держит неактивные WebSocket-соединения открытыми 24 часа вместо 60 секунд по умолчанию.

Как настроить кастомные страницы ошибок?

server {
    error_page 404 /404.html;
    error_page 500 502 503 504 /50x.html;

    location = /404.html {
        root /var/www/errors;
        internal;
    }

    location = /50x.html {
        root /var/www/errors;
        internal;
    }
}

Директива internal предотвращает прямой доступ к URL страниц ошибок. Без неё пользователи могли бы напрямую открыть /404.html.

Как добавить заголовки безопасности?

Создай /etc/nginx/snippets/security-headers.conf:

add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;

Подключи его в любом блоке server:

include snippets/security-headers.conf;

Параметр always добавляет заголовки даже для ответов с ошибками (4xx, 5xx). Без него Nginx добавляет их только для 2xx/3xx. Укрепление безопасности Nginx на Ubuntu и Debian

Минимальный TLS-блок server

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name example.com;

    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers off;
    server_tokens off;

    # ... location blocks
}

Не включай TLSv1 или TLSv1.1. Оба имеют известные уязвимости и отклоняются современными браузерами. Настройка Let's Encrypt SSL/TLS для Nginx на Debian 12 и Ubuntu 24.04

Как читать и отлаживать логи Nginx?

Nginx пишет два лога по умолчанию: access.log для каждого запроса и error.log для проблем. Оба находятся в /var/log/nginx/.

Просмотр логов в реальном времени

sudo tail -f /var/log/nginx/error.log

Или через journald:

journalctl -u nginx -f

Уровни серьёзности лога ошибок

Директива error_log принимает уровень. От самого подробного к наименее:

debug > info > notice > warn > error > crit > alert > emerg

По умолчанию — error. Для временного включения отладочного логирования:

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

Перезагрузи Nginx. Отладочное логирование крайне многословное. Отключи его после диагностики, иначе оно заполнит диск.

Формат логов доступа в JSON

Структурированные логи проще парсить инструментами вроде jq, Loki или OpenObserve.

log_format json_combined escape=json
    '{'
        '"time":"$time_iso8601",'
        '"remote_addr":"$remote_addr",'
        '"method":"$request_method",'
        '"uri":"$request_uri",'
        '"status":$status,'
        '"body_bytes_sent":$body_bytes_sent,'
        '"request_time":$request_time,'
        '"upstream_response_time":"$upstream_response_time",'
        '"http_user_agent":"$http_user_agent"'
    '}';

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

Набор инструментов для отладки

Команда Что делает
curl -I https://example.com Показывает только заголовки ответа. Проверь код статуса, версию сервера, кеш-заголовки.
curl -v https://example.com 2>&1 | head -30 Подробный вывод: TLS handshake, заголовки запроса/ответа.
sudo nginx -T 2>/dev/null | grep server_name Список всех настроенных server_name во всех конфиг-файлах.
sudo ss -tlnp | grep nginx Показывает, на каких портах/адресах слушает Nginx.
sudo ls -la /var/log/nginx/ Проверка размеров и прав файлов логов.

Включение stub_status для мониторинга

location /nginx_status {
    stub_status;
    allow 127.0.0.1;
    allow ::1;
    deny all;
}

curl http://127.0.0.1/nginx_status

Active connections: 3
server accepts handled requests
 1542 1542 4890
Reading: 0 Writing: 1 Waiting: 2

Ограничь stub_status адресом localhost или IP системы мониторинга. Эта директива раскрывает информацию о нагрузке сервера.

Что означают коды ошибок Nginx и как их исправить?

Когда Nginx возвращает HTTP-ошибку, error.log рассказывает, что произошло. Вот самые распространённые коды, их значение и способы исправления.

Код Название Типичное сообщение в error.log Частая причина Исправление
403 Forbidden directory index of "/var/www/html/" is forbidden Отсутствует файл index, неверные права на файлы, autoindex off (по умолчанию) Добавь index.html, исправь права (chmod 644 для файлов, 755 для каталогов) или включи autoindex on
404 Not Found open() "/var/www/html/page" failed (2: No such file or directory) Неверный путь root, неверный try_files, файл не существует Проверь директиву root, убедись что файл существует на диске
413 Request Entity Too Large client intended to send too large body Загрузка превышает client_max_body_size (по умолчанию: 1 МБ) Установи client_max_body_size 50m; в блоке server или location
502 Bad Gateway connect() failed (111: Connection refused) while connecting to upstream Бэкенд не запущен, неверный порт/сокет в proxy_pass Запусти бэкенд, проверь что порт совпадает с proxy_pass
503 Service Unavailable no live upstreams while connecting to upstream Все бэкенды в блоке upstream недоступны Запусти хотя бы один бэкенд, проверь конфиг health check
504 Gateway Timeout upstream timed out (110: Connection timed out) while reading response header Бэкенд слишком долго отвечает Увеличь proxy_read_timeout, оптимизируй бэкенд, проверь логи бэкенда

Диагностика 502

502 — самая частая ошибка проксирования. Пройди по шагам:

# 1. Is the backend running?
sudo ss -tlnp | grep 3000

# 2. Can Nginx reach it?
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:3000/

# 3. What does the error log say?
sudo tail -20 /var/log/nginx/error.log

Если ss ничего не показывает на порту 3000, бэкенд не запущен. Если curl возвращает ответ, а Nginx отдаёт 502, проверь права на сокеты (частая проблема с Unix-сокетами PHP-FPM или Gunicorn).

Какие ошибки Nginx встречаются чаще всего?

Именно они вызывают большинство ситуаций «я поменял конфиг и всё сломалось».

Пропущенные точки с запятой

Каждая директива должна заканчиваться точкой с запятой. Nginx выдаёт понятную ошибку:

nginx: [emerg] unexpected "}" in /etc/nginx/sites-enabled/example.com:12

Ошибка указывает на строку после пропущенной точки с запятой, а не на саму проблемную строку. Смотри на строку выше.

Путаница между root и alias

# root: appends the location to the path
location /images/ {
    root /var/www;
    # serves /var/www/images/photo.jpg
}

# alias: replaces the location with the path
location /images/ {
    alias /var/www/media/;
    # serves /var/www/media/photo.jpg
}

С alias завершающий слеш обязателен и в location, и в пути alias. Его отсутствие вызывает 404 без видимой причины в логе ошибок.

Путаница в порядке обработки location

Nginx обрабатывает location в таком порядке, независимо от их расположения в конфиг-файле:

  1. = /exact — Точное совпадение. Проверяется первым. При совпадении обработка прекращается.
  2. ^~ /prefix — Приоритетный префикс. Побеждает самое длинное совпадение. При совпадении все regex пропускаются.
  3. ~ regex — Регулярное выражение с учётом регистра. Обрабатывается сверху вниз. Побеждает первое совпадение.
  4. ~* regex — Регулярное выражение без учёта регистра. Тот же порядок сверху вниз.
  5. /prefix — Стандартный префикс. Побеждает самое длинное совпадение. Используется, только если ни один regex не сработал.

Для префиксов имеет значение длина совпадения, а не порядок в конфиг-файле. Для regex имеет значение порядок в конфиг-файле, а не длина. Смешивать их без понимания этого — путь к непредсказуемой маршрутизации.

Завершающий слеш в proxy_pass

# No trailing slash: passes /app/foo to backend as /app/foo
location /app/ {
    proxy_pass http://127.0.0.1:3000;
}

# Trailing slash: strips /app/ and passes /foo to backend
location /app/ {
    proxy_pass http://127.0.0.1:3000/;
}

Выбери один вариант и придерживайся его. Большинство бэкендов ожидают полный путь (без завершающего слеша в proxy_pass).

Забыл nginx -t перед перезагрузкой

Если перезагрузишь с битым конфигом, Nginx продолжит работать со старым конфигом и запишет ошибку в лог. Он не упадёт. Но теперь конфиг на диске не совпадает с запущенным. Это создаёт путаницу в будущем.

Выработай привычку: sudo nginx -t && sudo systemctl reload nginx. && гарантирует, что перезагрузка произойдёт только при успешном тесте.

Редактирование sites-available без создания симлинка

Файлы в /etc/nginx/sites-available/ не загружаются автоматически. Нужно создать симлинк в /etc/nginx/sites-enabled/. Прямое копирование тоже работает, но симлинки обеспечивают единый источник истины.

Что-то пошло не так?

Быстрая последовательность диагностики, когда Nginx ведёт себя неправильно:

# Check if Nginx is running
sudo systemctl status nginx

# Test the config
sudo nginx -t

# Check which config is actually loaded
sudo nginx -T 2>/dev/null | head -50

# Check the last 30 error log entries
sudo tail -30 /var/log/nginx/error.log

# Check what ports Nginx is listening on
sudo ss -tlnp | grep nginx

# Check file permissions on the web root
sudo ls -la /var/www/example.com/html/

Если сервис упал, journalctl -u nginx --no-pager -n 50 покажет полную картину. Ищи записи [emerg].

Готовы попробовать?

Разверните свой сервер за секунды. Linux, Windows или FreeBSD. →