Nginx支持断点续传需透传Range请求头及Content-Range、Accept-Ranges等响应头，禁用proxy_buffering和gzip，并确保后端正确返回206响应。
在 Nginx 中使用 proxy_pass 转发大文件下载请求时，要支持断点续传（即 HTTP Range 请求），关键不是手动实现逻辑，而是确保 Nginx 正确透传客户端的 Range 请求头、服务端的 206 Partial Content 响应及响应头（如 Content-Range、Accept-Ranges），同时禁用可能干扰流式响应的缓冲和压缩行为。
确保上游服务支持 Range 请求
断点续传依赖后端应用（如 Python Flask、Node.js、Java Spring 等）正确处理 Range 请求并返回 206 响应。Nginx 本身不生成或修改分块响应，它只做透传。请先验证后端是否能独立响应如下请求：
-
curl -H "Range: bytes=1000-1999" http://your-backend/file.zip返回206及正确Content-Range - 响应头中包含
Accept-Ranges: bytes
配置 proxy_pass 透传 Range 相关头部
Nginx 默认会忽略或改写部分请求/响应头。需显式启用透传：
- 用
proxy_pass_request_headers on;（默认开启，一般无需设置） - 显式添加
Range到允许转发的请求头列表：proxy_set_header Range $http_range; - 透传后端返回的关键响应头：
proxy_pass_header Accept-Ranges;proxy_pass_header Content-Range;proxy_pass_header ETag;（有助于客户端校验缓存）
关闭影响流式传输的代理选项
以下配置若启用，会破坏断点续传流程：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
-
禁用响应体缓冲：避免 Nginx 缓存整个响应再返回，导致无法按 Range 分块输出
proxy_buffering off; -
禁用 gzip 压缩：压缩会改变原始字节范围，使
Content-Range失效gzip off;（或针对下载路径单独关闭） -
禁用响应头重写：不要用
proxy_hide_header隐藏Accept-Ranges或Content-Range -
避免设置固定 Content-Length：尤其不要加
add_header Content-Length ...，会让 Range 请求退化为全量 200 响应
完整示例配置（供参考）
假设下载路径为 /dl/，后端地址为 http://backend:8080：
location /dl/ {
proxy_pass http://backend:8080/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
<pre class="brush:php;toolbar:false;"># 关键：透传 Range 请求头
proxy_set_header Range $http_range;
# 关键：透传后端的 Range 相关响应头
proxy_pass_header Accept-Ranges;
proxy_pass_header Content-Range;
proxy_pass_header ETag;
# 关键：禁用缓冲和压缩
proxy_buffering off;
gzip off;
# 可选：超时调大，适应大文件传输
proxy_read_timeout 3600;
proxy_send_timeout 3600;}
配置完成后 reload Nginx：nginx -s reload，再用支持断点续传的工具（如 wget -c 或 curl -r）测试即可生效。
