proxy_cache_max_range_offset 是 nginx 控制 range 请求缓存切片范围的关键参数，设定缓存完整响应时允许截取的最大字节偏移量，默认512kb；仅当客户端请求的 range 起始位置不超过该值，nginx 才从已缓存的完整响应中切片返回，否则回源。
proxy_cache_max_range_offset 是 Nginx 代理缓存中控制分段下载（Range 请求）缓存行为的关键参数，它决定了当客户端发起 Range 请求（比如视频拖拽、大文件断点续传）时，Nginx 能否从已缓存的完整响应中截取对应字节范围返回——前提是该 Range 偏移量不超过此阈值。
作用原理：为什么需要这个参数？
Nginx 默认不缓存 Range 请求的响应（即对 Range: bytes=1000-2000 这类请求，即使上游已返回并缓存了完整文件，也不会复用缓存直接切片返回）。启用 proxy_cache_use_stale updating 或配合 proxy_cache_key 优化后，仍需满足范围偏移限制才能命中缓存切片。该参数就是为解决“缓存了整文件，但 Range 请求太靠后导致无法复用”的问题。
它不是限制客户端请求的 Range 大小，而是限制：若缓存中已存在一个完整响应（例如 100MB 的文件），那么只有当客户端请求的 bytes=N- 中的 N ≤ proxy_cache_max_range_offset 时，Nginx 才允许从该缓存体中截取返回；否则，会绕过缓存，重新向后端发起 Range 请求。
FastAPI Flask Proxy
下载
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
典型配置与生效条件
要让该指令起作用，需同时满足以下条件：
- 开启代理缓存（
proxy_cache已定义并启用） - 启用 Range 缓存支持：
proxy_cache_valid 206 1h;（必须显式配置 206 状态码缓存时间） - 缓存键包含 Range 头（推荐：
proxy_cache_key "$scheme$request_method$host$request_uri$http_range";）或使用更优策略如忽略 Range（见下条） - 后端实际返回了完整响应（非仅返回片段），且被成功缓存（常见于后端未处理 Range、直接返回 200）
实用建议与常见误区
该参数默认为 512KB（即 524288 字节），对多数场景足够，但需按业务调整：
- 视频点播/大文件下载：若用户常拖拽到文件末尾（如请求最后 1MB），可设为
proxy_cache_max_range_offset 500m;（单位支持 k/m/g） - 避免盲目调大：过大的值会导致缓存体长期驻留内存/磁盘，且 Nginx 需加载整个缓存文件再切片，增加 I/O 和延迟
- 更高效的做法是让后端支持 Range 并返回 206，Nginx 缓存这些 206 响应（需
proxy_cache_key包含$http_range），此时该参数不生效，但缓存粒度更细、更节省空间 - 注意：该指令仅影响
proxy_cache，不适用于fastcgi_cache或scgi_cache
验证是否生效
可通过日志和响应头确认：
- 开启
log_format cache '$upstream_http_x_cache';，查看日志中是否出现HIT（而非MISST或UPDATING） - 响应头中检查
X-Cache: HIT和Content-Range是否存在，且Content-Length与请求 Range 一致 - 用
curl -H "Range: bytes=10485760-" http://your.site/file.zip -I测试偏移 10MB 请求是否走缓存（需确保该偏移 ≤ 设置值）
