pgaertig/nginx-big-upload

nginx-big-upload Docker镜像

镜像概述

本镜像集成了支持Lua的Nginx，提供大文件断点续传和可靠上传功能，还包含mod_zip模块可动态生成ZIP归档。适用于需要处理超大文件（如1TB）上传的场景，已在生产环境验证多年。

核心功能

• 支持PUT/POST RAW格式上传；
• 断点续传与分块上传；
• 实时CRC32/SHA-1校验（客户端或服务端状态存储）；
• 兼容nginx-upload-module 2.2的续传协议；
• 可通过Lua扩展上传生命周期逻辑；
• 无文件大小限制（已测试1TB文件）；
• 集成mod_zip模块，支持动态生成可续传的ZIP包。

使用场景

• 需要上传超大文件（如视频、备份数据）的应用；
• 网络不稳定环境下的断点续传需求；
• 需验证文件完整性的上传场景；
• 需动态生成ZIP归档的服务。

配置说明

基础配置

1. 克隆项目到服务器（非Docker部署时）：

   bash
   git clone -b v1.2.2 https://github.com/pgaertig/nginx-big-upload.git /opt/nginx-big-upload
   

2. Nginx配置示例：

   nginx
   lua_package_path "/opt/nginx-big-upload/lib/?.lua;;"; 
   server {  
       listen 80;
       location = /upload {
           set $storage backend_file;
           set $file_storage_path /tmp/uploads;
           set $backend_url /files/add;
           set $bu_sha1 on;
           set $bu_checksum on;
           content_by_lua_file /opt/nginx-big-upload/big-upload.lua;
       }
       location /files/add {
           internal;
           content_by_lua 'ngx.say("Upload completed")';
       }
   }
   

关键变量说明

• $storage: 存储方式（file直接保存到磁盘；backend_file完成后调用后端接口）；
• $file_storage_path: 文件存储目录（需Nginx worker有读写权限）；
• $backend_url: 上传完成后调用的后端接口（仅backend_file模式生效）；
• $bu_sha1: 是否启用SHA-1校验（on/off）；
• $bu_checksum: CRC32校验模式（on客户端存储状态；server服务端存储；off关闭）。

Docker部署示例

简单运行

bash
docker run -d -p 8080:80 -v /your/host/path:/tmp/uploads pgaertig/nginx-big-upload

• -p 8080:80: 映射容器80端口到主机8080；
• -v: 挂载主机目录到容器存储路径，持久化上传文件。

Docker Compose示例

yaml
version: '3'
services:
  nginx-big-upload:
    image: pgaertig/nginx-big-upload
    ports:
      - "8080:80"
    volumes:
      - ./uploads:/tmp/uploads
    restart: always

已知限制

• 暂不支持HTTP/2；
• 无上传速率限制；
• 不支持Web表单的多部分POST请求（建议用lua-resty-upload替代）；
• 分块需按顺序上传。