Zum Inhalt

zip: Streaming ZIP-Archivier 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-zip

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-zip

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

load_module modules/ngx_http_zip_module.so;

Dieses Dokument beschreibt nginx-module-zip v1.3.0, veröffentlicht am 04. Februar 2026.

mod_zip erstellt ZIP-Archive dynamisch. Es kann Komponentendateien von Upstream-Servern mit dem nativen Proxy-Code von nginx streamen, sodass der Prozess niemals mehr als ein paar KB RAM gleichzeitig benötigt, selbst beim Erstellen von Archiven, die (potenziell) Gigabyte groß sind.

mod_zip unterstützt eine Reihe von "modernen" ZIP-Funktionen, einschließlich großer Dateien, UTC-Zeitstempel und UTF-8-Dateinamen. Es ermöglicht Clients, große Downloads mit den "Range"- und "If-Range"-Headern fortzusetzen, obwohl diese Funktion erfordert, dass der Server die Dateiprüfziffern (CRC-32) im Voraus kennt. Siehe "Verwendung" für Details.

Um Dateien im laufenden Betrieb zu entpacken, schauen Sie sich das nginx-unzip-module an.

Verwendung

Das Modul wird aktiviert, wenn die ursprüngliche Antwort (vermutlich von einem Upstream) den folgenden HTTP-Header enthält:

X-Archive-Files: zip

Es scannt dann den Antwortkörper nach einer Liste von Dateien. Die Syntax ist eine durch Leerzeichen getrennte Liste der Dateiprüfziffer (CRC-32), Größe (in Bytes), Standort (richtig URL-kodiert) und Dateiname. Eine Datei pro Zeile. Der Dateistandort entspricht einem Standort in Ihrer nginx.conf; die Datei kann auf der Festplatte, von einem Upstream oder von einem anderen Modul stammen. Der Dateiname kann einen Verzeichnispfad enthalten und ist das, was aus der ZIP-Datei extrahiert wird. Beispiel:

1034ab38 428    /foo.txt   My Document1.txt
83e8110b 100339 /bar.txt   My Other Document1.txt
0        0      @directory My empty directory

Dateien werden in der angegebenen Reihenfolge abgerufen und kodiert. Wenn eine Datei nicht gefunden werden kann oder die Dateianforderung einen Fehler zurückgibt, wird der Download abgebrochen.

Die CRC-32 ist optional. Geben Sie "-" ein, wenn Sie die CRC-32 nicht kennen; beachten Sie, dass in diesem Fall mod_zip die Unterstützung für den Range-Header deaktiviert.

Ein spezielles URL-Markierungssymbol @directory kann verwendet werden, um einen Verzeichniseintrag innerhalb eines Archivs zu deklarieren. Dies ist sehr praktisch, wenn Sie einen Baum von Dateien verpacken müssen, einschließlich einiger leerer Verzeichnisse, da diese explizit deklariert werden müssen.

Wenn Sie möchten, dass mod_zip einige HTTP-Header der ursprünglichen Anfrage in den Unteranfragen, die den Inhalt der Dateien abrufen, einfügt, übergeben Sie die Liste ihrer Namen im folgenden HTTP-Header:

X-Archive-Pass-Headers: <header-name>[:<header-name>]*

Umkodierung von Dateinamen

Um die Dateinamen als UTF-8 umzucodieren, fügen Sie den folgenden Header zur Upstream-Antwort hinzu:

X-Archive-Charset: [original charset name]

Der ursprüngliche Zeichensatzname sollte etwas sein, das iconv versteht. (Diese Funktion funktioniert nur, wenn iconv vorhanden ist.)

Wenn Sie den ursprünglichen Zeichensatz als native festlegen:

X-Archive-Charset: native;

werden die Dateinamen aus der Dateiliste als bereits im nativen Zeichensatz des Systems betrachtet. Folglich wird das ZIP-Flag für allgemeine Zwecke (Bit 11), das anzeigt, dass die Namen UTF-8-kodiert sind, nicht gesetzt, und Archivierer wissen, dass es sich um einen nativen Zeichensatz handelt.

Manchmal gibt es Probleme bei der Umwandlung von UTF-8-Namen in den nativen (CP866) Zeichensatz, die dazu führen, dass gängige Archivierer sie nicht erkennen. Gleichzeitig möchten Sie, dass keine Daten verloren gehen, damit intelligente Archivierer das Unicode-Pfad-Extra-Feld verwenden können. Sie können Ihre eigene, angepasste Darstellung des Dateinamens im nativen Zeichensatz zusammen mit dem ursprünglichen UTF-8-Namen in einer Zeichenkette bereitstellen. Sie müssen nur den folgenden Header hinzufügen:

X-Archive-Name-Sep: [separator];

Ihre Dateiliste sollte dann so aussehen:

<CRC-32> <size> <path> <native-filename><separator><utf8-filename>
...

Dann wird das Dateinamenfeld native-filename enthalten und das Unicode-Pfad-Extra-Feld wird utf8-filename enthalten.

Tipps

  1. Fügen Sie einen Header "Content-Disposition: attachment; filename=foobar.zip" in der Upstream-Antwort hinzu, wenn Sie möchten, dass der Client die Datei "foobar.zip" nennt.

  2. Um Bandbreite zu sparen, fügen Sie einen "Last-Modified"-Header in der Upstream-Antwort hinzu; mod_zip wird dann den "If-Range"-Header von Clients respektieren.

  3. Um den X-Archive-Files-Header aus der an den Client gesendeten Antwort zu entfernen, verwenden Sie das headers_more-Modul: http://wiki.nginx.org/NginxHttpHeadersMoreModule

  4. Um die Leistung zu verbessern, stellen Sie sicher, dass die Backends keine gzipped Dateien zurückgeben. Sie können dies mit proxy_set_header Accept-Encoding ""; in den Standortblöcken für die Komponentendateien erreichen.

Fragen/Patches können an Evan Miller, emmiller@gmail.com, gerichtet werden.

GitHub

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