跳转至

upload-progress: 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
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-upload-progress

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

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

load_module modules/ngx_http_uploadprogress_module.so;

本文档描述了 nginx-module-upload-progress v0.9.4，于 2025 年 3 月 15 日发布。

介绍

nginx_uploadprogress_module 是一个上传进度系统的实现，它监控 RFC1867 POST 上传在传输到上游服务器时的进度。

它通过跟踪 Nginx 代理到上游服务器的上传，而不分析上传的内容，并提供一个 Web API，以 JavaScript、Json 或任何其他格式报告上传进度（通过模板的帮助）。

它之所以有效，是因为 Nginx 作为上游服务器的加速器，在将上传的 POST 内容传输到上游服务器之前将其存储在磁盘上。每个单独的 POST 上传请求应包含一个唯一的进度标识符。

该模块的版权归 (c) 2007-2012 Brice Figureau 所有，并根据 BSD 许可证授权（见 LICENSE）。 * rbtree 和 shm_zone 代码基于 Igor Sysoev 的 limit_zone Nginx 模块。 * expire header 代码基于 Igor Sysoev 的 header_filter Nginx 模块。

JSON 的想法和机制的想法基于 Lighttpd mod_uploadprogress： http://blog.lighttpd.net/articles/2006/08/01/mod_uploadprogress-is-back

警告： * 当使用 --with-debug 编译时，此模块将生成大量日志消息。

不兼容的更改

v0.9.0：

JSONP 现在是进度探测的默认输出。如果您依赖此模块提供已弃用的 Java 输出，请使用： upload_progress_java_output 在进度探测位置中。

配置

每个上传请求应分配一个唯一标识符。此唯一标识符将用于存储请求并引用以进行报告。 该标识符可以作为 GET 参数或名为 X-Progress-ID 的 HTTP 头传输。

upload_progress +++++++++++++++ :语法: upload_progress :默认值: 无 :上下文: http :描述: 此指令启用上传进度模块，并为 保留 字节，用于存储每个连接的跟踪信息。

track_uploads +++++++++++++ :语法: track_uploads :默认值: 无 :上下文: location :描述: 此指令启用当前位置的上传跟踪。每个到达此位置的 POST 将在 上传进度跟踪器中注册请求。 由于 Nginx 尚不支持 RFC 1867 上传，因此位置必须是 proxy_pass 或 fastcgi 位置。 POST 必须 有一个名为 X-Progress-ID 的查询参数（或同名的 HTTP 头），其值是用于获取进度信息的唯一标识符。如果 POST 没有此类信息，则不会跟踪上传。 被跟踪的连接在完成后最多保留 秒，以便能够为上传进度探测提供有用的信息。 警告：此指令必须是位置的最后一条指令。它必须位于 proxy_pass 或 fastcgi_pass 位置中。

report_uploads ++++++++++++++ :语法: report_uploads :默认值: 无 :上下文: location :描述: 此指令允许位置报告由 track_uploads 为 跟踪的上传进度。 返回的文档是一个 JavaScript 文本，默认可能有 4 个结果： * 上传请求尚未注册或未知： new Object({ 'state' : 'starting' })

    * 上传请求已结束：
            new Object({ 'state' : 'done' })

    * 上传请求生成了 HTTP 错误
            new Object({ 'state' : 'error', 'status' : <error code> })
        一个可以用于跟踪客户端的错误代码是 413（请求实体过大）。

    * 上传请求正在进行中：
            new Object({ 'state' : 'uploading', 'received' : <size_received>, 'size' : <total_size>})

可以返回纯 JSON 而不是此 JavaScript（请参见 upload_progress_json_output）。
还可以使用指令完全配置响应格式：
        upload_progress_template

对此位置的 HTTP 请求必须具有 X-Progress-ID 参数或 HTTP 头，包含有效的正在进行的上传的唯一标识符。

upload_progress_content_type ++++++++++++++++++++++++++++ :语法: upload_progress_content_type :默认值: text/javascript :上下文: location :描述: 此指令允许更改上传进度探测响应的内容类型。

upload_progress_header ++++++++++++++++++++++ :语法: upload_progress_header :默认值: X-Progress-ID :上下文: location :描述: 此指令允许更改进度 ID 的头名称。

upload_progress_jsonp_parameter ++++++++++++++++++++++ :语法: upload_progress_jsonp_parameter :默认值: callback :上下文: location :描述: 此指令允许更改带有 jsonp 回调名称的 GET 参数的名称。

upload_progress_java_output +++++++++++++++++++++++++++ :语法: upload_progress_java_output :默认值: 不适用 :上下文: location :描述: 此指令将所有内容设置为输出为 eval() 兼容的 JavaScript 代码。

upload_progress_json_output +++++++++++++++++++++++++++ :语法: upload_progress_json_output :默认值: 不适用 :上下文: location :描述: 此指令将所有内容设置为输出为纯 JSON。

upload_progress_jsonp_output ++++++++++++++++++++++++++++ :语法: upload_progress_jsonp_output :默认值: 不适用 :上下文: location :描述: 此指令将所有内容设置为输出为 jsonp（类似于 JSON 输出，但带有回调）。

upload_progress_template ++++++++++++++++++++++++ :语法: upload_progress_template