Proxy slice cache

proxy_slice_cache 只服务媒体代理。它把上游媒体按 HTTP Range 切成片段缓存，减少重复拉取同一段视频的带宽和延迟。

它不是业务缓存，不放在 cache 下面；业务 L1/L2 缓存见 业务缓存。

工作模型

客户端常见请求：

Range: bytes=1048576-2097151

SyncTV 代理会把可按 Range 访问的上游媒体拆成固定 slice。后续请求命中相同 slice 时，可以从内存或文件后端返回。

proxy slice cache 只缓存可按 Range 切片的媒体字节；上游不支持 Range 时直接 bypass，不会把完整大文件写入缓存。

配置示例

data_dir: "/var/lib/synctv"

proxy_slice_cache:
  enabled: true
  slice_size_bytes: 2097152
  max_cache_size_bytes: 536870912
  segment_ttl_seconds: 300
  stale_max_age_seconds: 60
  stale_while_revalidate: true
  file_backend_enabled: true
  file_cache_dir: "cache/proxy-slice"
  eviction_interval_seconds: 60
  watermark_ratio: 0.875

上面配置的实际文件路径是：

/var/lib/synctv/cache/proxy-slice

字段

字段	默认值	调整场景	风险
proxy_slice_cache.enabled	true	需要完全关闭媒体 Range 分片缓存时	关闭后代理仍可工作，但重复播放会更多回源
proxy_slice_cache.slice_size_bytes	2097152	想调整单个 Range 分片大小时	太小会增加元数据和回源请求，太大降低复用率
proxy_slice_cache.max_cache_size_bytes	536870912	需要限制内存或文件后端总容量时	太小会频繁驱逐，太大需要更多内存或磁盘
proxy_slice_cache.segment_ttl_seconds	300	想改变分片新鲜期时	太短会增加回源，太长可能保留较旧内容
proxy_slice_cache.stale_max_age_seconds	60	允许过期分片短暂兜底时	太长会延迟内容刷新
proxy_slice_cache.stale_while_revalidate	true	希望过期命中时后台刷新而不是阻塞等待时	关闭后过期命中延迟更高
proxy_slice_cache.file_backend_enabled	false	希望缓存跨进程重启保留，且有持久化目录时	容器无可写卷时会启动失败或写入失败
proxy_slice_cache.file_cache_dir	""	文件后端要放到指定目录时	文件后端启用后为空会使用 data_dir/cache/proxy-slice 默认目录
proxy_slice_cache.eviction_interval_seconds	60	想调整后台容量清理频率时	太短增加后台开销，太长可能短时超出容量
proxy_slice_cache.watermark_ratio	0.875	想调整触发驱逐后的目标水位时	太高会频繁驱逐，太低会一次释放更多缓存

环境变量：

SYNCTV_PROXY_SLICE_CACHE_ENABLED=true
SYNCTV_PROXY_SLICE_CACHE_SLICE_SIZE_BYTES=2097152
SYNCTV_PROXY_SLICE_CACHE_MAX_CACHE_SIZE_BYTES=536870912
SYNCTV_PROXY_SLICE_CACHE_SEGMENT_TTL_SECONDS=300
SYNCTV_PROXY_SLICE_CACHE_STALE_MAX_AGE_SECONDS=60
SYNCTV_PROXY_SLICE_CACHE_STALE_WHILE_REVALIDATE=true
SYNCTV_PROXY_SLICE_CACHE_FILE_BACKEND_ENABLED=true
SYNCTV_PROXY_SLICE_CACHE_FILE_CACHE_DIR=cache/proxy-slice
SYNCTV_PROXY_SLICE_CACHE_EVICTION_INTERVAL_SECONDS=60
SYNCTV_PROXY_SLICE_CACHE_WATERMARK_RATIO=0.875

生产部署

单机生产如果启用文件后端，挂载 data_dir 或 file_cache_dir 到持久化卷，并预留清理策略和容量监控。

Kubernetes 多副本可以使用共享存储让文件跨副本可见，但当前索引是进程内维护，没有跨进程共享索引或分布式锁。不要把它当成强一致的多副本实时缓存。

工作边界

• 只缓存支持 Range 的上游响应。
• 不做 full-body cache。
• 上游不支持 Range 时直接 bypass；如果客户端请求完整内容，SyncTV 可以流式透传完整上游响应，但不会把它写成完整文件缓存。
• 是否启用只在进程启动时读取，不支持 CLI 或 runtime settings 动态启停。

常见问题

客户端不带 Range 时会缓存吗？

SyncTV 可以尝试用 Range 请求上游。上游支持 Range 时可进入 slice cache；上游拒绝或忽略 Range 时会 bypass。

bytes=-N 这种 suffix range 怎么办？

如果已有元数据能知道文件总大小，可以换算成具体范围并使用 slice cache。没有足够元数据时，SyncTV 不会为了 suffix range 额外强制 HEAD 探测，而是让上游原生处理。

缓存会不会返回旧文件？

SyncTV 会尽量使用 ETag、Content-Range 等信息判断一致性。流式返回过程中如果发现后续 slice 与前面缓存不一致，会中断连接，避免继续拼接混合版本的数据。