upload：用于处理文件上传的NGINX模块

安装

您可以在任何基于RHEL的发行版中安装此模块，包括但不限于：

• RedHat Enterprise Linux 7、8、9和10
• CentOS 7、8、9
• AlmaLinux 8、9
• Rocky Linux 8、9
• Amazon Linux 2和Amazon Linux 2023

CentOS/RHEL 8+、Fedora Linux、Amazon Linux 2023+CentOS/RHEL 7和Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-upload

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-upload

通过在/etc/nginx/nginx.conf顶部添加以下内容来启用模块：

load_module modules/ngx_http_upload_module.so;

本文档描述了nginx-module-upload v2.4.0，发布于2026年2月3日。

---

这是一个用于nginx的模块，用于处理使用multipart/form-data编码（RFC 1867）的文件上传，以及根据此协议实现的可断点续传上传。

• 描述
• 指令
  • upload_pass
  • upload_resumable
  • upload_store
  • upload_state_store
  • upload_store_access
  • upload_set_form_field
  • upload_aggregate_form_field
  • upload_pass_form_field
  • upload_cleanup
  • upload_buffer_size
  • upload_max_part_header_len
  • upload_max_file_size
  • upload_limit_rate
  • upload_max_output_body_len
  • upload_tame_arrays
  • upload_pass_args
• 示例配置
• 许可证

描述

该模块解析请求体，将所有正在上传的文件存储到由upload_store指令指定的目录中。然后，文件将从请求体中剥离，修改后的请求被传递给由upload_pass指令指定的location，从而允许对上传的文件进行任意处理。每个文件字段都会被一组由upload_set_form_field指令指定的字段所替换。然后，每个上传文件的内容可以通过$upload_tmp_path变量从指定文件中读取，或者文件可以直接移动到最终目的地。输出文件的删除由upload_cleanup指令控制。如果请求的方法不是POST，模块将返回错误405（方法不允许）。具有此类方法的请求可以通过error_page指令在备选location中处理。

指令

upload_pass

语法： upload_pass location
默认值： —
上下文： server,location

指定传递请求体的location。文件字段将被剥离，并替换为包含处理上传文件所需信息的字段。

upload_resumable

语法： upload_resumable on | off
默认值： upload_resumable off
上下文： main,server,location

启用可断点续传上传。

upload_store

语法： upload_store directory [level1 [level2]] ...
默认值： —
上下文： server,location

指定输出文件保存到的目录。该目录可以进行哈希处理。在这种情况下，所有子目录应在启动nginx之前存在。

upload_state_store

语法： upload_state_store directory [level1 [level2]] ...
默认值： —
上下文： server,location

指定包含可断点续传上传状态文件的目录。该目录可以进行哈希处理。在这种情况下，所有子目录应在启动nginx之前存在。

upload_store_access

语法： upload_store_access mode
默认值： upload_store_access user:rw
上下文： server,location

指定用于创建输出文件的访问模式。

upload_set_form_field

语法： upload_set_form_field name value
默认值： —
上下文： server,location

为传递给后端的请求体中的每个上传文件指定要生成的表单字段。name和value都可以包含以下特殊变量：

• $upload_field_name：原始文件字段的名称
• $upload_content_type：上传文件的content type
• $upload_file_name：正在上传文件的原始名称，已去除DOS和UNIX表示法中的前导路径元素。即，"D:\Documents And Settings\My Dcouments\My Pictures\Picture.jpg"将被转换为"Picture.jpg"，"/etc/passwd"将被转换为"passwd"。
• $upload_tmp_path：原始文件内容存储到的路径。输出文件名由10位数字组成，生成算法与proxy_temp_path指令相同。

这些变量仅在处理原始请求体的一个部分期间有效。

使用示例：

upload_set_form_field $upload_field_name.name "$upload_file_name";
upload_set_form_field $upload_field_name.content_type "$upload_content_type";
upload_set_form_field $upload_field_name.path "$upload_tmp_path";

upload_aggregate_form_field

语法： upload_aggregate_form_field name value
默认值： —
上下文： server,location

为传递给后端的请求体中的每个上传文件指定包含聚合属性的表单字段。name和value都可以包含标准的nginx变量、来自upload_set_form_field指令的变量以及以下额外的特殊变量：

• $upload_file_md5：文件的MD5校验和
• $upload_file_md5_uc：文件的大写MD5校验和
• $upload_file_sha1：文件的SHA1校验和
• $upload_file_sha1_uc：文件的大写SHA1校验和
• $upload_file_sha256：文件的SHA256校验和
• $upload_file_sha256_uc：文件的大写SHA256校验和
• $upload_file_sha512：文件的SHA512校验和
• $upload_file_sha512_uc：文件的大写SHA512校验和
• $upload_file_crc32：文件的CRC32十六进制值
• $upload_file_size：文件的大小（以字节为单位）
• $upload_file_number：文件在请求体中的序号

由该指令指定的字段值在文件成功上传后计算，因此这些变量仅在处理原始请求体的一个部分结束时有效。

警告： 变量$upload_file_md5、$upload_file_md5_uc、$upload_file_sha1和$upload_file_sha1_uc会使用额外资源来计算MD5和SHA1校验和。

使用示例：

upload_aggregate_form_field $upload_field_name.md5 "$upload_file_md5";
upload_aggregate_form_field $upload_field_name.size "$upload_file_size";

upload_pass_form_field

语法： upload_pass_form_field regex
默认值： —
上下文： server,location

指定将从原始请求体中传递给后端的字段名称的正则表达式模式。此指令可以在每个location中多次指定。只要第一个模式匹配，字段就会被传递给后端。对于不支持PCRE的环境，此指令指定要传递给后端的字段的确切名称。如果省略该指令，则不会将任何字段从客户端传递给后端。

使用示例：

upload_pass_form_field "^submit$|^description$";

对于不支持PCRE的环境：

upload_pass_form_field "submit";
upload_pass_form_field "description";

upload_cleanup

语法： upload_cleanup status/range ...
默认值： —
上下文： server,location

指定在生成某些HTTP状态码后，将删除当前请求中成功上传的所有文件。用于在后端或服务器故障后进行清理。如果后端出于某种原因不需要上传的文件，也可以显式发出错误状态码。HTTP状态码必须是400-599范围内的数值，不允许有前导零。可以使用短横线指定状态码范围。

使用示例：

upload_cleanup 400 404 499 500-505;

upload_buffer_size

语法： upload_buffer_size size
默认值： 内存页大小（以字节为单位）
上下文： server,location

用于累积文件数据并将其写入磁盘的写缓冲区大小（以字节为单位）。此指令旨在权衡内存使用与系统调用频率。

upload_max_part_header_len

语法： upload_max_part_header_len size
默认值： 512
上下文： server,location

指定part header的最大长度（以字节为单位）。确定用于累积part header的缓冲区大小。

upload_max_file_size

语法： upload_max_file_size size
默认值： 0
上下文： main,server,location

指定文件的最大大小。超过此指令值的文件将被忽略。此指令指定的是“软”限制，即遇到超过指定限制的文件后，nginx将继续处理请求体，尝试接收剩余文件。对于“硬”限制，必须使用client_max_body_size指令。此指令的值为零表示不对文件大小施加任何限制。

upload_limit_rate

语法： upload_limit_rate rate
默认值： 0
上下文： main,server,location

指定上传速率限制（以字节/秒为单位）。零表示速率不受限制。

upload_max_output_body_len

语法： upload_max_output_body_len size
默认值： 100k
上下文： main,server,location

指定输出体的最大长度。这可以防止非文件表单字段在内存中堆积。每当输出体超过指定限制时，将生成错误413（请求实体过大）。此指令的值为零表示不对输出体长度施加任何限制。

upload_tame_arrays

语法： upload_tame_arrays on | off
默认值： off
上下文： main,server,location

指定是否必须删除文件字段名称中的方括号（PHP数组所需）。

upload_pass_args

语法： upload_pass_args on | off
默认值： off
上下文： main,server,location

启用将查询参数转发到由upload_pass指定的location。对命名location无效。示例：

<form action="/upload/?id=5">
<!-- ... -->

location /upload/ {
    upload_pass /internal_upload/;
    upload_pass_args on;
}

# ...

location /internal_upload/ {
    # ...
    proxy_pass http://backend;
}

在此示例中，后端收到的请求URI为"/upload?id=5"。如果upload_pass_args off，后端收到的则是"/upload"。

示例配置

server {
    client_max_body_size 100m;
    listen 80;

    # 上传表单应提交到此location
    location /upload/ {
        # 将修改后的请求体传递到此location
        upload_pass @test;

        # 将文件存储到此目录
        # 该目录已进行哈希处理，子目录0 1 2 3 4 5 6 7 8 9应存在
        upload_store /tmp 1;

        # 允许上传的文件仅由用户读取
        upload_store_access user:r;

        # 在请求体中设置指定字段
        upload_set_form_field $upload_field_name.name "$upload_file_name";
        upload_set_form_field $upload_field_name.content_type "$upload_content_type";
        upload_set_form_field $upload_field_name.path "$upload_tmp_path";

        # 告知后端文件的哈希和大小
        upload_aggregate_form_field "$upload_field_name.md5" "$upload_file_md5";
        upload_aggregate_form_field "$upload_field_name.size" "$upload_file_size";

        upload_pass_form_field "^submit$|^description$";

        upload_cleanup 400 404 499 500-505;
    }

    # 将修改后的请求体传递给后端
    location @test {
        proxy_pass http://localhost:8080;
    }
}

<form name="upload" method="POST" enctype="multipart/form-data" action="/upload/">
<input type="file" name="file1">
<input type="file" name="file2">
<input type="hidden" name="test" value="value">
<input type="submit" name="submit" value="Upload">
</form>

GitHub

您可以在nginx-module-upload的GitHub仓库中找到此模块的其他配置技巧和文档。