dynamic-etag: NGINX-Modul zum Hinzufügen von ETag zu dynamischen Inhalten
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-dynamic-etag
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-dynamic-etag
Aktivieren Sie das Modul, indem Sie Folgendes am Anfang von /etc/nginx/nginx.conf hinzufügen:
load_module modules/ngx_http_dynamic_etag_module.so;
Dieses Dokument beschreibt nginx-module-dynamic-etag v0.3.0 veröffentlicht am 14. November 2026.
ETag für die Antworten, die Ihre Anwendung im laufenden Betrieb erzeugt.
NGINX fügt statischen Dateien ein ETag hinzu und nichts dem, was von PHP-FPM,
einer proxied Anwendung oder einem anderen Upstream kommt. Diese Seiten werden dann bei
jedem Besuch vollständig heruntergeladen, selbst wenn sich kein Byte geändert hat. Dieses Modul hasht den
Antwort-Body, sendet den Hash als ETag und beantwortet ein passendes
If-None-Match mit 304 Not Modified und ohne Body.
Es funktioniert mit jedem Upstream-Modul: proxy_pass, fastcgi_pass,
uwsgi_pass, scgi_pass, grpc_pass.
Synopsis
location ~ \.php$ {
dynamic_etag on;
fastcgi_pass unix:/run/php-fpm/www.sock;
include fastcgi_params;
}
$ curl -sI -X GET https://example.com/ | grep -i etag
ETag: "6f5902ac237024bdd0c176cb93063dc4"
$ curl -s -o /dev/null -w '%{http_code} %{size_download}\n' \
-H 'If-None-Match: "6f5902ac237024bdd0c176cb93063dc4"' https://example.com/
304 0
Funktionsweise
Das ETag muss im Antwort-Header stehen, und der Header wird vor dem
Body gesendet. Daher hält das Modul die Antwort zurück: Es sammelt den Body, während der
Upstream ihn liefert, hasht ihn vollständig (MD5) und sendet erst dann den Header,
nun mit dem ETag, gefolgt vom Body.
- Der Hash umfasst immer den gesamten Body, egal wie er ankommt: in einem Stück
oder in vielen, mit
proxy_bufferingan oder aus, aus dem Speicher oder aus einer temporären Datei, in die NGINX ihn ausgelagert hat. - Ein Body, der größer als
dynamic_etag_buffer_sizeist, erhält keinETagund wird unverändert weitergegeben. Es gibt nie einen partiellen Hash. - Bedingte Anfragen werden von NGINX selbst gegen das berechnete
ETagbeantwortet:If-None-Matcherhält ein304, ein fehlgeschlagenesIf-Matcherhält ein412. - Der Body wird vor der Komprimierung gehasht.
gzipund andere Komprimierungsfilter schwächen dann dasETagab (W/"..."), wie sie es auch bei statischen Dateien tun.
Direktiven
dynamic_etag
- Syntax:
dynamic_etag on | off | $variable - Standard:
off - Kontext:
http,server,location
Aktiviert das ETag für Upstream-Antworten. Bei einer Variable wird das ETag hinzugefügt,
wenn ihr Wert on ist; siehe Bedingte Verwendung.
dynamic_etag_types
- Syntax:
dynamic_etag_types mime-type ... - Standard:
text/html - Kontext:
http,server,location
Fügt das ETag zu Antworten mit den aufgelisteten MIME-Typen zusätzlich zu
text/html hinzu. Der spezielle Wert * entspricht jedem Typ.
dynamic_etag_strength
- Syntax:
dynamic_etag_strength strong | weak | $variable - Standard:
strong - Kontext:
http,server,location
Macht das generierte ETag stark ("...") oder schwach (W/"..."). Ein schwaches ETag
besagt, dass die Seite äquivalent ist, nicht byte-für-byte identisch. Bei einer Variable
ist das ETag schwach, wenn ihr Wert weak ist.
dynamic_etag_buffer_size
- Syntax:
dynamic_etag_buffer_size size - Standard:
1m - Kontext:
http,server,location
Der größte Antwort-Body, den das Modul zum Hashen im Speicher hält. Eine größere Antwort
wird ohne ETag gesendet, genau so, wie NGINX sie mit deaktiviertem Modul senden würde.
Welche Antworten erhalten ein ETag
All dies muss zutreffen:
- die Antwort kommt von einem Upstream (nicht von einer statischen Datei,
returnoder einer Fehlerseite: statische Dateien behandelt NGINX selbst); - ihr Status ist
200; - ihr Typ ist in
dynamic_etag_typesaufgelistet; - die Anfrage ist kein
HEAD(es gibt keinen Body zum Hashen); - der Body ist nicht leer und passt in
dynamic_etag_buffer_size; - der Upstream hat kein eigenes
ETaggesendet. Dieses wird beibehalten, und NGINX beantwortet bedingte Anfragen gegen dieses.
Hinweise
Die Seite muss gleich sein, um dasselbe ETag zu erhalten. Eine Seite, die einen
Zeitstempel, ein zufälliges Token oder eine pro Anfrage erzeugte Nonce einbettet, ändert sich bei jeder Anfrage,
und damit auch ihr Hash. Prüfen Sie mit:
diff <(curl -s https://example.com/) <(curl -s https://example.com/) && echo stable
Die Antwort wird gesendet, wenn sie vollständig ist. Der Client erhält das erste
Byte, sobald die Anwendung das letzte erzeugt hat. Bei einer gewöhnlichen Seite ist das
eine Verzögerung von wenigen Millisekunden; bei einer Antwort, die absichtlich streamt
(Fortschrittsausgabe, Server-Sent Events), lassen Sie dynamic_etag ausgeschaltet.
Eine Antwort, die der Upstream nicht zu Ende bringt, wird überhaupt nicht gesendet. Wenn
die Anwendung mitten auf der Seite abstürzt, erhält der Client eine geschlossene Verbindung, nicht eine halbe Seite
mit einem 200 und einem ETag.
Testen mit curl. curl -I sendet eine HEAD-Anfrage, die kein
ETag erhält. Verwenden Sie stattdessen curl -sI -X GET.
Bedingte Verwendung
Die Direktiven sind innerhalb von if nicht gültig. Verwenden Sie map:
map $request_uri $dyn_etag {
default on;
~^/checkout off;
~^/api/ off;
}
map $http_user_agent $etag_strength {
default strong;
~*legacybot weak;
}
server {
location / {
dynamic_etag $dyn_etag;
dynamic_etag_strength $etag_strength;
proxy_pass http://backend;
}
}