Nginx 中 proxy_cache_max_range_offset 优化媒体缓存-Nginx-PHP中文网

proxy_cache_max_range_offset 不是 nginx 官方支持的指令，属无效配置；应改用 proxy_cache_valid 200 206、统一 proxy_cache_key、分片缓存及合理 proxy_cache_path 等真实有效配置优化媒体缓存。

nginx 中 proxy_cache_max_range_offset 优化媒体缓存

proxy_cache_max_range_offset 并不是 Nginx 官方模块（包括 ngx_http_proxy_module）的合法配置指令。它不存在于任何稳定版或主线版 Nginx 中（截至 2026 年 6 月），既不在官方文档里，也不被源码支持。

你在某些博客、错误配置片段或第三方补丁中看到的 proxy_cache_max_range_offset，极可能是以下情况之一：

混淆了 proxy_buffer_size、proxy_buffers 或 client_max_body_size 等指令；
误将 max_ranges（属于 http_core 模块，控制 HTTP Range 请求最多允许多少个 range）当作缓存相关参数；
引用了非标准 fork 版本（如某些定制化流媒体 Nginx 补丁），但这类补丁未被上游接纳，不具备通用性和维护性；
把前端播放器或 CDN 的私有参数错贴到 Nginx 配置中。

真正影响媒体文件（尤其是大视频、分片流）缓存效果的关键配置

如果你的目标是优化 Nginx 对视频、音频等媒体资源的 proxy cache 行为（比如支持断点续传、避免重复回源、提升首帧加载），应聚焦以下真实、有效、可验证的配置项：

✅ 正确启用 Range 请求缓存支持

Nginx 默认不缓存 Range 请求响应（即 206 Partial Content），因为 Cache-Control: no-store 常被源站自动添加，且 ETag/Last-Modified 在分片场景下易失效。需主动放开限制：

proxy_cache_valid 200 206 4h;        # 显式允许缓存 206 响应
proxy_cache_use_stale updating;      # 更新缓存时仍可返回旧内容（防卡顿）
proxy_ignore_headers Cache-Control;  # 忽略源站的 no-cache/no-store 指令（谨慎使用）
proxy_ignore_headers Expires;        # 同上，配合 Cache-Control 使用更稳妥
add_header X-Cache-Status $upstream_cache_status;

⚠️ 注意：proxy_ignore_headers Cache-Control 有风险，建议仅对可信源站（如内部媒资服务）启用，并搭配 proxy_cache_valid 明确设定过期时间。

✅ 合理设计 cache_key，确保 Range 请求命中同一缓存实体

默认 proxy_cache_key $scheme$proxy_host$request_uri 会把 Range: bytes=100-199 这样的请求视为不同 key（因 $request_uri 包含 query 或 header？不，实际不包含 header）。但若源站依赖 query 参数定位分片（如 /video.mp4?start=100&end=199），则需统一 key：

FastAPI Flask Proxy

FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。

下载

proxy_cache_key "$scheme$proxy_host$uri$is_args$args";
# 或更稳妥地剥离 Range 相关干扰（Nginx 本身不从 $uri 提取 Range，但若业务用 query 控制分片，就需保留）

真正关键的是：确保相同资源的不同 Range 请求，最终生成相同的 cache key。否则每个 range 都会单独缓存一份，浪费空间且无法复用。

✅ 配置足够大的缓存区与合理层级，适配大文件

百万级小图和单个 500MB 视频的缓存策略完全不同：

proxy_cache_path /var/cache/nginx/media_cache
  levels=2:2:2
  keys_zone=media_cache:200m
  max_size=2t
  inactive=30d
  use_temp_path=off;

levels=2:2:2 → 支持海量文件分散存储，避免单目录 inode 瓶颈；
keys_zone=200m → 每 1MB 内存约支持 8k 缓存条目，200MB 可管 ~160 万 key；
max_size=2t → 大容量磁盘配 SSD + XFS 文件系统（XFS 对大文件 + 多硬链接更友好）；
use_temp_path=off → 减少写入跳转，提升吞吐。

✅ 配合源站做切片友好型回源（推荐 HLS/DASH）

不要让 Nginx 直接缓存整段 GB 级视频。标准做法是：

源站将视频切为 .ts 或 .mp4 分片（如 video_1234567890_00001.ts）；
Nginx 缓存每个分片（小文件，易管理、易失效）；
利用 proxy_cache_valid 200 206 24h + inactive=7d 实现热分片常驻、冷分片自动清理；
通过 proxy_cache_lock on 防止多请求同时回源同一分片。

这样既规避了“单文件过大导致缓存写入慢、删除卡顿”，又天然支持并发加载与秒开。

总结

proxy_cache_max_range_offset 是无效指令，删掉或替换为真实可用配置；
媒体缓存优化核心在于：允许缓存 206、统一 cache_key、分片化存储、忽略干扰头、硬件与文件系统协同；
不要试图“强行缓存整个大视频”，而应推动架构向分片+边缘缓存演进；
所有配置务必通过 curl -H "Range: bytes=0-999" + 查看 X-Cache-Status 和磁盘缓存文件是否存在来验证。

不复杂但容易忽略。