IT博客汇 | nginx上传模块nginx_upload_module原理、安装及使用教程

nginx上传模块nginx_upload_module原理、安装及使用教程

mckee发表于 2015-05-26 00:26:35

一.nginx_upload_module使用背景
利用nginx上传模块Nginx_upload_module可更有效实现大文件断点续传，还可安装nginx-upload-progress-module扩展显示文件上传进度。
二.nginx_upload_module工作原理
Nginx_upload_module通过nginx服务来接受用户上传的文件，自动解析请求体中存储的所有文件上传到upload_store指定的目录下。这些文件信息从原始请求体中分离并根据nginx.conf中的配置重新组装好上传参数，交由upload_pass指定的段处理，从而允许处理任意上传文件。每个上传文件中的file字段值被一系列的upload_set_form_field指令值替换。每个上传文件的内容可以从$upload_tmp_path变量读取，或者可以将文件转移到目的目录下。上传的文件移除可以通过upload_cleanup指令控制。如果请求的方法不是POST，模块将返回405错误(405 Not Allowed)，该错误提示可以通过error_page指令处理。
三.nginx_upload_module安装过程
(1).检查是否安装nginx_upload_module模块

/usr/local/nginx/sbin/nginx -V

(2).下载nginx_upload_module

wget https://github.com/hongzhidao/nginx-upload-module/archive/master.zip
unzip master.zip

(3).进入nginx源码目录，重新编译安装nginx，并添加nginx_upload_module编译选项

--add-module=/模块源代码路径/nginx_upload_module

(4).配置nginx上传模块
在server的上下文中添加配置信息：

location /upload {
    upload_pass   /upload.php;#上传完成后端接受处理文件
    upload_store /data/uptmp;#上传文件夹
    upload_limit_rate 1024k;# 限制上传速度
    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;#md5
    upload_aggregate_form_field "${upload_field_name}_size" $upload_file_size;#文件大小
    upload_pass_form_field "^submit$|^description$";
    #如果希望把所有的表单字段都传给后端可以用upload_pass_form_field "^.*$";
}

四.nginx_upload_module配置参数(详情可见官方文档)
syntax: upload_pass
default: none
severity: mandatory
context: server, location

指定传输请求到后端的服务器。文件字段将会被重新组织，包括处理文件的必要信息。

syntax: upload_resumable off><em>
default: off
severity: mandatory
context: main, server, location

启用断点续传

syntax: upload_store [ [ ] ... ]
default: none
severity: mandatory
context: server, location

指定上传文件保存的目录。目录可以被散列化，启动nginx之前，所有的子目录都必须已经存在。

syntax: upload_state_store [ [ ] ... ]
default: none
severity: optional
context: server, location

指定断点续传文件所包含的状态文件的目录，目录可以被散列化，启动nginx之前，所有的子目录都必须已经存在。

syntax: upload_store_access
default: user:rw
severity: optional
context: server, location

指定上传文件的权限模式。

syntax: upload_set_form_field
default: none
severity: optional
context: server, location

在请求体中指定要生成的每个上传文件的表单字段，字段名和字段值可以包含在下列变量中。

$upload_field_name -- 源文件字段的名字
$upload_content_type -- 上传文件的Content-Type值
$upload_file_name -- 上传的源文件的文件名，文件名中的路径会被处理掉，比如路径 "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";

syntax: upload_aggregate_form_field
default: none
severity: optional
context: server, location

指定表单的字段名和字段值，字段名和字段值可以包含nginx标准的变量，变量由 upload_set_form_field 指定或者使用下面这些变量：

$upload_file_md5 -- MD5 checksum of the file
$upload_file_md5_uc -- MD5 checksum of the file in uppercase letters
$upload_file_sha1 -- SHA1 checksum of the file
$upload_file_sha1_uc -- SHA1 checksum of the file in uppercase letters
$upload_file_crc32 -- hexdecimal value of CRC32 of the file
$upload_file_size -- size of the file in bytes
$upload_file_number -- ordinal number of file in request body

上面指定的字段值只会在文件成功上传完毕后才会被计算，因此这些变量仅仅在最后一个请求体上传完毕后才会被校验。

警告: 变量 $upload_file_md5, $upload_file_md5_uc, $upload_file_sha1 和 $upload_file_sha1_uc 会耗用更多的资源来计算 MD5 和 SHA1 校验。

example:

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

syntax: upload_pass_form_field
default: none
severity: optional
context: server, location

给字段名指定一个正则表达式，这将会被转发到后端服务器，每个指令都可以设置多个匹配模式。只要碰到了匹配的模式，指令就会被立刻转发到后端服务器，如果是PCRE不能识别的模式，则会进行精确匹配字段名，匹配了则转发到后端服务器，如果指令被忽略，则不会转发到后端服务器。

例如:

upload_pass_form_field "^submit$|^description$";

PCRE-不能识别的情况：

upload_pass_form_field "submit";
upload_pass_form_field "description";

syntax: upload_cleanup [...]
default: none
severity: optional
context: server, location

指定当每一个文件都上传成功后的HTTP的状态，用于后端服务器失败后的清理，当后端服务器由于某种原因不需要上传文件时，后端服务器也可能会直接返回错误代码，HTTP的状态必须是一个数字，范围在400---599之间，可以指定一个破折号范围的状态。

例如：

upload_cleanup 400 404 499 500-505;

syntax: upload_buffer_size
default: size of memory page in bytes
severity: optional
context: server, location

设置写缓冲区的尺寸，被用来累积文件数据，然后一次性写入硬盘。该值的使用是用来提高内存的使用效率和优化系统调用次数。

syntax: upload_max_part_header_len
default: 512
severity: optional
context: server, location

指定头的最大长度，单位为bytes，该值被用来累积保存头的缓冲区大小。

syntax: upload_max_file_size
default: off
severity: optional
context: main, server, location

指定文件的最大尺寸。文件长度超过该值将会被忽略。该指令是一个软限制，当碰到文件长度超过指定的最大值时，nginx也会继续接收处理请求体。如果要让该值必须起作用，需要通过client_max_body_size的硬限制来设置。该值设置为0，代表没有任何限制。

syntax: upload_limit_rate
default: 0
severity: optional
context: main, server, location

指定上传速率，单位为bytes/秒，0代表速率无限制。

syntax: upload_max_output_body_len
default: 100k
severity: optional
context: main, server, location

指定输出体的最大长度。这将会避免非文件表单数据占用内存。超过该值，将会返回413错误，代表请求体太大，该值为0，代表无限制。

syntax: upload_tame_arrays off><em>
default: off
severity: optional
context: main, server, location

指定在字段名中的方刮号是否被丢弃 (需要 PHP 数组).。

syntax: upload_pass_argsoff><em>
default: off
severity: optional
context: main, server, location

允许转发请求参数, 该参数由upload_pass指定无效的命名位置，例如：


...
location /upload {
    upload_pass /internal_upload;
    upload_pass_args on;
}
...
location /internal_upload {
    ...
    proxy_pass http://backend;
}

在这个例子中，后端服务器得到的请求地址为 "/upload?id=5". 该例子中，如果 upload_pass_args 设置为off ，则后端服务器得到的请求地址为 "/upload".

五.nginx_upload_module实现代码：
html代码：

PHP代码：

print_r($_POST);

if (rename($_POST['myfile_path'], $_POST['myfile_name'])) {
    echo 'ok';
}

/*
Array
(
    [myfile_name] => psb (2).jpg
    [myfile_content_type] => image/jpeg
    [myfile_path] => /data/uptmp/0000000012
    [myfile_md5] => 091fa303622a020dba0e57a5d36ca276
    [myfile_size] => 18364
)
*/