nginx-upload-module用于让nginx在接入层接收并落盘大文件，再将文件路径等元信息以表单字段形式转发后端，实现上传与业务逻辑解耦，显著降低后端内存占用和进程阻塞。
Linux 下 Nginx 编译安装 upload 模块（即 nginx-upload-module）是为了支持大文件上传的后端接收与分段处理，它本身不直接提供断点续传或前端控制，但能将上传的文件、表单字段等解析为标准 CGI 参数，便于后端脚本（如 PHP/Python）安全高效地接收和保存。
确认 Nginx 当前状态与依赖准备
先检查是否已安装 Nginx 及其版本：
nginx -V 2>&1 | grep -o 'configure arguments:' -A 1
若已运行官方预编译包（如 yum/apt 安装），默认不含 upload 模块，必须重新编译。需提前安装基础编译工具和依赖：
- gcc、make、autoconf、automake、libtool
- pcre-devel（支持正则）、openssl-devel（HTTPS）、zlib-devel（gzip）
- 若用 HTTPS 或需要 GeoIP 等功能，按需补充对应 -devel 包
下载并解压 Nginx 与 upload 模块源码
选择与当前 Nginx 版本一致或兼容的源码（推荐使用稳定版，如 nginx-1.24.0）：
wget https://nginx.org/download/nginx-1.24.0.tar.gz<br>tar -zxvf nginx-1.24.0.tar.gz<br><br># 下载 nginx-upload-module（注意：该项目已多年未更新，推荐使用维护更活跃的 fork）<br>wget https://github.com/fdintino/nginx-upload-module/archive/refs/tags/2.3.0.tar.gz<br>tar -zxvf 2.3.0.tar.gz
⚠️ 注意：原作者 v3.0+ 分支已弃用；fdintino 的 2.3.0 是目前最常用且兼容主流 Nginx 1.20–1.26 的稳定版本。
配置并编译带 upload 模块的 Nginx
进入 Nginx 源码目录，执行 configure 并加入 upload 模块路径（绝对路径更稳妥）：
cd nginx-1.24.0<br>./configure \<br> --prefix=/usr/local/nginx \<br> --with-http_ssl_module \<br> --with-http_gzip_static_module \<br> --add-module=../nginx-upload-module-2.3.0 \<br> --user=www \<br> --group=www
然后编译安装：
Linux 性能分析与调优专家，覆盖 CPU、内存、磁盘 I/O、网络、内核参数、编译优化、容器/K8s。适用场景：系统卡顿/高负载、内存不足/OOM/Swap 高、CPU 异常/iowait 高。
make && sudo make install
安装完成后，检查模块是否生效：
/usr/local/nginx/sbin/nginx -V 2>&1 | grep upload
若输出中含 --add-module=...upload-module，说明成功集成。
配置 upload 模块实现大文件上传
在 nginx.conf 的 http 或 server 块中添加如下配置（以接收 POST 到 /upload 的文件为例）：
upload_pass @backend;<br>upload_store /tmp/upload_tmp;<br>upload_store_access user:rw group:rw all:r;<br>upload_set_form_field $upload_field_name.name "$upload_file_name";<br>upload_set_form_field $upload_field_name.content_type "$upload_content_type";<br>upload_set_form_field $upload_field_name.path "$upload_tmp_path";<br>upload_aggregate_form_field "$upload_field_name.md5" "$upload_file_md5";<br>upload_pass_form_field "^submit$|^description$";<br>upload_cleanup 400 404 499 500-505;
再定义一个内部 location 处理上传后的转发：
location @backend {<br> proxy_pass http://127.0.0.1:8080;<br> proxy_set_header X-File-Name $upload_file_name;<br> proxy_set_header X-File-Path $upload_tmp_path;<br> proxy_set_header X-File-Size $upload_file_size;<br>}
关键说明：
-
upload_store必须是 Nginx worker 进程有读写权限的目录（建议单独创建并 chown www:www） -
upload_pass_form_field白名单表单字段，防止恶意字段注入 - 后端服务（如 Python Flask）收到请求时，会拿到
X-File-Path和原始文件名等信息，可直接移动或处理临时文件 - Nginx 本身不保存最终文件，只是“搬运工”，真正落盘由后端完成，更安全可控
重启 Nginx 后即可测试上传（建议用 curl 或 Postman 发送 multipart/form-data 请求）。注意还需同步调大 client_max_body_size、client_body_timeout 等参数以支持大文件：
client_max_body_size 2G;<br>client_body_timeout 600;
不复杂但容易忽略的是权限与路径一致性——upload_store 目录权限错、Nginx 用户无法写入、或后端没及时处理临时文件，都会导致上传失败静默丢弃。
