别苑拾遗
0%

Nginx-upload-module中文文档

Posted on Edited on In

参数

upload_pass

Syntax: upload_pass location
Default: —
Context: server,location

完成文件上传后当前的POST表单内的file字段将被替换为服务器上的零
时路径与其他的必须信息,并通过本参数交由下一阶段处理,可指向某个
uri或upstream.

upload_resumable

Syntax: upload_resumable on | off
Default: upload_resumable off
Context: main,server,location

启用断点续传.

upload_store

Syntax: upload_store directory [level1 [level2]] ...
Default: —
Context: server,location

指定一个目录用于零时存储上传的文件,如指定level为1则该目录下需创建
名为0-9的子目录以适配哈希化存储,目录/子目录需在Nginx启动前创建完
成,Nginx不会自动创建目录/子目录.

upload_state_store

Syntax: upload_state_store directory [level1 [level2]] ...
Default: —
Context: server,location

指定一个目录用于存储断点续传的零时文件,其他同upload_store.

upload_store_access

Syntax: upload_store_access mode
Default: upload_store_access user:rw
Context: server,location

指定upload_store目录下零时文件的权限,无特殊需求时无需设置,使用默认值.

upload_set_form_field

Syntax: upload_set_form_field name value
Default: —
Context: server,location

定义变量名用于替换POST表单内file字段供下一阶段使用:

  • $upload_field_name: HTML表单内的file字段名
  • $upload_content_type: 文件MIME类型
  • $upload_file_name: 不带路径的原始文件名
  • $upload_tmp_path: 零时文件的绝对路径

这些变量仅在本次POST请求期间有效.

使用范例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
#若一HTML表单有两个file字段分别为file1与file2,上传的文件名为TODO.xlsx与SDR.txt
#当我们的Nginx配置如下时:

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_pass送出的POST表单内容如下:
------WebKitFormBoundarydjT6Js1Pew3Fxmyb
Content-Disposition: form-data; name="file1.name"

TODO.xlsx
------WebKitFormBoundarydjT6Js1Pew3Fxmyb
Content-Disposition: form-data; name="file1.content_type"

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
------WebKitFormBoundarydjT6Js1Pew3Fxmyb
Content-Disposition: form-data; name="file1.path"

/tmp/2/0000000002

------WebKitFormBoundarydjT6Js1Pew3Fxmyb
Content-Disposition: form-data; name="file2.name"

SDR.txt
------WebKitFormBoundarydjT6Js1Pew3Fxmyb
Content-Disposition: form-data; name="file2.content_type"

text/plain
------WebKitFormBoundarydjT6Js1Pew3Fxmyb
Content-Disposition: form-data; name="file2.path"

/tmp/3/0000000003

upload_aggregate_form_field

Syntax: upload_aggregate_form_field name value
Default: —
Context: server,location

提供额外的附加在POST表单内的聚合字段,可在设置中使用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: 上传文件的大小(bytes)
  • $upload_file_number: 上传文件的序号(从1开始)

这些变量仅在本次POST请求期间有效.

注意: 除去$upload_file_size, $upload_file_number这两个变量外,其他的
变量一旦被设置均会消耗额外的CPU资源用于计算哈希值,同时设置一种哈希
算法的大小写变量仅进行一次哈希计算.

使用范例:

1
2
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

Syntax: upload_pass_form_field regex
Default: —
Context: server,location

默认情况下,本模块并不会将file类型字段以外的input字段发送给下一阶段处理
,除非在此显式声明字段名称(非类型).

使用范例(PCRE支持):

1
upload_pass_form_field "^submit$|^test$";

使用范例(无PCRE):

1
2
upload_pass_form_field "submit";
upload_pass_form_field "test";

upload_cleanup

Syntax: upload_cleanup status/range ...
Default: —
Context: server,location

指定一系列HTTP状态码,范围201-599, 可以用减号指定范围,当下一阶段处理完毕
返回的HTTP状态码与此处匹配时则删除当前POST请求上传的零时文件.

使用范例:

1
upload_cleanup 400 404 499 500-505;

upload_buffer_size

Syntax: upload_buffer_size size
Default: size of memory page in bytes
Context: server,location

写缓冲区尺寸,默认为一个内存页的大小(4k),如果希望减少系统呼叫(syscall write)
的次数,可增加该值.

upload_max_part_header_len

Syntax: upload_max_part_header_len size
Default: 512
Context: server,location

设置part header的长度,绝大多数时候保持默认值即可

1
2
3
4
5
6
part header长这样:
------WebKitFormBoundarydjT6Js1Pew3Fxmyb
或者这样:
--------------------------858745820d5862d4
如果part header超长,你会在错误日志看到下面这行提示:
*53 part header is too long

upload_max_file_size

Syntax: upload_max_file_size size
Default: 0
Context: main,server,location

设定单个文件的尺寸限制,默认为0,不限制文件大小.该设置为软限制,即使文件
大小超限Nginx也不会中断与报错,超限文件仅被模块忽略,较而言之
client_max_body_size 是Nginx声明的硬限制,超限会导致上传中断与报错.

upload_limit_rate

Syntax: upload_limit_rate rate
Default: 0
Context: main,server,location

上传速率限制,默认为0,不限制上传速度.

upload_max_output_body_len

Syntax: upload_max_output_body_len size
Default: 100k
Context: main,server,location

定义送至下一阶段的POST请求内body最大尺寸,默认为100k,如果超限会收到错
误提示error 413 (Request entity too large) . 设置为0时不限制.

upload_tame_arrays

Syntax: upload_tame_arrays on | off
Default: off
Context: main,server,location

是否删除文件字段名称中的方括号.
(当你的后端是PHP时,需要打开该选项).

upload_pass_args

Syntax: upload_pass_args on | off
Default: off
Context: main,server,location

转发查询参数至upload_pass指定的location, 对命名location无效,如@test.

使用范例:

1
2
3
#表单内容
<form action="/upload/?id=5">
<!-- ... -->
1
2
3
4
5
6
7
8
9
10
11
location /upload/ {
    upload_pass /internal_upload/;
    upload_pass_args on;
}

# ...

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

配置范例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
server {
    client_max_body_size 100m;
    listen 80;

    # 设定上传路径
    location /upload/ {
        # 设定后端路径,在这里是通过代理模块指向另一个http server
        upload_pass @test;

        # 设定存储目录
        # cd /tmp && mkdir -m 777 {0..9}
        # 如果你忘记创建目录,你会得到以下错误
        # 503 Service Temporarily Unavailable
        upload_store /tmp 1;

        # 零时文件创建时对Nginx运行用户可读
        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";

        # 增加文件md5摘要与尺寸大小
        upload_aggregate_form_field "$upload_field_name.md5" "$upload_file_md5";
        upload_aggregate_form_field "$upload_field_name.size" "$upload_file_size";
		
        #允许表单内两项input值传入后端
        upload_pass_form_field "^submit$|^test$";

        upload_cleanup 400 404 499 500-505;
    }

    # 设定后端地址
    location @test {
        proxy_pass http://localhost:8080;
    }
}
1
2
3
4
5
6
<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>