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 下缓存目录的文件数量与平均大小，碎片明显减少即为正向效果