Nginx 大文件上传与请求体处理：缓冲、临时文件与断点续传

客户端 --[请求体]--> Nginx --[转发]--> 上游应用
                      |
                      +-- 1. 边收边写内存缓冲 client_body_buffer_size
                      +-- 2. 缓冲满 -> 落盘 client_body_temp_path
                      +-- 3. 收完（或边收边发）后转发上游

http {
    # 内存缓冲区大小：超出即落盘
    client_body_buffer_size 256k;

    # 临时文件目录（可配置多级哈希子目录）
    client_body_temp_path /var/cache/nginx/body 1 2;

    # 请求体大小上限
    client_max_body_size 100m;

    # 读取请求体的超时（针对单次读操作）
    client_body_timeout 60s;
}

http {
    # 默认档：普通接口
    client_max_body_size 1m;

    server {
        listen 80;

        # 表单与 JSON 接口
        location /api/ {
            client_max_body_size 10m;
            proxy_pass http://api_backend;
        }

        # 图片与文档上传
        location /upload/image/ {
            client_max_body_size 20m;
            proxy_pass http://upload_backend;
        }

        # 视频与大文件上传
        location /upload/video/ {
            client_max_body_size 2048m;
            client_body_timeout 300s;
            proxy_pass http://upload_backend;
        }
    }
}

server {
    listen 80;

    # 自定义 413 响应，让前端能给出友好提示
    error_page 413 = @too_large;

    location @too_large {
        default_type application/json;
        return 413 '{"code":413,"msg":"文件超过大小限制"}';
    }

    location /upload/ {
        client_max_body_size 100m;
        proxy_pass http://upload_backend;
    }
}

location /upload/video/ {
    client_max_body_size 2048m;

    # 关闭请求体缓冲：边收边转发，不落盘
    proxy_request_buffering off;

    # 关闭后必须放大发送超时，否则慢速客户端会被切断
    proxy_send_timeout 300s;
    proxy_read_timeout 300s;

    proxy_pass http://upload_backend;
}

proxy_request_buffering on（默认）
  优点：上游只接收完整请求体，可安全重试；上游连接占用时间短
  缺点：大文件会在 Nginx 落盘一次，再读出来转发，磁盘双倍 IO
  适用：小文件、需要失败重试的接口

proxy_request_buffering off
  优点：无磁盘落盘，内存占用低，首字节到达上游更快
  缺点：上游必须能处理慢速请求体；连接占用时间长；无法重试
  适用：大文件、流式上传、上传即转发的管道

http {
    # 独立分区，避免打满根分区影响系统
    client_body_temp_path /data/nginx/body 1 2;

    # 与后端协商的超时与大小上限保持一致
    client_body_timeout 120s;
}

# 监控临时目录占用，超过阈值告警
du -sh /data/nginx/body
find /data/nginx/body -type f -mmin +60 -delete   # 清理一小时前的残留

# 挂载时预留 5% 给 root，防止完全写满
# /etc/fstab 中为数据盘添加保留块设置
tune2fs -m 5 /dev/vdb1

client_header_timeout   读取请求头超时，上传场景通常不变
client_body_timeout     两次读请求体之间的最大间隔（不是总时长）
proxy_send_timeout      两次向上游写数据之间的最大间隔
proxy_read_timeout      两次从上游读数据之间的最大间隔

location /upload/video/ {
    client_max_body_size 2048m;

    # 慢速移动网络的单次读间隔可能很长，需放大
    client_body_timeout 180s;

    proxy_request_buffering off;
    proxy_send_timeout 180s;
    proxy_read_timeout 180s;

    proxy_pass http://upload_backend;
}

location /upload/chunk/ {
    client_max_body_size 16m;      # 单片大小，可精确控制
    proxy_request_buffering off;
    proxy_pass http://upload_backend;

    # 关闭对分片请求的缓存，避免复用
    proxy_cache off;
}

location /api/upload/sign {
    # 应用签发带过期时间的直传凭证，Nginx 仅转发
    proxy_pass http://api_backend;
    proxy_set_header Host $host;
}

location /api/upload/callback {
    # 对象存储上传完成后回调，应用校验并落库
    client_max_body_size 1m;
    proxy_pass http://api_backend;
}

架构对比：
  经 Nginx 中转  客户端 -> Nginx -> 应用 -> 对象存储
                 带宽占用 Nginx，临时文件占用 Nginx 磁盘

  客户端直传     客户端 -> 对象存储（Nginx 只签发凭证）
                 带宽与磁盘都不经 Nginx，仅需处理凭证与回调

# 确认实际生效的请求体限制（可能被上层覆盖）
nginx -T | grep -n 'client_max_body_size\|client_body_timeout'

# 观察临时文件是否在增长（上传进行中）
watch -n1 'ls -l /data/nginx/body | tail -5; du -sh /data/nginx/body'

# 检查磁盘与 inode（小文件过多会耗尽 inode）
df -h /data/nginx/body
df -i /data/nginx/body

# 观察上传过程中的连接状态与错误日志
tail -f /var/log/nginx/error.log | grep -i 'client intended to send too large body'
tail -f /var/log/nginx/error.log | grep -i 'timed out reading client request body'

# 在响应头暴露限制值，便于前端提前校验
add_header X-Max-Upload-Size "104857600" always;

# 上传接口的限速与并发限制
limit_req_zone $binary_remote_addr zone=upload:10m rate=5r/m;
limit_conn_zone $binary_remote_addr zone=upconn:10m;

server {
    location /upload/ {
        client_max_body_size 2048m;

        # 限速与并发限制
        limit_req zone=upload burst=2 nodelay;
        limit_conn upconn 3;

        # 上传接口必须鉴权
        auth_request /internal/authz;
        # 只允许特定方法与内容类型
        limit_except POST { deny all; }

        proxy_request_buffering off;
        proxy_pass http://upload_backend;
    }

    location = /internal/authz {
        internal;
        proxy_pass http://auth_backend/verify;
        proxy_pass_request_body off;
        proxy_set_header Content-Length "";
    }
}