Nginx: сборка и установка PageSpeed на Debian 11

Схема взаимодействия модуля PageSpeed с Nginx и кэшированием

Введение

Google PageSpeed Module (ngx_pagespeed / mod_pagespeed) — открытый проект для оптимизации статических ресурсов на уровне веб-сервера. Модуль анализирует ответы сервера и применяет оптимизации: сжатие и минификацию HTML/CSS/JS, оптимизацию изображений, агрегацию ресурсов, управление кэшированием и т.д. В этой инструкции показано, как собрать динамический модуль ngx_pagespeed для Nginx на Debian 11 (Bullseye) и подключить его к уже установленному Nginx, не пересобирая и не заменяя существующий бинарник.

В этом руководстве используются термины:

ngx_pagespeed — модуль PageSpeed для Nginx.
PSOL — PageSpeed Optimization Library, бинарная библиотека, необходимая модулю.

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

Требования

Операционная система: Debian 11 (Bullseye)
Привилегии root или sudo
Доступ в интернет для загрузки исходников и зависимостей

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

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

sudo apt update

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

sudo apt install curl dpkg-dev build-essential zlib1g-dev git libpcre3 git libpcre3-dev unzip uuid-dev -y

Затем установите зависимости сборки для Nginx из репозиториев Debian:

sudo apt build-dep nginx -y

Примечание: если у вас системные ограничения (напр., корпоративный прокси), убедитесь, что wget/git могут получить доступ к указанным URL.

Проверка текущей версии Nginx

Чтобы собрать совместимый модуль, узнайте версию установленного Nginx:

nginx -v

Пример вывода (на вашей системе может быть другой номер):

nginx version: nginx/1.18.0

Если Nginx отсутствует, установите его из официального репозитория Debian:

sudo apt install nginx -y

Создайте временную переменную окружения с номером версии Nginx (замените на вашу версию):

export NG_VER=1.18.0

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

Создайте рабочую директорию и перейдите в неё:

mkdir -p /usr/src/nginx; cd /usr/src/nginx

Загрузите и распакуйте исходники Nginx указанной версии:

wget http://nginx.org/download/nginx-$NG_VER.tar.gz  
tar -xzvf nginx-$NG_VER.tar.gz

Клонируйте репозиторий модуля PageSpeed для Nginx:

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

Перейдите в директорию модуля и переключитесь на стабильную ветку:

cd incubator-pagespeed-ngx/  
git checkout latest-stable

Откройте файл PSOL_BINARY_URL для определения правильной ссылки на бинарную библиотеку PSOL:

cat PSOL_BINARY_URL

Вы увидите строку вида:

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

Установите архитектуру сервера в переменную (пример — 64‑бит):

export BIT_SIZE_NAME=x64

Скачайте и распакуйте PSOL (используйте ту же версию, что указана в PSOL_BINARY_URL):

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

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

Компиляция модуля Nginx Pagespeed

Перейдите в каталог исходников Nginx:

cd /usr/src/nginx/nginx-$NG_VER

Сконфигурируйте сборку с опцией динамического модуля для ngx_pagespeed. Эта команда также проверит наличие системных библиотек:

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

Ожидаемый вывод конфигурации (пример):

Configuration summary  
  + using system PCRE library  
  + OpenSSL library is not used  
  + using system zlib library  
  
  nginx path prefix: "/usr/local/nginx"  
  nginx binary file: "/usr/local/nginx/sbin/nginx"  
  nginx modules path: "/usr/local/nginx/modules"  
  nginx configuration prefix: "/usr/local/nginx/conf"  
  nginx configuration file: "/usr/local/nginx/conf/nginx.conf"  
  nginx pid file: "/usr/local/nginx/logs/nginx.pid"  
  nginx error log file: "/usr/local/nginx/logs/error.log"  
  nginx http access log file: "/usr/local/nginx/logs/access.log"  
  nginx http client request body temporary files: "client_body_temp"  
  nginx http proxy temporary files: "proxy_temp"  
  nginx http fastcgi temporary files: "fastcgi_temp"  
  nginx http uwsgi temporary files: "uwsgi_temp"  
  nginx http scgi temporary files: "scgi_temp"

Соберите модули (команда может занять время):

make modules

После успешной сборки модуль появится как объектный файл: objs/ngx_pagespeed.so. Проверить его наличие:

ls objs/ngx_pagespeed.so

Пример вывода (в примере размер ~19M):

-rwxr-xr-x 1 root root 19M Dec  8 21:44 objs/ngx_pagespeed.so

Если сборка выдала ошибки, внимательно проверьте вывод make — часто проблема в несовпадении версий библиотек или отсутствующем PSOL.

Установка модуля в текущий Nginx

Скопируйте собранный модуль в системную папку модулей Nginx (по умолчанию для Debian):

cp /usr/src/nginx/nginx-$NG_VER/objs/ngx_pagespeed.so /usr/share/nginx/modules

Создайте конфигурационный файл для загрузки модуля:

nano /usr/share/nginx/modules-available/ngx-pagespeed.conf

Вставьте:

load_module modules/ngx_pagespeed.so;

Сохраните и создайте символическую ссылку в каталог modules-enabled:

ln -s /usr/share/nginx/modules-available/ngx-pagespeed.conf /etc/nginx/modules-enabled/70-ngx-pagespeed.conf

Создайте файл конфигурации pagespeed.conf в /etc/nginx и добавьте базовые настройки:

nano /etc/nginx/pagespeed.conf

Вставьте (строки и отступы сохраните как есть):

pagespeed on;  
  
# Needs to exist and be writable by nginx.  Use tmpfs for best performance.  
pagespeed FileCachePath /var/ngx_pagespeed_cache;  
  
# Ensure requests for pagespeed optimized resources go to the pagespeed handler  
# and no extraneous headers get set.  
location ~ "\.pagespeed\.([a-z]\.)?[a-z]{2}\.[^.]{10}\.[^.]+" {  
  add_header "" "";  
}  
location ~ "^/pagespeed_static/" { }  
location ~ "^/ngx_pagespeed_beacon$" { }

Создайте каталог для кэша и установите владельца www-data:

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

Рекомендация: для лучшей производительности используйте tmpfs для FileCachePath, если у вас достаточно RAM. Это ускорит операции записи и чтения кэша.

Подключение модуля к виртуальному хосту

Чтобы включить PageSpeed на конкретном серверном блоке, подключите pagespeed.conf через include.

Откройте пример виртуального хоста:

nano /etc/nginx/sites-available/default

Внутри блока server { … } добавьте:

include /etc/nginx/pagespeed.conf;

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

nginx -t  
sudo systemctl restart nginx

Если nginx -t выдаёт ошибки, исправьте их перед перезапуском.

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

Проверьте заголовки HTTP с помощью curl:

curl -I https://domain.com/

В заголовках должна появиться строка X-Page-Speed, подтверждающая, что модуль работает:

HTTP/1.1 200 OK  
Server: nginx/1.18.0  
Content-Type: text/html  
Connection: keep-alive  
Date: Wed, 01 Dec 2021 22:02:52 GMT  
X-Page-Speed: 1.13.35.2-0  
Cache-Control: max-age=0, no-cache

Вывод curl с заголовком X-Page-Speed

Также проверьте через браузер: откройте сайт, выберите «Inspect» (Инспектировать) → Network → выберите ресурс и изучите заголовки ответов. После перезагрузки страницы вы увидите заголовки, связанные с PageSpeed.

Инструменты разработчика: заголовки ответа с PageSpeed

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

Модуль загружается без ошибок: nginx -t и systemctl status nginx в норме.
В ответах сервера присутствует заголовок X-Page-Speed с версией.
Директория /var/ngx_pagespeed_cache существует и принадлежит www-data.
Нет ошибок в error.log, связанных с ngx_pagespeed, PSOL или отсутствием прав.
Страницы корректно отображаются после включения (важно проверить JS/CSS на целевых страницах).

План отката (Rollback)

Если после включения возникли проблемы, выполните простые шаги отката:

Удалите симлинк из /etc/nginx/modules-enabled:

rm /etc/nginx/modules-enabled/70-ngx-pagespeed.conf

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

nginx -t  
sudo systemctl restart nginx

(Опционально) Верните старую копию pagespeed.conf или удалите /etc/nginx/pagespeed.conf, если она была создана только для теста.
Очистите кэш PageSpeed при необходимости:

rm -rf /var/ngx_pagespeed_cache/*

Чек-лист по ролям

Администратор (операции):

Обновить пакеты и установить зависимости.
Убедиться в наличии свободного места на /usr/src и /var.
Создать каталоги и установить права.

Разработчик (frontend):

Проверить, что минификация и конкатенация не ломают фронтенд.
Протестировать критические страницы и запросы API.

QA / тестировщик:

Прогнать автотесты UI и проверить загрузку статических ресурсов.
Проверить заголовки ответов и время отклика.

Быстрая шпаргалка команд

Обновить репозитории: sudo apt update
Установить зависимости: sudo apt install …
Проверить версию Nginx: nginx -v
Установить NG_VER: export NG_VER=1.18.0
Скачать исходники: wget http://nginx.org/download/nginx-$NG_VER.tar.gz
Склонировать PageSpeed: git clone https://github.com/apache/incubator-pagespeed-ngx.git
Скачать PSOL: wget https://dl.google.com/dl/page-speed/psol/1.13.35.2-$BIT_SIZE_NAME.tar.gz
Сконфигурировать: ./configure –with-compat –add-dynamic-module=../incubator-pagespeed-ngx
Собрать модули: make modules
Копировать модуль: cp objs/ngx_pagespeed.so /usr/share/nginx/modules
Подключить: ln -s /usr/share/nginx/modules-available/ngx-pagespeed.conf /etc/nginx/modules-enabled/70-ngx-pagespeed.conf
Проверить nginx: nginx -t
Перезапустить: sudo systemctl restart nginx
Проверить заголовки: curl -I https://domain.com/

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

Несовпадение версий Nginx: убедитесь, что NG_VER соответствует nginx -v. В противном случае используйте исходники той же версии.
Проблемы с PSOL: если сборка жалуется на отсутствие PSOL, убедитесь, что вы скачали и распаковали корректный tarball для вашей архитектуры.
Права на каталог кэша: если Nginx не может записать в /var/ngx_pagespeed_cache, проверьте владельца и права (chown www-data:www-data).
Модуль не загружается: проверьте /var/log/nginx/error.log и вывод systemctl status nginx. Частая причина — несоответствие ABI между бинарником и модулем.

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

CDN с функционалом оптимизации изображений и минификации (Cloudflare, Fastly) может заменить часть задач PageSpeed и снизить нагрузку на сервер.
Статическая оптимизация в CI/CD (минификация, оптимизация изображений, спрайты) хороша для предсказуемости и контроля версий.
Brotli/ gzip и HTTP/2/3 — дополнение к PageSpeed, которое улучшает доставку контента.

Когда PageSpeed не подходит: динамически генерируемый контент с сложной логикой может ломаться при агрессивной оптимизации; в таких случаях полезнее локально контролировать оптимизации в сборке фронтенда.

Краткая методология (микро‑workflow)

Подготовка окружения: установить зависимости и определить NG_VER.
Загрузить исходники Nginx и модуль PageSpeed, скачать PSOL.
Сконфигурировать сборку с –add-dynamic-module и собрать make modules.
Скопировать модуль, подключить через load_module и включить pagespeed.conf.
Протестировать, провести приемочные тесты и мониторинг.

Глоссарий (1 строка)

PSOL — библиотека оптимизации, используемая ngx_pagespeed для обработки ресурсов.
Dynamic module — модуль Nginx в формате .so, загружаемый в рантайме.

Заключение

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

Краткая сводка: