Nginx 中 proxy_cache_max_range_offset 实现断点续传-Nginx-PHP中文网

proxy_cache_max_range_offset 并不直接实现断点续传，而是使 nginx 缓存能正确处理 range 请求，为断点续传提供基础支持；它限定可缓存响应的最大字节偏移量，避免缓存失控，需配合后端 accept-ranges/content-range 响应及 proxy_cache_valid 206 等配置共同生效。

nginx 中 proxy_cache_max_range_offset 实现断点续传

proxy_cache_max_range_offset 并不直接实现断点续传，它只是让 Nginx 缓存能正确处理带 Range 请求的响应，从而为断点续传提供支持基础。

它解决什么问题？

当客户端（如下载工具、视频播放器）发起分片下载或拖动进度条时，会发送 Range: bytes=1000-1999 这类请求。如果后端返回的是完整文件（200 OK），而 Nginx 缓存里只存了整个响应体，那么对后续的 Range 请求，Nginx 默认无法从缓存中精准截取对应字节段——除非启用范围缓存支持。

proxy_cache_max_range_offset 就是告诉 Nginx：允许缓存那些“可被 Range 请求命中”的响应，并限定最大偏移量，避免缓存过大或不可控的范围请求导致内存/磁盘压力。

如何配合断点续传工作？

要让 Nginx 缓存真正支持断点续传，需同时满足以下条件：

后端服务返回响应时，必须带上 Accept-Ranges: bytes 或 Content-Range（对 206 响应）；
Nginx 配置中开启 proxy_cache_use_stale updating 和 proxy_cache_lock 提升并发 Range 请求的可靠性；
设置 proxy_cache_max_range_offset（例如 500m），表示最多缓存从开头起 500MB 内的任意 Range 请求结果；
确保 proxy_cache_valid 200 206 1h 等指令覆盖了 206 Partial Content 响应；
使用 proxy_ignore_headers Cache-Control Expires Set-Cookie（视业务而定）避免后端干扰缓存策略。

典型配置片段

以下是一个支持 Range 缓存的最小可行示例：

CPA Update - Secure CLI Proxy API Maintenance

安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。

下载

proxy_cache_path /var/cache/nginx/range_cache levels=1:2 keys_zone=range:10m max_size=1g inactive=60m use_temp_path=off;
<p>server {
location /files/ {
proxy_pass <a href="https://www.php.cn/link/65b5b8d1f89bf53a5713bc3afdd83e9e">https://www.php.cn/link/65b5b8d1f89bf53a5713bc3afdd83e9e</a>;
proxy_cache range;
proxy_cache_valid 200 206 1h;
proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
proxy_cache_lock on;
proxy_cache_lock_timeout 5s;
proxy_cache_max_range_offset 500m;</p><pre class="brush:php;toolbar:false;">    # 必须透传 Range 和 Accept-Ranges
    proxy_set_header Range $http_range;
    proxy_set_header If-Range $http_if_range;
    proxy_pass_request_headers on;
}

}