Проверка конфигурации Nginx: обзор линтеров и руководство по nginx-lint

Зачем нужна автоматическая проверка конфигурации Nginx

Команда nginx -t проверяет только синтаксис — правильность скобок и точек с запятой. Ошибки безопасности, устаревшие протоколы и плохие практики она не обнаружит. В этой статье проводим проверку конфигурации Nginx с помощью специализированных линтеров: сравниваем четыре инструмента и показываем, как настроить автоматический аудит с помощью nginx-lint.

Проверка конфигурации Nginx: что упускает команда nginx -t

Стандартная команда nginx -t проверяет синтаксическую корректность: правильность расстановки скобок, точек с запятой и допустимость имён директив. Команда nginx -T дополнительно выводит полную конфигурацию со всеми обработанными include-директивами. Но это не полноценная проверка конфигурации Nginx — команда не проводит аудит безопасности и не находит логические ошибки в настройках.

Вот что остаётся за пределами nginx -t:

Безопасность — включён ли server_tokens, используются ли устаревшие SSL-протоколы (TLSv1.0, TLSv1.1), корректно ли настроен add_header. Линтер находит эти ошибки автоматически
Лучшие практики — есть ли autoindex on в открытом доступе, корректен ли alias без завершающего слэша, используется ли if в небезопасном контексте
Устаревшие директивы — например, директива ssl on, удалённая в Nginx 1.25.1. Без линтера такие ошибки обнаруживаются только при обновлении версии Nginx на сервере
Стиль и консистентность — единообразие отступов, порядок директив, одинаковое форматирование блоков server и location

Для инфраструктуры из одного-двух серверов достаточно ручного контроля — опытный администратор визуально заметит ошибку в конфигурации. Но когда серверов десятки и конфигурации меняются регулярно, ручной аудит перестаёт работать. Нужен линтер — инструмент для автоматической проверки конфигурации Nginx на ошибки безопасности, устаревшие настройки и нарушения лучших практик.

Рекомендуемый порядок проверки конфигурации Nginx на сервере:

nginx -t — убедиться, что синтаксис корректен и конфигурация загружается без ошибок
nginx-lint /etc/nginx/nginx.conf — провести полный аудит безопасности и лучших практик
Исправить найденные проблемы — вручную или через --fix для поддерживаемых правил
nginx -t повторно — убедиться, что исправления не сломали синтаксис
nginx -s 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

# Проверка с указанием файла
$ nginx -t -c /path/to/nginx.conf

# Вывод полной конфигурации (со всеми include)
$ nginx -T

Установка и настройка nginx-lint для аудита конфигурации

nginx-lint — современный линтер конфигурации Nginx, написанный на Rust. На момент написания статьи это наиболее функциональный инструмент для автоматической проверки конфигурации Nginx: 30+ встроенных правил, автоматическое исправление ошибок, поддержка WASM-плагинов, Web UI и интеграция с CI/CD.

Установка из исходного кода. Для сборки потребуется Rust toolchain (cargo). Клонируйте репозиторий и соберите проект командой cargo install --path .. Для сборки с поддержкой встроенного веб-сервера добавьте флаг --features web-server.

Запуск через Docker. Самый быстрый способ попробовать nginx-lint без установки. Образ доступен в GitHub Container Registry: ghcr.io/walf443/nginx-lint:latest. Монтируйте директорию с конфигурацией в read-only режиме и передайте путь к файлу. Для автоматического исправления ошибок потребуется монтирование в read-write режиме (без флага :ro).

Настройка правил через .nginx-lint.toml. После установки nginx-lint поддерживает гибкую настройку через конфигурационный файл. Создайте конфиг по умолчанию командой nginx-lint config init и адаптируйте под свои нужды. Основные секции конфигурации:

[rules.deprecated-ssl-protocol] — допустимые SSL/TLS протоколы. Рекомендуемое значение: ["TLSv1.2", "TLSv1.3"]
[rules.server-tokens-enabled] — включение или отключение конкретных правил проверки
[rules.indent] — настройка отступов: "auto" для автоопределения или конкретное число (например, 4)
[parser] и [rules.invalid-directive-context] — поддержка сторонних модулей (RTMP, Lua, Brotli)

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

Подавление предупреждений. Иногда срабатывание линтера обосновано, но в конкретной ситуации директива используется намеренно. nginx-lint позволяет подавить предупреждение через inline-комментарий # nginx-lint:ignore правило причина. Обязательно указывайте причину — через полгода будет понятно, почему предупреждение подавлено. Для проверки частичных конфигов из conf.d/ используйте флаг --context http,server, чтобы указать родительский контекст.

				
					# Установка из исходного кода
$ git clone https://github.com/walf443/nginx-lint.git
$ cd nginx-lint && cargo install --path .

# Запуск через Docker (проверка без установки)
$ TARGET_PATH=/etc/nginx/nginx.conf
$ docker run --rm \
    -v "$(dirname $TARGET_PATH):$(dirname $TARGET_PATH):ro" \
    ghcr.io/walf443/nginx-lint:latest "$TARGET_PATH"

# Базовые команды
$ nginx-lint /etc/nginx/nginx.conf          # проверка
$ nginx-lint --fix /etc/nginx/nginx.conf     # автоисправление
$ nginx-lint why server-tokens-enabled       # документация по правилу
$ nginx-lint -o json /etc/nginx/nginx.conf   # JSON для CI

# Настройка правил
$ nginx-lint config init      # создать .nginx-lint.toml
$ nginx-lint config validate  # проверить конфиг линтера

Практика: аудит конфигурации Nginx и интеграция в CI/CD

Рассмотрим проверку конфигурации Nginx на реальном примере. Типичный конфиг reverse proxy с SSL часто содержит неочевидные ошибки безопасности, которые nginx -t не обнаружит:

server-tokens-enabled — директива server_tokens on раскрывает версию Nginx в заголовках ответов и на страницах ошибок. Атакующий может использовать эту информацию для поиска известных уязвимостей конкретной версии сервера
autoindex-enabled — autoindex on в контексте http включает листинг директорий для всех виртуальных серверов. Это может привести к раскрытию структуры файловой системы и конфиденциальных файлов
alias-traversal — в блоке location /static/ значение alias /var/www/static без завершающего слэша потенциально позволяет выйти за пределы целевой директории через path traversal — запрос вида /static../etc/passwd
add-header-redefinition — директива add_header внутри location переопределяет все заголовки, установленные на уровне server. Это документированная особенность Nginx, которая часто становится источником ошибок безопасности — заголовок X-Frame-Options или Content-Security-Policy просто пропадает для запросов к этому location

nginx-lint находит все эти ошибки автоматически. Для правил с поддержкой автофикса достаточно запустить nginx-lint --fix — линтер исправит файл на месте. Например, server_tokens on будет заменён на server_tokens off, а в alias добавится недостающий завершающий слэш. Не все правила поддерживают автофикс — например, переопределение add_header требует понимания контекста и ручного аудита. Перед использованием --fix на рабочем сервере обязательно сделайте резервную копию конфигурации.

Команда nginx-lint why <правило> объясняет каждое правило с примерами плохой и хорошей конфигурации — полезно для понимания, зачем нужна та или иная проверка.

Интеграция в CI/CD. Для GitHub существует готовый action — nginx-lint-action. Он запускает проверку конфигурации Nginx при каждом Pull Request и добавляет аннотации прямо к изменённым строкам кода. Для GitLab CI и других систем используйте Docker-образ ghcr.io/walf443/nginx-lint:latest — он не требует установки Rust и работает в любой CI-среде с поддержкой Docker. Формат вывода -o github-actions генерирует аннотации к строкам кода, а -o json — структурированные данные для интеграции с системами мониторинга и тикет-системами.

Web UI. nginx-lint предоставляет браузерный интерфейс на WebAssembly для быстрой проверки сниппетов конфигурации без установки. Возможности Web UI: проверка конфигурации Nginx в реальном времени при вводе текста, интерактивные кнопки исправления для каждой найденной проблемы, кнопка «Fix All» для применения всех исправлений сразу, документация по правилам с примерами. Для локального запуска: nginx-lint web --open. Это удобно для демонстрации проблем коллегам и для предварительной проверки перед деплоем — аналог подхода, который мы описывали в статье о настройке Nginx для GLPI и OsTicket.

				
					# .github/workflows/nginx-lint.yml
name: Lint Nginx Config

on:
  pull_request:
    paths:
      - 'nginx/**'
      - '*.conf'

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: walf443/nginx-lint-action@v1
        with:
          files: nginx/nginx.conf

nginx-lint — основной линтер для проверки конфигурации Nginx

nginx-lint — современный линтер, написанный на Rust. Активная разработка: 680+ коммитов, 15 релизов, актуальная версия 0.10.0. Покрывает наибольшее количество категорий проверок среди всех доступных инструментов для аудита конфигурации Nginx.

Ключевые возможности: 30+ встроенных правил для аудита безопасности и лучших практик, автофикс ошибок настройки через --fix, расширение через WASM-плагины, Web UI на WebAssembly, встроенная документация через команду why, поддержка include-директив и glob-паттернов. Форматы вывода: стандартный errorformat, JSON для CI, формат GitHub Actions для аннотаций в PR.

Дополнительно стоит отметить конфигурируемость: файл .nginx-lint.toml позволяет настроить каждое правило отдельно, задать допустимые протоколы SSL/TLS, добавить директивы сторонних модулей. Подавление предупреждений реализовано через inline-комментарии с обязательным указанием причины — что помогает поддерживать прозрачность решений в команде.

Gixy — анализатор безопасности Nginx от Яндекса

Gixy — статический анализатор конфигураций Nginx от Яндекса. Ориентирован исключительно на поиск уязвимостей безопасности: HTTP Request Splitting, SSRF через переменные Nginx, переопределение заголовков через add_header, проблемы с директивами alias и try_files, а также небезопасное использование if.

Установка через pip install gixy. Проект фактически не обновляется — последний релиз вышел несколько лет назад. Официально поддерживаются только устаревшие версии Python (2.7, 3.5–3.7). Не проверяет стиль, устаревшие директивы, не умеет исправлять ошибки автоматически. Тем не менее, для аудита специфических уязвимостей безопасности Gixy по-прежнему полезен — его правила дополняют nginx-lint в части HTTP-splitting и SSRF-уязвимостей. Ищите актуальные форки с поддержкой новых версий Python в разделе Forks репозитория.

Сравнительная таблица линтеров для проверки конфигурации Nginx

Сводная таблица по четырём инструментам — ключевые характеристики для выбора линтера:

Характеристика	nginx -t	Gixy	nginx-lint	nginx-linter
Язык	C (часть Nginx)	Python	Rust	Node.js
Синтаксис	Да	Нет	Да	Да
Безопасность	Нет	Да	Да	Частично
Best Practices	Нет	Частично	Да	Да
Устаревшие директивы	Нет	Нет	Да	Нет
Автофикс	Нет	Нет	Да	Нет
Web UI	Нет	Нет	Да	Нет
Docker	—	Да	Да	Нет
CI/CD интеграция	Ручная	Ручная	GitHub Actions, JSON	Ручная
Кол-во правил	—	~7	30+	~8
Плагины	Нет	Нет	WASM	Нет
Поддержка	Активная	Заброшен	Активная	Редкая

Какой линтер выбрать: рекомендации по сценариям

Выбор инструмента зависит от задачи, инфраструктуры и зрелости процессов. Наши рекомендации для типичных сценариев:

Быстрая проверка перед nginx reload

Запустите nginx -t для проверки синтаксиса, затем nginx-lint для аудита безопасности и лучших практик. Этот порядок предотвращает и синтаксические ошибки, и проблемы с настройками безопасности. Минимальное вложение времени — несколько секунд на проверку конфигурации Nginx — которое предотвращает реальные инциденты на рабочем сервере.

Полный аудит безопасности конфигурации Nginx

Используйте nginx-lint как основной инструмент — 30+ правил покрывают большинство категорий ошибок безопасности и лучших практик. Для дополнительной проверки на SSRF-уязвимости и HTTP Request Splitting запустите Gixy. Два линтера дополняют друг друга и обеспечивают наиболее полную проверку конфигурации Nginx.

Автоматизация в CI/CD pipeline

nginx-lint — единственный линтер с нативной поддержкой CI/CD. Используйте nginx-lint-action для GitHub или Docker-образ для GitLab CI. Формат -o json подходит для интеграции с любой системой автоматизации.

Разовая проверка без установки

Откройте Web UI nginx-lint в браузере — проверка конфигурации Nginx работает полностью на стороне клиента через WebAssembly. Удобно для быстрой проверки сниппетов и для демонстрации проблем коллегам.

Заключение

Автоматическая проверка конфигурации Nginx — не замена ручному аудиту, а его дополнение. Линтеры позволяют отлавливать типичные ошибки безопасности ещё до того, как они попадут на рабочий сервер: устаревшие протоколы, раскрытие версии, небезопасные alias-пути, переопределение заголовков.

Gixy от Яндекса полезен для аудита специфических уязвимостей, но проект не развивается. nginx-lint активно обновляется, покрывает больше категорий ошибок и предлагает автофикс — что делает его основным инструментом для регулярной проверки конфигурации Nginx. Встройте линтер в pre-commit hook, CI/CD pipeline или запускайте вручную перед каждым nginx -s reload.

Проверка конфигурации Nginx — часть нашей работы по администрированию серверов. Берём на себя полный цикл: от настройки линтера и аудита безопасности до круглосуточного мониторинга и оперативного реагирования.

Обсудить задачу

Часто задаваемые вопросы (FAQ)

Ответы на частые вопросы о проверке конфигурации Nginx и инструментах для аудита.

Чем nginx-lint отличается от nginx -t?

nginx -t проверяет только синтаксис конфигурации — скобки, точки с запятой, допустимость имён директив. nginx-lint проводит полноценный аудит: находит ошибки безопасности (server_tokens, устаревшие SSL-протоколы, alias traversal), устаревшие директивы (ssl on), нарушения лучших практик (autoindex в продакшене, переопределение add_header) — всего 30+ правил. Это разные уровни проверки конфигурации Nginx, и оба инструмента рекомендуется использовать совместно: сначала nginx -t для синтаксиса, затем nginx-lint для аудита безопасности.

Можно ли использовать Gixy в 2026 году?

Gixy по-прежнему работает для проверки безопасности (HTTP-splitting, SSRF, alias traversal), но проект заброшен — не обновляется и не поддерживает новые версии Python. Рекомендуем использовать nginx-lint как основной линтер, а Gixy — как дополнительный инструмент. Ищите актуальные форки в разделе Forks репозитория.

Как встроить проверку конфигурации Nginx в CI/CD?

Для GitHub используйте nginx-lint-action — готовый action, который автоматически запускает проверку конфигурации Nginx и добавляет аннотации прямо к строкам кода в Pull Request. Для GitLab CI и других систем — Docker-образ ghcr.io/walf443/nginx-lint:latest, который не требует установки Rust. Формат вывода -o json генерирует структурированные данные для интеграции с системами мониторинга и тикет-системами. Формат -o github-actions создаёт аннотации в формате GitHub Workflow Commands.

Поддерживает ли nginx-lint сторонние модули Nginx?

Да. В файле .nginx-lint.toml можно указать дополнительные директивы в секциях [rules.invalid-directive-context] и [parser], чтобы линтер не выдавал ложных предупреждений для модулей RTMP, Lua, Brotli и других. Создайте конфиг командой nginx-lint config init и адаптируйте под свою инфраструктуру.

Безопасно ли использовать автофикс nginx-lint на рабочем сервере?

Флаг –fix изменяет файлы конфигурации на месте. Перед использованием на рабочем сервере обязательно сделайте резервную копию конфигурации. Рекомендуемый порядок: сначала запустите проверку без –fix и изучите список найденных проблем, затем примените исправления, после чего обязательно выполните nginx -t для проверки синтаксиса. Не все правила поддерживают автофикс — например, переопределение add_header требует понимания контекста и ручного аудита настроек.