Brotli в Nginx: сборка и настройка на Ubuntu

В этой инструкции показано, как собрать пакет Nginx с модулем ngx_brotli на Ubuntu (пример на 18.04), включить Brotli в конфигурации и проверить работу. Пошагово: добавить репозиторий Nginx, скачать исходники, подключить ngx_brotli, собрать .deb, установить пакет, настроить виртуальный хост и протестировать. Также приведены чек-листы, советы по отладке и примечания по безопасности.

О чём статья

• Основная цель: добавить поддержку Brotli в Nginx сборкой с ngx_brotli.
• Подходит для Ubuntu (пример 18.04) и может быть адаптировано для Debian.
• Включены тесты, отладка, рекомендации по безопасности и альтернативные подходы.

Краткие варианты использования

• Быстрое улучшение размера ответов статики (CSS, JS, HTML).
• Подходит для сайтов с HTTPS (Brotli работает через TLS).
• Альтернатива: использовать gzip, CDN с Brotli или динамические модули поставщика пакетов.

Предварительные требования

• Ubuntu 18.04 (пример). Позже версии обычно совместимы, но проверяйте зависимости.
• Права root или sudo.
• Доступ в интернет для загрузки репозиториев и исходников.

Что мы сделаем

1. Установим зависимости для сборки.
2. Добавим репозиторий Nginx, скачиваем исходники и ngx_brotli.
3. Изменим правила сборки, подключим ngx_brotli и соберём .deb пакеты.
4. Установим Nginx, включим Brotli и настроим виртуальный хост.
5. Протестируем работу и приведём сценарии отладки.

Шаг 1 — Установить зависимости для сборки

Обновите репозитории и установите необходимые пакеты:

sudo apt update
sudo apt install dpkg-dev build-essential zlib1g-dev libpcre3 libpcre3-dev unzip

Подождите, пока все пакеты будут установлены.

Шаг 2 — Установка Nginx с ngx_brotli

Мы соберём кастомный пакет Nginx, чтобы встроить ngx_brotli. В примере используется официальный репозиторий nginx.org.

Добавление репозитория Nginx

Добавьте ключ подписи и создайте файл репозитория:

curl -L https://nginx.org/keys/nginx_signing.key | sudo apt-key add -

Откройте редактор и создайте /etc/apt/sources.list.d/nginx.list:

vim /etc/apt/sources.list.d/nginx.list

Вставьте:

deb http://nginx.org/packages/ubuntu/ bionic nginx
deb-src http://nginx.org/packages/ubuntu/ bionic nginx

Сохраните и выполните обновление:

sudo apt-get update

Скачивание исходных файлов Nginx и ngx_brotli

Перейдите в /usr/local/src и скачайте исходники Nginx, затем установите зависимости для сборки:

cd /usr/local/src
sudo apt source nginx
sudo apt build-dep nginx -y

Клонируйте ngx_brotli из GitHub (рекурсивно):

git clone --recursive https://github.com/google/ngx_brotli.git

После этого у вас должны быть каталоги с исходниками nginx и ngx_brotli.

Сборка Nginx с поддержкой ngx_brotli

Отредактируйте Debian-правила для сборки, чтобы добавить модуль ngx_brotli.

cd /usr/local/src/nginx-*/
vim debian/rules

Найдите блоки config.env.nginx и config.env.nginx_debug и добавьте в опции сборки:

--add-module=/usr/local/src/ngx_brotli

Сохраните и выйдите.

Запустите сборку пакета:

sudo dpkg-buildpackage -b -uc -us

Примечание по флагам:

• -b: собрать только бинарные пакеты (.deb).
• -uc, -us: не подписывать файлы сборки и исходные пакеты.

После завершения сборки вы увидите .deb-файлы в /usr/local/src.

ls -lah

Установка Nginx и включение Brotli

Установите сгенерированные .deb-пакеты:

cd /usr/local/src/
sudo dpkg -i *.deb

Теперь включите модуль в конфиге /etc/nginx/nginx.conf — в блоке http добавьте:

    brotli on;
    brotli_comp_level 6;
    brotli_static on;
    brotli_types text/plain text/css application/javascript application/x-javascript text/xml application/xml application/xml+rss text/javascript image/x-icon image/vnd.microsoft.icon image/bmp image/svg+xml;

Сохраните и проверьте конфигурацию:

nginx -t

Если ошибок нет, перезапустите Nginx:

systemctl restart nginx

Шаг 3 — Настройка виртуального хоста

Brotli работает только по HTTPS, поэтому убедитесь, что у вас есть SSL-сертификат (например, от Let’s Encrypt).

Создайте файл конфигурации conf.d/brotli.conf:

cd /etc/nginx/
vim conf.d/brotli.conf

Вставьте конфигурацию виртуального хоста (замените домен и пути к сертификатам):

# Redirect HTTP to HTTPS Nginx
server {
   listen 80;
    server_name nginx.hakase-labs.io;
    return 301 https://$host$request_uri;
}

# SSL configuration
server {
    listen 443 ssl http2;
    server_name nginx.hakase-labs.io;

    ssl_certificate /etc/letsencrypt/live/nginx.hakase-labs.io/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/nginx.hakase-labs.io/privkey.pem;

    # Improve HTTPS performance with session resumption
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 5m;

    # Enable server-side protection against BEAST attacks
    ssl_prefer_server_ciphers on;
    ssl_ciphers ECDH+AESGCM:ECDH+AES256:ECDH+AES128:DH+3DES:!ADH:!AECDH:!MD5;

    # Disable SSLv3
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;

    # web root directory
    location / {
    root /usr/share/nginx/html;
    }

}

Проверьте конфигурацию и перезапустите nginx:

nginx -t
systemctl restart nginx

Шаг 4 — Тестирование

Откройте сайт в браузере по HTTPS и в инструментах разработчика (Network) посмотрите Response headers — должна быть строка content-encoding: br. Пример для curl:

curl -H 'Accept-Encoding: br' -I https://nginx.hakase-labs.io

Вы увидите в ответе header: content-encoding: br.

Отладка и частые проблемы

• Ошибка при сборке: проверьте, установлены ли build-dep пакеты и правильно ли клонирован ngx_brotli с флагом –recursive.
• Nginx не запускается: проверьте nginx -t и логи в /var/log/nginx/error.log.
• Заголовок content-encoding не появляется: убедитесь, что запрос идёт по HTTPS и у клиента в Accept-Encoding есть br.
• Если brotli_static on, Nginx отдает готовые .br файлы, если они есть; иначе сжимает на лету.

Рекомендации по безопасности и приватности

• Компрессия и утечки: HTTP-компрессия может увеличить риск атак типа BREACH при отправке чувствительных данных в теле ответа. Минимальные меры:
  • Не включайте компрессию для ответов с чувствительными токенами или персональными данными.
  • Применяйте Content-Security-Policy и защиту от CSRF.
  • Для сессий используйте безопасные cookie и короткие таймауты.
• TLS: используйте современные протоколы (TLS 1.2/1.3) и сильные шифры. В конфиге выше показаны устаревшие строки для совместимости — обновите их в продакшне.

Альтернативные подходы

• Использовать готовый пакет с модулем Brotli (PPA или репозиторий с собранным модулем) — быстрее, но проверьте доверие к источнику.
• Применять Brotli на CDN (Cloudflare, Fastly) — самое простое и масштабируемое решение для статики.
• Заменить на gzip, если поддержка клиентов ограничена.

Когда этот подход не подходит

• Если вы не управляете сервером (shared hosting) и не можете собирать пакеты.
• Если приоритет — минимальная сложность и вы предпочитаете использовать CDN.
• Если вы обрабатываете много персональных данных в ответах без разделения и боитесь компрессионных атак.

Чек-листы

Чек-лист для системного администратора перед сборкой:

• Есть доступ root/sudo.
• Установлены build-essential, dpkg-dev и зависимости.
• Клонирован ngx_brotli рекурсивно.
• Внесены изменения в debian/rules.
• Протестирована конфигурация nginx -t.

Чек-лист для релиза в продакшен:

• Тесты на staging с реальными браузерами.
• Мониторинг SLO/SLI на латентность и ошибки.
• Проверки заголовков безопасности (HSTS, CSP).
• Бэкап конфигураций и быстрый план отката.

Критерии приёмки

• Nginx успешно запущен и устойчив после перезапуска.
• В ответах на HTTPS-запросы присутствует content-encoding: br при Accept-Encoding: br.
• Нет ошибок в nginx -t и логах ошибок за последние 10 минут работы.

Мини-руководство по откату (rollback)

1. Если служба не запускается после установки, выполните:

systemctl status nginx
journalctl -u nginx -n 200

2. Откат до предыдущего пакета .deb (если сохранили):

sudo dpkg -i /path/to/previous-nginx-version.deb
systemctl restart nginx

3. Если откат невозможен, замените конфиг на рабочую копию и перезапустите.

Полезные сценарии тестирования и приёмки

• Функциональный тест: curl как выше, проверить content-encoding.
• Производительный тест: сравнить размеры ответов при gzip и brotli для CSS/JS/HTML.
• Нагрузочный тест: убедиться, что CPU не растёт непропорционально при brotli_comp_level > 6.

Факты и рекомендации по настройкам

• brotli_comp_level: 4–6 — хороший компромисс между временем сжатия и размером. 11 даёт лучший сжатие, но сильнее нагружает CPU.
• brotli_static on: используйте для отдачи заранее сжатых файлов (.br), это снижает CPU.

Мермайд: простая схема принятия решения

flowchart TD
    A[Нужна поддержка Brotli?] --> B{У вас доступ к серверу?}
    B -- Да --> C{Можно собрать nginx?}
    B -- Нет --> D[Использовать CDN или готовый пакет]
    C -- Да --> E[Собрать nginx + ngx_brotli]
    C -- Нет --> D
    E --> F[Включить brotli в nginx.conf]
    F --> G[Тестирование: curl + браузер]

Совместимость и заметки по миграции

• Модуль ngx_brotli предназначен для сборки в nginx на уровне исходников. Для динамического модуля проверьте совместимость с версией nginx.
• При переходе с Ubuntu 18.04 на 20.04/22.04 проверьте версии библиотек (zlib, pcre) и при необходимости обновите зависимости.

Локальные альтернативы и подводные камни

• PPA-пакеты могут содержать уже собранный модуль, но источнику следует доверять.
• Некоторые сборки nginx от дистрибутивов (apt-get install nginx) уже содержат динамические модули; проверьте nginx -V на наличие ngx_brotli.

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

Поддерживает ли Brotli HTTP/2?

Да, Brotli работает поверх HTTPS и HTTP/2 — это механизм кодирования содержимого, независимый от транспорта.

Работает ли Brotli для всех типов файлов?

Обычно имеет смысл включать для текстовых типов (HTML, CSS, JS, XML). Для изображений и уже сжатых форматов (JPEG, PNG, WebP) нет выгоды.

Можно ли использовать Brotli на HTTP (без TLS)?

Практически все браузеры поддерживают Brotli только через HTTPS. Поэтому в продакшне Brotli полезен только для HTTPS.

Ссылки и ресурсы

• https://github.com/google/ngx_brotli
• Akamai, Cloudflare и Mozilla — статьи о производительности Brotli (поиск по сайту).
• https://www.babak.io/blog/

Краткое резюме

Brotli даёт более эффективное сжатие по сравнению с gzip и особенно полезен для текстовых ресурсов. Если вы управляете сервером, оптимальный путь — собрать Nginx с ngx_brotli или использовать CDN. Обязательно протестируйте и учтите возможные риски утечек через компрессию для чувствительных данных.

Примечания

• Замените nginx.hakase-labs.io на ваш домен и укажите актуальные пути к сертификатам.
• Обновите ssl_protocols и ssl_ciphers для соответствия текущим рекомендациям безопасности.