Zum Inhalt

small-light: Dynamisches Bildtransformation-Modul für NGINX

Installation

Sie können dieses Modul in jeder RHEL-basierten Distribution installieren, einschließlich, aber nicht beschränkt auf:

  • RedHat Enterprise Linux 7, 8, 9 und 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 und Amazon Linux 2023
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

Aktivieren Sie das Modul, indem Sie Folgendes an den Anfang von /etc/nginx/nginx.conf hinzufügen:

load_module modules/ngx_http_small_light_module.so;

Dieses Dokument beschreibt nginx-module-small-light v0.9.4, veröffentlicht am 27. Mai 2020.

Ein dynamisches Bildtransformation-Modul für nginx.

Erste Schritte

Fügen Sie die folgende Konfiguration in einen Serverkontext in nginx.conf ein und starten Sie nginx.

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

Wenn Sie das Originalbild von image.jpg unter der folgenden URL abrufen können,

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

werden Sie in der Lage sein, das konvertierte Bild von image.jpg unter der folgenden URL abzurufen.

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

Der Teil von small_light(...) wird als small_light-Funktion bezeichnet.

Konfigurationsbeispiel

Hier ist ein Konfigurationsbeispiel.

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 Bild generieren
    # http://localhost:8000/small_light(p=ssize)/img/filename.jpg -> ssize Bild generieren
    # http://localhost:8000/small_light(of=gif,q=100)/img/filename.jpg -> gif Bild mit Qualität 100 generieren
    location ~ small_light[^/]*/(.+)$ {
        set $file $1;
        rewrite ^ /$file;
    }
}

Direktiven

small_light

Syntax small_light on | off
Standard off
Kontext server, location

Diese Direktive legt fest, ob die Bildverarbeitung mit ngx_small_light in einem Serverkontext aktiviert ist.

small_light_getparam_mode

Syntax small_light_getparam_mode on | off
Standard off
Kontext server, location

Diese Direktive legt fest, ob die Bildkonvertierung über GET-Parameter anstelle der small_light-Funktion (z. B. /small_light(dw=200,dh=200)) aktiviert ist. In diesem Fall ist die small_light-Funktion deaktiviert. Sie müssen jedoch sowohl small_light als auch small_light_getparam_mode aktivieren, um die Funktion dieser Direktive zu aktivieren.

small_light_material_dir

Syntax small_light_material_dir path
Standard
Kontext server

Diese Direktive weist das Verzeichnis für eingebettete Symbolbilder zu.

small_light_pattern_define

Syntax small_light_pattern_define pattern_name parameters
Standard
Kontext server

Diese Direktive benennt durch Kommas getrennte Parameter.

small_light_radius_max

Syntax small_light_radius_max number
Standard 10
Kontext server,location

Diese Direktive legt den maximalen Radiuswert der Geometrie für sharpen, unsharp und blur fest.

small_light_sigma_max

Syntax small_light_sigma_max number
Standard 10
Kontext server,location

Diese Direktive legt den maximalen Sigmawert der Geometrie für sharpen, unsharp und blur fest.

small_light_imlib2_temp_dir

Syntax small_light_imlib2_temp_dir path [level1 [level2 [level 3 ]]]
Standard small_light_imlib2_temp 1 2
Kontext server

Diese Direktive weist das Verzeichnis für temporäre Dateien für die Imlib2-Verarbeitung zu. Diese Direktive ist verfügbar, wenn Imlib2 aktiviert ist.

small_light_buffer

Syntax small_light_buffer size
Standard 1m
Kontext server

Diese Direktive weist die maximale Größe des Puffers zu, der zum Lesen von Bildern verwendet wird, wenn der Content-Length-Header in den Antwort-Headern nicht gesetzt ist.

Parameter für die small_light-Funktion

Parameter Typ Standard Beschreibung ImageMagick Imlib2 GD
p string benannter Muster von durch Kommas getrennten Parametern ⭕ ⭕ ⭕
e string imagemagick Engine-Name (imagemagick, imlib2, gd)
q number Qualität ⭕ ⭕ ⭕
of string Ausgabeformat (jpg, gif, png, webp) ⭕ ⭕ ⭕
jpeghint char n JPEG-Hinweis aktivieren (y, n) ⭕ ⭕ ❌
dw coord sw Zielbreite ⭕ ⭕ ⭕
dh coord sh Zielhöhe ⭕ ⭕ ⭕
dx coord sx Ziel-x-Koordinate ⭕ ⭕ ⭕
dy coord sy Ziel-y-Koordinate ⭕ ⭕ ⭕
da char l Ziel-Seitenverhältnissteuerung (l, s, n) ⭕ ⭕ ⭕
ds char n Ziel-Skalierungssteuerung (s, n) ⭕ ⭕ ⭕
cw number Leinwandbreite ⭕ ⭕ ⭕
ch number Leinwandhöhe ⭕ ⭕ ⭕
cc color 000000 Leinwandfarbe ⭕ ⭕ ⭕
bw number Rahmenbreite ⭕ ⭕ ⭕
bh number Rahmenhöhe ⭕ ⭕ ⭕
bc color 000000 Rahmenfarbe ⭕ ⭕ ⭕
sw coord Quellbreite ⭕ ⭕ ⭕
sh coord Quellhöhe ⭕ ⭕ ⭕
sx coord Quell-x-Koordinate ⭕ ⭕ ⭕
sy coord Quell-y-Koordinate ⭕ ⭕ ⭕
pt char n Durchlaufsteuerung (y, n) ⭕ ⭕ ⭕
sharpen string Radius,Sigma (z. B. 10x5) ⭕ ⭕ ⭕
unsharp string Radius,Sigma,Menge,Schwellenwert (z. B. 2x5+0.5+0) ⭕ ❌ ❌
blur string Radius,Sigma (z. B. 5x10) ⭕ ⭕ ❌
embedicon string Eingebettete Symboldatei in small_light_material_dir ⭕ ❌ ❌
ix number 0 Eingebettete Symbol-x-Koordinate ⭕ ❌ ❌
iy number 0 Eingebettete Symbol-y-Koordinate ⭕ ❌ ❌
angle number 0 Drehwinkel (90, 180, 270) ⭕ ⭕ ⭕
progressive char n JPEG progressiv machen (y, n) ⭕ ❌ ❌
cmyk2rgb char n Farbraum von CMYK nach sRGB konvertieren (y, n) ⭕ ❌ ❌
rmprof char n Profil entfernen (y, n) ⭕ ❌ ❌
autoorient char n Automatische Anpassung der Bildorientierung aktivieren (y, n) ⭕ ❌ ❌

Die Werte von da sind l, s und n. Diese haben die folgenden Bedeutungen.

  • l: basierend auf der langen Kante
  • s: basierend auf der kurzen Kante
  • n: nein

Es gibt einige Einschränkungen unten.

  • of=gif und of=webp werden nicht unterstützt, wenn e=imlib2.
  • autoorient ist ab ImageMagick-6.9.0 oder später verfügbar.
  • Der Wert von radius,sigma für sharpen, unsharp und blur ist durch small_light_radius_max und small_light_sigma_max begrenzt.

Hier sind die Typen jedes Parameters.

Typ Beschreibung
coord Koordinate oder Pixel. Prozent, wenn 'p' angehängt wird
char Zeichen
number Ganzzahl
color rrggbb oder rrggbbaa
string string

Verwendung von GET-Parametern

ngx_small_light unterstützt die Bildkonvertierung nicht nur durch die small_light-Funktion, sondern auch durch GET-Parameter in v0.5.0 oder später. Sie müssen sowohl small_light als auch small_light_getparam_mode aktivieren, um diese Funktion zu aktivieren. Im Gegenzug wird die small_light-Funktion (z. B. /small_light(dw=300,dh=300)/img.jpg) deaktiviert.

small_light on;
small_light_getparam_mode on;

In der obigen Konfiguration gibt die folgende URL kein konvertiertes Bild zurück.

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

Stattdessen gibt die folgende URL das erwartete konvertierte Bild zurück.

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

Aktivierung der WebP-Transformation

ngx_small_light unterstützt die WebP-Transformation mit ImageMagick und GD. Wenn of=webp an die small_light-Funktion übergeben wird, wandelt ngx_small_light das Bildformat in WebP um. Aber ImageMagick benötigt libwebp und GD benötigt libvpx. Sie müssen diese Bibliotheken beim Erstellen von ImageMagick und GD einbinden, um die WebP-Transformation zu aktivieren.

Wenn die WebP-Transformation nicht verfügbar ist, gibt nginx in der error.log eine Zeile wie die folgende aus, während es ein Bild mit of=webp verarbeitet.

WebP wird nicht unterstützt

Wenn die WebP-Transformation mit ImageMagick verfügbar ist, enthält die Ausgabe von convert -list format eine Zeile wie die folgende.

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

Wenn die WebP-Transformation mit GD verfügbar ist, enthält die Ausgabe von gdlib-config --libs -lvpx.

Im Allgemeinen enthalten die von den Linux-Distributionen bereitgestellten Pakete von ImageMagick und GD, wie Ubuntu und CentOS, standardmäßig nicht die Bibliothek für die WebP-Transformation. In solchen Fällen müssen Sie ImageMagick oder GD selbst erstellen.

Optimierungstipps

Hier sind einige Optimierungstipps für ngx_small_light.

JPEG-Hinweis

Wenn das Ausgabeformat JPEG ist und die Bildkonvertierungs-Engine ImageMagick oder Imlib2 ist, können Sie jpeghint=y angeben. Die Geschwindigkeit der Bildverarbeitung wird erheblich verbessert.

Thread-Anzahl mit OpenMP begrenzen

Wenn die Bildkonvertierungs-Engine ImageMagick ist und die Version von ngx_small_light niedriger als v0.6.14 ist, wird dringend empfohlen, 1 für OMP_NUM_THREADS oder MAGICK_THREAD_LIMIT in nginx.conf anzugeben. Da OpenMP standardmäßig in ImageMagick aktiviert ist und ImageMagick mit aktiviertem OpenMP in einer Multi-Prozess-Umgebung sehr langsam ist.

env OMP_NUM_THREADS=1; # oder env MAGICK_THREAD_LIMIT=1;

Alternativ können Sie dieses Problem umgehen, indem Sie ImageMagick mit --disable-openmp erstellen.

In v0.6.14 oder später sind sie nicht mehr erforderlich, da ngx_small_light die Thread-Anzahl mit OpenMP immer auf 1 setzt.

Einschränkungen

ngx_small_light hat die folgenden Einschränkungen.

Nicht unterstützte Funktionen mit Imlib2

Die Transformation mit Imlib2 unterstützt nicht das Schreiben von GIF-Bildern. Da Imlib2 die Funktion zum Laden von GIF-Bildern hat, jedoch nicht die Funktion zum Speichern. Darüber hinaus unterstützt die Transformation durch Imlib2 nicht das Schreiben und Lesen von WebP-Bildern. Daher können of=gif und e=imlib2 nicht gleichzeitig angegeben werden. Wenn diese angegeben werden, gibt ngx_small_light 415 (Unsupported Media Type) zurück.

Nicht unterstützte Funktionen mit GD

Die Transformation mit GD unterstützt das Schreiben von WebP-Bildern. Aber es ist eine experimentelle Funktion.

Nicht unterstützte animierte GIFs

ngx_small_light unterstützt nicht die Transformation von animierten GIFs, die Animationen beibehalten. Da es lange dauert, animierte GIFs zu transformieren (z. B. zu skalieren, zuzuschneiden). Daher ist es nicht realistisch, dass ngx_small_light animierte GIFs unterstützt.

Wenn das animierte GIF übergeben wird, transformiert ngx_small_light nur den ersten Frame.

Tests ausführen

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

GitHub

Sie finden zusätzliche Konfigurationstipps und Dokumentationen für dieses Modul im GitHub-Repository für nginx-module-small-light.