proxy_cache_max_range_offset用于限制Nginx缓存Range请求的起始偏移量，防止大文件尾部随机Range导致缓存碎片化和资源浪费；推荐设为1m～10m，并必须配合含$http_range的cache_key使用。
设置 proxy_cache_max_range_offset 是优化大文件 Range 请求缓存行为的关键手段，核心目标不是“多缓存”，而是“缓存得更稳、更省、更准”。
为什么大文件访问需要这个参数？
视频、安装包等大文件常通过 HTTP Range 实现拖拽播放或断点续传。若不对 Range 起始位置设限，Nginx 可能为末尾几 MB 甚至最后几个字节（如 bytes=9999990000-）单独建缓存项——内容极少，但元数据开销不减，长期积累导致：
- 磁盘缓存碎片化严重，
inactive清理效率下降 - 缓存命中率降低，大量请求穿透到上游
- 若
proxy_cache_key没包含$http_range，还可能返回错位内容
合理设置 offset 值的依据
重点不是文件有多大，而是用户最常访问哪一段。实测和生产经验表明：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
- 95% 以上的视频拖拽发生在前 2MB 内（关键帧、索引头、moov box 等元数据集中区）
- 下载工具（如 wget、curl -C）断点续传也多从起始或中间偏移较小处恢复
- 设为 1m～5m 已覆盖绝大多数有效场景；超过 10m 后收益急剧衰减，反而增加碎片风险
示例配置：proxy_cache_max_range_offset 3m;
表示只缓存 bytes=0- 到 bytes=3145727- 范围内的请求，超出即透传。
必须同步调整的配套项
单设 max_range_offset 不足以生效，还需确认以下三点：
-
cache_key 必须含
$http_range：否则不同 Range 共享同一缓存键，造成内容污染 -
启用
slice模块（可选但推荐）：配合slice 1m+$slice_range，让 Nginx 主动分片管理，比被动响应 Range 更可控 -
缓存有效期对 206 响应显式声明：如
proxy_cache_valid 200 206 1h;，避免 Range 片段被过早淘汰
如何验证是否起作用？
开启 Nginx 日志中的 $upstream_cache_status 变量：
- 看到
HIT或UPDATING→ 前段 Range 缓存生效 - 看到
BYPASS或MISS（且请求 Range 起始远超设定值）→ 参数已拦截尾部请求 - 对比设置前后
proxy_cache_path下缓存目录的文件数量与平均大小，碎片明显减少即为正向效果
