ngx_pagespeed для Nginx на Ubuntu 20.04

Что такое ngx_pagespeed и зачем он нужен

ngx_pagespeed — это модуль для Nginx, разработанный сообществом (оригинально Google PageSpeed), который оптимизирует контент на лету: минификация, объединение ресурсов, оптимизация изображений и кэширование. Коротко:

• ngx_pagespeed ускоряет загрузку страниц за счёт автоматических преобразований.
• PSOL (PageSpeed Optimization Library) — бинарная библиотека, необходимая модулю.

Важно: ngx_pagespeed — не панацея. Он удобен для быстрого внедрения оптимизаций, но часть задач лучше решать на этапе сборки/CI (оптимизация изображений, CSP, правильные заголовки).

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

• Сервер с Ubuntu 20.04.
• Домен, указывающий на IP сервера (в примерах — example.com).
• Доступ root или sudo.

Примечание: версии исходников Nginx и установленного пакета Nginx должны совпадать — иначе модуль не загрузится.

Подготовка системы и зависимости

Обновите пакеты:

apt-get update -y

Установите зависимости для сборки:

apt-get install dpkg-dev build-essential zlib1g-dev libpcre3 git libpcre3-dev unzip -y

Если планируете запускать сборку как непривилегированный пользователь, используйте sudo перед командами.

Установка Nginx (пакетный вариант)

Установим Nginx, если он ещё не стоит:

apt-get install nginx -y

Проверьте установленную версию:

nginx -v

Ожидаемый вывод в примере:

nginx version: nginx/1.18.0 (Ubuntu)

Запомните эту версию: для компиляции модуля потребуется исходник именно этой версии.

Загрузка исходников и ngx_pagespeed

1. Скачайте исходники Nginx той же версии. В примере используется 1.18.0:

wget http://nginx.org/download/nginx-1.18.0.tar.gz

2. Распакуйте архив:

tar -xvzf nginx-1.18.0.tar.gz

3. Склонируйте репозиторий ngx_pagespeed:

git clone https://github.com/apache/incubator-pagespeed-ngx.git

4. Перейдите в каталог и выберите стабильную ветку:

cd incubator-pagespeed-ngx
git checkout latest-stable

Вы увидите подсказку о detached HEAD — это нормально.

5. Посмотрите файл PSOL_BINARY_URL, чтобы узнать URL для PSOL:

cat PSOL_BINARY_URL

Пример содержимого:

https://dl.google.com/dl/page-speed/psol/1.13.35.2-$BIT_SIZE_NAME.tar.gz

6. Скачайте PSOL, подставив x64 или x86 в имя файла в зависимости от архитектуры:

wget https://dl.google.com/dl/page-speed/psol/1.13.35.2-x64.tar.gz

7. Распакуйте PSOL:

tar -xvzf 1.13.35.2-x64.tar.gz

Сборка динамического модуля ngx_pagespeed

1. Перейдите в каталог с исходниками Nginx (пример — /root/nginx-1.18.0):

cd /root/nginx-1.18.0

2. Установите дополнительные зависимости для сборки пакета Nginx из репозиториев Ubuntu и uuid-dev:

apt-get build-dep nginx
apt-get install uuid-dev

3. Запустите configure, указывая путь к каталогу incubator-pagespeed-ngx:

./configure --with-compat --add-dynamic-module=/root/incubator-pagespeed-ngx

Вы увидите сводку конфигурации, где указаны префиксы установки и используемые библиотеки.

4. Постройте модуль:

make modules

5. Скопируйте полученный файл модуля в каталог модулей Nginx (пример для пакета nginx из Ubuntu):

cp objs/ngx_pagespeed.so /usr/share/nginx/modules/

После этого модуль физически присутствует в системе.

Подключение ngx_pagespeed в конфигурации Nginx

1. Откройте основной конфигурационный файл Nginx:

nano /etc/nginx/nginx.conf

Добавьте в начало файла (перед остальной конфигурацией) строку загрузки модуля:

load_module modules/ngx_pagespeed.so;

Сохраните и закройте файл.

2. Создайте каталог для кэша PageSpeed и назначьте правильные права:

mkdir -p /var/ngx_pagespeed_cache
chown -R www-data:www-data /var/ngx_pagespeed_cache

3. Отредактируйте виртуальный хост по умолчанию:

nano /etc/nginx/sites-available/default

Замените содержимое (в примере) на следующие настройки. Обратите внимание, что server_name замените на ваш домен:

server {
     listen 80;
     server_name example.com; 

     root /var/www/html;
     index index.nginx-debian.html index.html index.htm;

     access_log   /var/log/nginx/access.log;
     error_log    /var/log/nginx/error.log;

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

     pagespeed on;
     pagespeed FileCachePath "/var/ngx_pagespeed_cache/";
     pagespeed RewriteLevel OptimizeForBandwidth;

     location ~ ".pagespeed.([a-z].)?[a-z]{2}.[^.]{10}.[^.]+" {
         add_header "" "";
     }

     location ~ "^/pagespeed_static/" { }
     location ~ "^/ngx_pagespeed_beacon$" { }
pagespeed RewriteLevel CoreFilters;

 }

Сохраните файл.

4. Проверьте конфигурацию Nginx:

nginx -t

Ожидаемый вывод:

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

5. Перезапустите Nginx:

systemctl restart nginx

Проверьте статус сервиса:

systemctl status nginx

Проверка установки

Проверьте, возвращает ли сервер заголовок X-Page-Speed:

curl -I -p http://example.com

Пример ответа:

HTTP/1.1 200 OK
Server: nginx/1.18.0 (Ubuntu)
Content-Type: text/html
Connection: keep-alive
Vary: Accept-Encoding
Date: Wed, 25 Nov 2020 11:58:56 GMT
X-Page-Speed: 1.13.35.2-0
Cache-Control: max-age=0, no-cache

Если вы видите заголовок X-Page-Speed, модуль активен и выполняет оптимизации.

Частые ошибки и способы их устранения

Важно: большинство проблем связано с несовпадением версий исходника Nginx и установленного пакета или с отсутствием PSOL.

• Ошибка загрузки модуля при старте Nginx: проверьте совместимость версий. Соберите модуль из исходников той же версии, что и установленный nginx -v.
• Пустой ответ или 500: посмотрите /var/log/nginx/error.log.
• Права на каталог кеша: убедитесь, что каталог /var/ngx_pagespeed_cache принадлежит www-data.
• PSOL не распакован или не совпадает по архитектуре: распакуйте правильный tar.gz (x64/x86).

Совет: для отладки включайте в конфигурации pagespeed LogDir и промежуточное логирование.

Откат и план восстановления

Если нужно быстро вернуть предыдущую конфигурацию:

1. Удалите строку load_module из /etc/nginx/nginx.conf или закомментируйте её.
2. Перезапустите Nginx:

systemctl restart nginx

3. Если модуль скопирован в каталог /usr/share/nginx/modules, можно переместить его в архив:

mv /usr/share/nginx/modules/ngx_pagespeed.so /root/

После отката проверьте работоспособность сайта и логов.

Альтернативные подходы к оптимизации

• Использовать построенные в CI инструменты для оптимизации изображений (mozjpeg, sharp, svgo) вместо on-the-fly оптимизаций.
• Применить Brotli/ gzip и правильные заголовки кеширования на уровне Nginx.
• CDN с функциями оптимизации (например, изображений) — сокращает нагрузку на сервер и улучшает доставку.
• Для Apache есть модуль mod_pagespeed; выбор зависит от веб-сервера.

Чек-лист администратора (роль-based)

• Проверить версию Nginx (nginx -v).
• Скачать исходники нужной версии.
• Склонировать incubator-pagespeed-ngx и скачать PSOL.
• Установить зависимости и собрать модуль.
• Скопировать ngx_pagespeed.so в каталог модулей.
• Добавить load_module и создать каталог кэша.
• Проверить nginx -t и перезапустить сервис.
• Проверить наличие заголовка X-Page-Speed.

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

• Nginx запускается без ошибок после добавления модуля (nginx -t и systemctl status nginx).
• Ответ на запрос содержит заголовок X-Page-Speed с версией PSOL.
• Каталог кэша создан и доступен пользователю процесса Nginx.
• Нет ошибок в /var/log/nginx/error.log, связанных с ngx_pagespeed.

Тестовые сценарии

1. Проверка заголовка:

curl -I http://example.com | grep X-Page-Speed

Ожидается: строка с X-Page-Speed.

2. Проверка статического ресурса, оптимизированного через pagespeed:

• Запросите URL ресурса с .pagespeed. в имени.
• Ожидается код 200 и корректное содержимое.

Безопасность и рекомендации по эксплуатации

• Не включайте экспериментальные фильтры без тестирования на стейджинге.
• Ограничьте размер кэша и следите за дисковым пространством.
• При использовании TLS убедитесь, что заголовки кеширования и HSTS настроены корректно.

Совместимость и миграция

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

Факто-бокс

• Пример версии Nginx в руководстве: 1.18.0.
• Пример PSOL: 1.13.35.2.
• Кэш PageSpeed по умолчанию хранится в /var/ngx_pagespeed_cache и должен быть доступен процессу Nginx.

Резюме

Вы собрали ngx_pagespeed как динамический модуль и подключили его в конфигурации Nginx. После проверки заголовка X-Page-Speed можно тестировать фильтры и поведение в реальном трафике. Если столкнётесь с проблемами, проверьте версию исходников, права на каталог кэша и логи.

Важно: перед внедрением в прод не забудьте провести нагрузочное и функциональное тестирование на стейджинге.

Если нужны готовые конфиги для HTTPS, примеры LogDir для pagespeed или playbook в Ansible — скажите, подготовлю.