Pular para conteúdo

zip: Armazenador ZIP em streaming para NGINX

Instalação

Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:

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

Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:

load_module modules/ngx_http_zip_module.so;

Este documento descreve o nginx-module-zip v1.3.0 lançado em 04 de fevereiro de 2026.

mod_zip monta arquivos ZIP dinamicamente. Ele pode transmitir arquivos componentes de servidores upstream com o código de proxy nativo do nginx, de modo que o processo nunca consome mais do que alguns KB de RAM de cada vez, mesmo ao montar arquivos que são (potencialmente) gigabytes em tamanho.

mod_zip suporta uma série de recursos "modernos" do ZIP, incluindo arquivos grandes, timestamps em UTC e nomes de arquivos em UTF-8. Ele permite que os clientes retomem grandes downloads usando os cabeçalhos "Range" e "If-Range", embora esses recursos exijam que o servidor conheça os checksums dos arquivos (CRC-32) com antecedência. Veja "Uso" para mais detalhes.

Para descompactar arquivos em tempo real, confira o nginx-unzip-module.

Uso

O módulo é ativado quando a resposta original (presumivelmente de um upstream) inclui o seguinte cabeçalho HTTP:

X-Archive-Files: zip

Ele então escaneia o corpo da resposta em busca de uma lista de arquivos. A sintaxe é uma lista separada por espaços do checksum do arquivo (CRC-32), tamanho (em bytes), localização (corretamente codificada em URL) e nome do arquivo. Um arquivo por linha. A localização do arquivo corresponde a uma localização no seu nginx.conf; o arquivo pode estar no disco, de um upstream ou de outro módulo. O nome do arquivo pode incluir um caminho de diretório e é o que será extraído do arquivo ZIP. Exemplo:

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

Os arquivos são recuperados e codificados em ordem. Se um arquivo não puder ser encontrado ou a solicitação do arquivo retornar qualquer tipo de erro, o download é abortado.

O CRC-32 é opcional. Coloque "-" se você não souber o CRC-32; note que, nesse caso, o mod_zip desabilitará o suporte para o cabeçalho Range.

Um marcador de URL especial @directory pode ser usado para declarar uma entrada de diretório dentro de um arquivo. Isso é muito conveniente quando você precisa empacotar uma árvore de arquivos, incluindo alguns diretórios vazios, pois eles devem ser declarados explicitamente.

Se você quiser que o mod_zip inclua alguns cabeçalhos HTTP da solicitação original, nas sub-solicitações que buscam o conteúdo dos arquivos, passe a lista de seus nomes no seguinte cabeçalho HTTP:

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

Re-encodificação de nomes de arquivos

Para re-encodar os nomes dos arquivos como UTF-8, adicione o seguinte cabeçalho à resposta do upstream:

X-Archive-Charset: [original charset name]

O nome do charset original deve ser algo que o iconv entenda. (Esse recurso só funciona se o iconv estiver presente.)

Se você definir o charset original como native:

X-Archive-Charset: native;

os nomes dos arquivos da lista de arquivos são tratados como já estando no charset nativo do sistema. Consequentemente, a flag de uso geral do ZIP (bit 11) que indica nomes codificados em UTF-8 não será definida, e os arquivadores saberão que é um charset nativo.

Às vezes, há problemas ao converter nomes em UTF-8 para o charset nativo (CP866) que fazem com que arquivadores populares falhem em reconhecê-los. E ao mesmo tempo, você deseja que os dados não sejam perdidos para que arquivadores inteligentes possam usar o campo extra de caminho Unicode. Você pode fornecer sua própria representação adaptada do nome do arquivo no charset nativo junto com o nome original em UTF-8 em uma única string. Você só precisa adicionar o seguinte cabeçalho:

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

Assim, sua lista de arquivos deve parecer:

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

então o campo do nome do arquivo conterá native-filename e o campo extra de caminho Unicode conterá utf8-filename.

Dicas

  1. Adicione um cabeçalho "Content-Disposition: attachment; filename=foobar.zip" na resposta do upstream se você quiser que o cliente nomeie o arquivo como "foobar.zip".

  2. Para economizar largura de banda, adicione um cabeçalho "Last-Modified" na resposta do upstream; o mod_zip então honrará o cabeçalho "If-Range" dos clientes.

  3. Para remover o cabeçalho X-Archive-Files da resposta enviada ao cliente, use o módulo headers_more: http://wiki.nginx.org/NginxHttpHeadersMoreModule

  4. Para melhorar o desempenho, certifique-se de que os backends não estão retornando arquivos gzipped. Você pode conseguir isso com proxy_set_header Accept-Encoding ""; nos blocos de localização para os arquivos componentes.

Dúvidas/patches podem ser direcionados a Evan Miller, emmiller@gmail.com.

GitHub

Você pode encontrar dicas de configuração adicionais e documentação para este módulo no repositório do GitHub para nginx-module-zip.