small-light: Модуль динамической трансформации изображений для NGINX

Установка

Вы можете установить этот модуль в любой дистрибутив на базе RHEL, включая, но не ограничиваясь:

RedHat Enterprise Linux 7, 8, 9 и 10
CentOS 7, 8, 9
AlmaLinux 8, 9
Rocky Linux 8, 9
Amazon Linux 2 и Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 и Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-small-light

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-small-light

Включите модуль, добавив следующее в начало файла /etc/nginx/nginx.conf:

load_module modules/ngx_http_small_light_module.so;

Этот документ описывает nginx-module-small-light v0.9.4, выпущенный 27 мая 2020 года.

Динамический модуль трансформации изображений для nginx.

Начало работы

Добавьте приведённую ниже конфигурацию в некоторый контекст сервера в nginx.conf и запустите nginx.

small_light on;
location ~ small_light[^/]*/(.+)$ {
    set $file $1;
    rewrite ^ /$file;
}

Если вы можете получить оригинальное изображение image.jpg по следующему URL,

http://$host:$port/img/image.jpg

Вы сможете получить преобразованное изображение image.jpg по следующему URL.

http://$host:$port/small_light(dw=300,dh=300)/img/image.jpg

Часть small_light(...) называется функцией small_light.

Пример конфигурации

Ниже приведён пример конфигурации.

server {
    listen 8000;
    server_name localhost;

    small_light on;
    small_light_pattern_define msize dw=500,dh=500,da=l,q=95,e=imagemagick,jpeghint=y;
    small_light_pattern_define ssize dw=120,dh=120,da=l,q=95,e=imlib2,jpeghint=y;

    # http://localhost:8000/small_light(p=msize)/img/filename.jpg -> генерировать изображение msize
    # http://localhost:8000/small_light(p=ssize)/img/filename.jpg -> генерировать изображение ssize
    # http://localhost:8000/small_light(of=gif,q=100)/img/filename.jpg -> генерировать gif изображение с качеством 100
    location ~ small_light[^/]*/(.+)$ {
        set $file $1;
        rewrite ^ /$file;
    }
}

Директивы

small_light

Синтаксис	small_light on \| off
По умолчанию	off
Контекст	server, location

Эта директива устанавливает, включена ли обработка изображений с помощью ngx_small_light в контексте сервера.

small_light_getparam_mode

Синтаксис	small_light_getparam_mode on \| off
По умолчанию	off
Контекст	server, location

Эта директива устанавливает, включено ли преобразование изображений с помощью GET параметров вместо функции small_light (например, /small_light(dw=200,dh=200)). В этом случае функция small_light отключена. Но вам нужно установить обе директивы small_light и small_light_getparam_mode on, чтобы включить эту функцию.

small_light_material_dir

Синтаксис	small_light_material_dir path
По умолчанию
Контекст	server

Эта директива назначает директорию для встроенных иконок изображений.

small_light_pattern_define

Синтаксис	small_light_pattern_define pattern_name parameters
По умолчанию
Контекст	server

Эта директива задаёт имя параметров, разделённых запятыми.

small_light_radius_max

Синтаксис	small_light_radius_max number
По умолчанию	10
Контекст	server, location

Эта директива устанавливает максимальное значение радиуса геометрии для sharpen, unsharp и blur.

small_light_sigma_max

Синтаксис	small_light_sigma_max number
По умолчанию	10
Контекст	server, location

Эта директива устанавливает максимальное значение сигмы геометрии для sharpen, unsharp и blur.

small_light_imlib2_temp_dir

Синтаксис	small_light_imlib2_temp_dir path [level1 [level2 [level 3 ]]]
По умолчанию	small_light_imlib2_temp 1 2
Контекст	server

Эта директива назначает директорию для временных файлов для обработки Imlib2. Эта директива доступна, когда Imlib2 включен.

small_light_buffer

Синтаксис	small_light_buffer size
По умолчанию	1m
Контекст	server

Эта директива устанавливает максимальный размер буфера, используемого для чтения изображений, когда Content-Length не установлен в заголовках ответа.

Параметры для функции small_light

Параметр	Тип	По умолчанию	Описание
p	string		именованный шаблон параметров, разделённых запятыми
e	string	imagemagick	имя движка (imagemagick, imlib2, gd)
q	number		качество
of	string		формат вывода (jpg, gif, png, webp)
jpeghint	char	n	включить подсказку JPEG (y, n)
dw	coord	sw	ширина назначения
dh	coord	sh	высота назначения
dx	coord	sx	координата x назначения
dy	coord	sy	координата y назначения
da	char	l	управление соотношением сторон назначения (l, s, n)
ds	char	n	управление масштабированием назначения (s, n)
cw	number		ширина холста
ch	number		высота холста
cc	color	000000	цвет холста
bw	number		ширина границы
bh	number		высота границы
bc	color	000000	цвет границы
sw	coord		ширина источника
sh	coord		высота источника
sx	coord		координата x источника
sy	coord		координата y источника
pt	char	n	управление проходом (y, n)
sharpen	string		радиус, сигма (например, 10x5)
unsharp	string		радиус, сигма, количество, порог (например, 2x5+0.5+0)
blur	string		радиус, сигма (например, 5x10)
embedicon	string		встроенный файл иконки в `small_light_material_dir`
ix	number	0	координата x встроенной иконки
iy	number	0	координата y встроенной иконки
angle	number	0	угол поворота (90, 180, 270)
progressive	char	n	сделать JPEG прогрессивным (y, n)
cmyk2rgb	char	n	конвертировать цветовое пространство из CMYK в sRGB (y, n)
rmprof	char	n	удалить профиль (y, n)
autoorient	char	n	включить автоматическую корректировку ориентации изображения (y, n)

Значения da - это l, s и n. Они имеют следующие значения.

l: основано на длинной стороне
s: основано на короткой стороне
n: нет

Ниже приведены некоторые ограничения.

of=gif и of=webp не поддерживаются, когда e=imlib2.
autoorient доступен в ImageMagick-6.9.0 или более поздних версиях.
Значение radius,sigma для sharpen, unsharp и blur ограничено small_light_radius_max и small_light_sigma_max.

Ниже приведены типы каждого параметра.

Тип	Описание
coord	координата или пиксель. процент при добавлении 'p'
char	символ
number	целое число
color	rrggbb или rrggbbaa
string	string

Использование GET параметров

ngx_small_light поддерживает преобразование изображений не только с помощью функции small_light, но и с помощью GET параметров в v0.5.0 или более поздних версиях. Вам нужно установить обе директивы small_light и small_light_getparam_mode on, чтобы включить эту функцию. При этом функция small_light (например, /small_light(dw=300,dh=300)/img.jpg) отключается.

small_light on;
small_light_getparam_mode on;

В приведённой выше конфигурации URL ниже не возвращает преобразованное изображение.

http://localhost:8000/small_light(dw=200,dh=200)/img/image.jpg

Вместо этого URL ниже возвращает ожидаемое преобразованное изображение.

http://localhost:8000/img/image.jpg?dw=200&dh=200

Включение трансформации WebP

ngx_small_light поддерживает трансформацию WebP с помощью ImageMagick и GD. Указав of=webp для функции small_light, ngx_small_light преобразует формат изображения в WebP. Но ImageMagick требует libwebp, а GD требует libvpx. Вам нужно встроить эти библиотеки при сборке ImageMagick и GD для включения трансформации WebP.

Если трансформация WebP недоступна, nginx выводит строку, подобную следующей, в error.log при обработке изображения с of=webp.

WebP is not supported

Если трансформация WebP с помощью ImageMagick доступна, вывод команды convert -list format включает строку, подобную следующей.

$ convert -list format | grep -i webp
     WEBP* WEBP      rw-   WebP Image Format (libwebp 0.5.0[0208])

Если трансформация WebP с помощью GD доступна, вывод команды gdlib-config --libs включает -lvpx.

Как правило, пакеты ImageMagick и GD, предоставляемые дистрибутивами Linux, такими как Ubuntu и CentOS, по умолчанию не встраивают библиотеку для трансформации WebP. В таких случаях вам нужно собрать ImageMagick или GD самостоятельно.

Советы по оптимизации

Существует несколько советов по оптимизации для ngx_small_light.

Подсказка JPEG

Когда формат вывода - JPEG, а движок преобразования изображений - ImageMagick или Imlib2, вы можете указать jpeghint=y. Скорость обработки изображений значительно увеличивается.

Ограничение числа потоков с OpenMP

Когда движок преобразования изображений - ImageMagick, а версия ngx_small_light ниже v0.6.14, настоятельно рекомендуется установить 1 для OMP_NUM_THREADS или MAGICK_THREAD_LIMIT в nginx.conf. Поскольку OpenMP включен в ImageMagick по умолчанию, ImageMagick с включённым OpenMP работает очень медленно в многопроцессорной среде.

env OMP_NUM_THREADS=1; # или env MAGICK_THREAD_LIMIT=1;

Или вы можете избежать этой проблемы, собрав ImageMagick с --disable-openmp.

В версиях v0.6.14 и более поздних это больше не требуется. Поскольку ngx_small_light всегда устанавливает количество потоков с OpenMP равным 1.

Ограничения

ngx_small_light имеет следующие ограничения.

Не поддерживаемые функции с Imlib2

Преобразование с помощью Imlib2 не поддерживает запись GIF-изображений. Поскольку Imlib2 имеет функцию для загрузки GIF-изображений, но не имеет функции для сохранения. Кроме того, преобразование с помощью Imlib2 не поддерживает запись и чтение WebP-изображений. Поэтому of=gif и e=imlib2 не могут быть указаны одновременно. Если они указаны, ngx_small_light возвращает 415 (Unsupported Media Type).

Не поддерживаемые функции с GD

Преобразование с помощью GD поддерживает запись WebP-изображений. Но это экспериментальная функция.

Не поддерживаемый анимированный GIF

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

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

Запуск тестов

perl Build.PL
cpanm --installdeps .
NGINX_BIN=${nginx_prefix_dir}/sbin/nginx ./Build test
## или
NGINX_BIN=${nginx_prefix_dir}/sbin/nginx prove t/**/*.t

GitHub

Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-small-light.