Перейти к содержанию

zip: Потоковый ZIP архиватор для NGINX

Установка на Debian/Ubuntu

Эти документы относятся к APT пакету nginx-module-zip, предоставляемому репозиторием GetPageSpeed Extras.

  1. Настройте APT репозиторий, как описано в настройке APT репозитория.
  2. Установите модуль:
sudo apt-get update
sudo apt-get install nginx-module-zip
Показать дистрибутивы и архитектуры 
| Дистрибутив | Версия            | Компонент   | Архитектуры    |
|-------------|-------------------|-------------|-----------------|
| debian      | bookworm          | main        | amd64, arm64    |
| debian      | bookworm-mainline | main        | amd64, arm64    |
| debian      | trixie            | main        | amd64, arm64    |
| debian      | trixie-mainline   | main        | amd64, arm64    |
| ubuntu      | focal             | main        | amd64, arm64    |
| ubuntu      | focal-mainline    | main        | amd64, arm64    |
| ubuntu      | jammy             | main        | amd64, arm64    |
| ubuntu      | jammy-mainline    | main        | amd64, arm64    |
| ubuntu      | noble             | main        | amd64, arm64    |
| ubuntu      | noble-mainline    | main        | amd64, arm64    |

mod_zip динамически собирает ZIP архивы. Он может передавать компонентные файлы с восходящих серверов, используя родной прокси-код nginx, так что процесс никогда не занимает больше нескольких КБ ОЗУ одновременно, даже при сборке архивов, которые (потенциально) могут быть гигантских размеров в несколько гигабайт.

mod_zip поддерживает ряд "современных" функций ZIP, включая большие файлы, временные метки UTC и имена файлов в кодировке UTF-8. Он позволяет клиентам возобновлять большие загрузки, используя заголовки "Range" и "If-Range", хотя эти функции требуют от сервера знать контрольные суммы файлов (CRC-32) заранее. См. раздел "Использование" для подробностей.

Чтобы разархивировать файлы на лету, ознакомьтесь с nginx-unzip-module.

Использование

Модуль активируется, когда оригинальный ответ (вероятно, от восходящего сервера) включает следующий HTTP заголовок:

X-Archive-Files: zip

Затем он просматривает тело ответа на наличие списка файлов. Синтаксис — это список, разделенный пробелами, содержащий контрольную сумму файла (CRC-32), размер (в байтах), местоположение (правильно закодированное в URL) и имя файла. Один файл на строку. Местоположение файла соответствует местоположению в вашем nginx.conf; файл может находиться на диске, с восходящего сервера или из другого модуля. Имя файла может включать путь к каталогу и будет извлечено из ZIP файла. Пример:

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

Файлы извлекаются и кодируются в порядке. Если файл не может быть найден или запрос файла возвращает любую ошибку, загрузка отменяется.

CRC-32 является необязательным. Укажите "-" если вы не знаете CRC-32; имейте в виду, что в этом случае mod_zip отключит поддержку заголовка Range.

Специальный маркер URL @directory может использоваться для обозначения записи каталога в архиве. Это очень удобно, когда вам нужно упаковать дерево файлов, включая некоторые пустые каталоги, так как их необходимо объявить явно.

Если вы хотите, чтобы mod_zip включал некоторые HTTP заголовки оригинального запроса в подзапросах, которые извлекают содержимое файлов, передайте список их имен в следующем HTTP заголовке:

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

Пере kodirovka имен файлов

Чтобы пере kodirovat' имена файлов в UTF-8, добавьте следующий заголовок к ответу восходящего сервера:

X-Archive-Charset: [имя оригинальной кодировки]

Имя оригинальной кодировки должно быть чем-то, что понимает iconv. (Эта функция работает только в том случае, если iconv присутствует.)

Если вы установите оригинальную кодировку как native:

X-Archive-Charset: native;

имена файлов из списка файлов будут считаться уже в системной родной кодировке. Соответственно, общий флаг ZIP, указывающий на то, что имена закодированы в UTF-8, не будет установлен, и архиваторы будут знать, что это родная кодировка.

Иногда возникают проблемы с конвертацией имен UTF-8 в родную кодировку (CP866), что заставляет популярные архиваторы не распознавать их. В то же время вы хотите, чтобы данные не терялись, так что умные архиваторы могут использовать дополнительное поле Unicode Path. Вы можете предоставить свою собственную адаптированную репрезентацию имени файла в родной кодировке вместе с оригинальным именем UTF-8 в одной строке. Вам просто нужно добавить следующий заголовок:

X-Archive-Name-Sep: [разделитель];

Таким образом, ваш список файлов должен выглядеть так:

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

тогда поле имени файла будет содержать native-filename, а дополнительное поле Unicode Path будет содержать utf8-filename.

Советы

  1. Добавьте заголовок "Content-Disposition: attachment; filename=foobar.zip" в ответ восходящего сервера, если вы хотите, чтобы клиент назвал файл "foobar.zip".

  2. Чтобы сэкономить пропускную способность, добавьте заголовок "Last-Modified" в ответ восходящего сервера; mod_zip тогда будет уважать заголовок "If-Range" от клиентов.

  3. Чтобы удалить заголовок X-Archive-Files из ответа, отправленного клиенту, используйте модуль headers_more: http://wiki.nginx.org/NginxHttpHeadersMoreModule

  4. Чтобы улучшить производительность, убедитесь, что бэкенды не возвращают сжатыми файлы. Вы можете добиться этого с помощью proxy_set_header Accept-Encoding ""; в блоках местоположения для компонентных файлов.

Вопросы/патчи можно направлять Эвену Миллеру, emmiller@gmail.com.