zip: Compresor ZIP en streaming para NGINX
Instalación
Puedes instalar este módulo en cualquier distribución basada en RHEL, incluyendo, pero no limitado a:
- RedHat Enterprise Linux 7, 8, 9 y 10
- CentOS 7, 8, 9
- AlmaLinux 8, 9
- Rocky Linux 8, 9
- Amazon Linux 2 y 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
Habilita el módulo añadiendo lo siguiente en la parte superior de /etc/nginx/nginx.conf:
load_module modules/ngx_http_zip_module.so;
Este documento describe nginx-module-zip v1.3.0 lanzado el 04 de febrero de 2026.
mod_zip ensambla archivos ZIP de forma dinámica. Puede transmitir archivos componentes desde servidores upstream con el código de proxy nativo de nginx, de modo que el proceso nunca ocupa más que unos pocos KB de RAM a la vez, incluso mientras ensambla archivos que son (potencialmente) de varios gigabytes de tamaño.
mod_zip soporta una serie de características "modernas" de ZIP, incluyendo archivos grandes, marcas de tiempo UTC y nombres de archivos en UTF-8. Permite a los clientes reanudar descargas grandes utilizando los encabezados "Range" e "If-Range", aunque estas características requieren que el servidor conozca los checksums de los archivos (CRC-32) de antemano. Consulta "Uso" para más detalles.
Para descomprimir archivos al vuelo, consulta nginx-unzip-module.
Uso
El módulo se activa cuando la respuesta original (presumiblemente de un upstream) incluye el siguiente encabezado HTTP:
X-Archive-Files: zip
Luego escanea el cuerpo de la respuesta en busca de una lista de archivos. La sintaxis es una lista separada por espacios del checksum del archivo (CRC-32), tamaño (en bytes), ubicación (correctamente codificada en URL) y nombre del archivo. Un archivo por línea. La ubicación del archivo corresponde a una ubicación en tu nginx.conf; el archivo puede estar en disco, provenir de un upstream o de otro módulo. El nombre del archivo puede incluir una ruta de directorio y es lo que se extraerá del archivo ZIP. Ejemplo:
1034ab38 428 /foo.txt My Document1.txt
83e8110b 100339 /bar.txt My Other Document1.txt
0 0 @directory My empty directory
Los archivos se recuperan y codifican en orden. Si no se puede encontrar un archivo o la solicitud del archivo devuelve algún tipo de error, la descarga se aborta.
El CRC-32 es opcional. Pon "-" si no conoces el CRC-32; ten en cuenta que en este caso mod_zip deshabilitará el soporte para el encabezado Range.
Un marcador de URL especial @directory puede usarse para declarar una entrada de directorio dentro de un archivo. Esto es muy conveniente cuando tienes que empaquetar un árbol de archivos, incluyendo algunos directorios vacíos. Ya que deben ser declarados explícitamente.
Si deseas que mod_zip incluya algunos encabezados HTTP de la solicitud original, en las sub-solicitudes que obtienen el contenido de los archivos, entonces pasa la lista de sus nombres en el siguiente encabezado HTTP:
X-Archive-Pass-Headers: <header-name>[:<header-name>]*
Re-codificación de nombres de archivos
Para re-codificar los nombres de archivos como UTF-8, añade el siguiente encabezado a la respuesta del upstream:
X-Archive-Charset: [nombre del conjunto de caracteres original]
El nombre del conjunto de caracteres original debe ser algo que iconv entienda. (Esta característica solo funciona si iconv está presente.)
Si estableces el conjunto de caracteres original como native:
X-Archive-Charset: native;
los nombres de archivos de la lista de archivos se tratan como si ya estuvieran en el conjunto de caracteres nativo del sistema. En consecuencia, la bandera de propósito general de ZIP (bit 11) que indica nombres codificados en UTF-8 no se establecerá, y los archivadores sabrán que es un conjunto de caracteres nativo.
A veces hay problemas al convertir nombres en UTF-8 a un conjunto de caracteres nativo (CP866) que causan que los archivadores populares no los reconozcan. Y al mismo tiempo, deseas que los datos no se pierdan para que los archivadores inteligentes puedan usar el campo extra de Ruta Unicode. Puedes proporcionar tu propia representación adaptada del nombre del archivo en el conjunto de caracteres nativo junto con el nombre original en UTF-8 en una cadena. Solo necesitas añadir el siguiente encabezado:
X-Archive-Name-Sep: [separator];
Así que tu lista de archivos debería verse así:
<CRC-32> <size> <path> <native-filename><separator><utf8-filename>
...
entonces el campo de nombre de archivo contendrá native-filename y el campo extra de Ruta Unicode contendrá utf8-filename.
Consejos
-
Añade un encabezado "Content-Disposition: attachment; filename=foobar.zip" en la respuesta del upstream si deseas que el cliente nombre el archivo "foobar.zip".
-
Para ahorrar ancho de banda, añade un encabezado "Last-Modified" en la respuesta del upstream; mod_zip respetará el encabezado "If-Range" de los clientes.
-
Para eliminar el encabezado X-Archive-Files de la respuesta enviada al cliente, utiliza el módulo headers_more: http://wiki.nginx.org/NginxHttpHeadersMoreModule
-
Para mejorar el rendimiento, asegúrate de que los backends no estén devolviendo archivos gzipped. Puedes lograr esto con
proxy_set_header Accept-Encoding "";en los bloques de ubicación para los archivos componentes.
Las preguntas/parches pueden dirigirse a Evan Miller, emmiller@gmail.com.
GitHub
Puedes encontrar consejos de configuración adicionales y documentación para este módulo en el repositorio de GitHub para nginx-module-zip.