Aller au contenu

zip: Archiveur ZIP en streaming pour NGINX

Installation

Vous pouvez installer ce module dans n'importe quelle distribution basée sur RHEL, y compris, mais sans s'y limiter :

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

Activez le module en ajoutant ce qui suit en haut de /etc/nginx/nginx.conf :

load_module modules/ngx_http_zip_module.so;

Ce document décrit nginx-module-zip v1.3.0 publié le 4 février 2026.

mod_zip assemble des archives ZIP dynamiquement. Il peut diffuser des fichiers composants depuis des serveurs en amont avec le code de proxy natif de nginx, de sorte que le processus ne prenne jamais plus que quelques Ko de RAM à la fois, même lors de l'assemblage d'archives qui sont (potentiellement) de plusieurs gigaoctets.

mod_zip prend en charge un certain nombre de fonctionnalités ZIP "modernes", y compris les gros fichiers, les horodatages UTC et les noms de fichiers UTF-8. Il permet aux clients de reprendre de gros téléchargements en utilisant les en-têtes "Range" et "If-Range", bien que ces fonctionnalités nécessitent que le serveur connaisse les sommes de contrôle des fichiers (CRC-32) à l'avance. Voir "Utilisation" pour plus de détails.

Pour décompresser des fichiers à la volée, consultez nginx-unzip-module.

Utilisation

Le module est activé lorsque la réponse originale (présumément d'un serveur en amont) inclut l'en-tête HTTP suivant :

X-Archive-Files: zip

Il scanne ensuite le corps de la réponse à la recherche d'une liste de fichiers. La syntaxe est une liste séparée par des espaces de la somme de contrôle du fichier (CRC-32), de la taille (en octets), de l'emplacement (appropriément encodé en URL) et du nom de fichier. Un fichier par ligne. L'emplacement du fichier correspond à un emplacement dans votre nginx.conf ; le fichier peut être sur le disque, provenant d'un serveur en amont ou d'un autre module. Le nom de fichier peut inclure un chemin de répertoire, et c'est ce qui sera extrait du fichier ZIP. Exemple :

1034ab38 428    /foo.txt   Mon Document1.txt
83e8110b 100339 /bar.txt   Mon Autre Document1.txt
0        0      @directory Mon répertoire vide

Les fichiers sont récupérés et encodés dans l'ordre. Si un fichier ne peut pas être trouvé ou si la demande de fichier retourne une sorte d'erreur, le téléchargement est interrompu.

Le CRC-32 est optionnel. Mettez "-" si vous ne connaissez pas le CRC-32 ; notez que dans ce cas, mod_zip désactivera le support de l'en-tête Range.

Un marqueur d'URL spécial @directory peut être utilisé pour déclarer une entrée de répertoire dans une archive. C'est très pratique lorsque vous devez empaqueter un arbre de fichiers, y compris certains répertoires vides. Comme ils doivent être déclarés explicitement.

Si vous souhaitez que mod_zip inclue certains en-têtes HTTP de la requête originale, dans les sous-requêtes qui récupèrent le contenu des fichiers, passez la liste de leurs noms dans l'en-tête HTTP suivant :

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

Ré-encodage des noms de fichiers

Pour ré-encoder les noms de fichiers en UTF-8, ajoutez l'en-tête suivant à la réponse en amont :

X-Archive-Charset: [nom du charset d'origine]

Le nom du charset d'origine doit être quelque chose que iconv comprend. (Cette fonctionnalité ne fonctionne que si iconv est présent.)

Si vous définissez le charset d'origine comme native :

X-Archive-Charset: native;

les noms de fichiers de la liste de fichiers sont considérés comme déjà dans le charset natif du système. En conséquence, le drapeau d'utilisation générale ZIP (bit 11) qui indique des noms encodés en UTF-8 ne sera pas défini, et les archiveurs sauront qu'il s'agit d'un charset natif.

Parfois, il y a un problème pour convertir des noms UTF-8 en charset natif (CP866) qui empêche les archiveurs populaires de les reconnaître. Et en même temps, vous voulez que les données ne soient pas perdues afin que les archiveurs intelligents puissent utiliser le champ supplémentaire Unicode Path. Vous pouvez fournir votre propre représentation adaptée du nom de fichier dans le charset natif avec le nom UTF-8 d'origine dans une seule chaîne. Il vous suffit d'ajouter l'en-tête suivant :

X-Archive-Name-Sep: [séparateur];

Ainsi, votre liste de fichiers devrait ressembler à :

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

alors le champ de nom de fichier contiendra native-filename et le champ supplémentaire Unicode Path contiendra utf8-filename.

Conseils

  1. Ajoutez un en-tête "Content-Disposition: attachment; filename=foobar.zip" dans la réponse en amont si vous souhaitez que le client nomme le fichier "foobar.zip".

  2. Pour économiser de la bande passante, ajoutez un en-tête "Last-Modified" dans la réponse en amont ; mod_zip respectera alors l'en-tête "If-Range" des clients.

  3. Pour supprimer l'en-tête X-Archive-Files de la réponse envoyée au client, utilisez le module headers_more : http://wiki.nginx.org/NginxHttpHeadersMoreModule

  4. Pour améliorer les performances, assurez-vous que les backends ne renvoient pas de fichiers gzippés. Vous pouvez y parvenir avec proxy_set_header Accept-Encoding ""; dans les blocs de localisation pour les fichiers composants.

Les questions/patches peuvent être dirigés vers Evan Miller, emmiller@gmail.com.

GitHub

Vous pouvez trouver des conseils de configuration supplémentaires et de la documentation pour ce module dans le dépôt GitHub pour nginx-module-zip.