Nginx 工程实践 -- 18. proxy_cache 进阶:缓存键、分段缓存与清除

第 5 篇讲了 proxy_cache 的命中/失效与击穿保护。一旦缓存进入生产,真正决定"命中率"和"内存/磁盘是否被打爆"的,是缓存键怎么设计、大文件怎么缓存、过期内容怎么清。这篇深入这三块。

flowchart TD
    A["请求"] --> B["计算缓存键
proxy_cache_key"] B --> C["levels 分层目录
查找缓存"] C --> D{"命中且未过期?"} D -->|"是"| G["直接返回"] D -->|"否"| E["回源并写入"] E --> F["大文件按 slice 分段缓存
子响应各自命中"] H["清除"] -->|"版本化 URL 或 proxy_cache_purge"| C

一、缓存键:命中率的总开关

1
proxy_cache_key "$scheme$proxy_host$request_uri";

这是默认键:协议 + 上游主机 + 完整 URI。它的问题是把查询参数也算进去,?v=1 和 ?v=2 是两条缓存;反之,若两个上游共用同一缓存区,可能互相污染。

按需调整:

1
2
3
4
5
6
7
8
# 只按路径缓存,忽略参数
proxy_cache_key "$scheme$proxy_host$uri";

# 把客户端类型、地域纳入键,做差异化缓存
proxy_cache_key "$scheme$proxy_host$request_uri$http_accept_encoding";

# 带变量时注意:键里含 cookie 会让命中率骤降
proxy_cache_key "$request_uri$cookie_session";

要点:

  • 键里的变量越多,命中率越低、内存占用越大,要权衡;
  • 含 $cookie_*、$http_user_agent 这类高基数字段要非常谨慎;
  • 用 proxy_cache_key 自定义后,proxy_cache_valid 仍按状态码控制时长。

二、缓存区与分层目录

1
2
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=api:64m
inactive=60m max_size=10g use_temp_path=off;
  • levels=1:2:目录分层,避免单目录文件过多;
  • keys_zone=api:64m:共享内存区名与大小,存缓存键和元数据;
  • inactive:未被访问超过该时长的缓存被清理,即使没过期;
  • max_size:总容量上限,超限由 manager 进程按 LRU 淘汰;
  • use_temp_path=off:避免回源时先写临时文件再 rename,大文件场景可开。

三、slice:大文件分段缓存

大文件(安装包、视频)整文件缓存有两个问题:回源时第一个请求要等整个文件,且任意字节变化就整份失效。ngx_http_slice_module 把响应切成固定大小的段,每段独立缓存:

1
2
3
4
slice 1m;
proxy_cache_key "$uri$is_args$args$slice_range";
proxy_set_header Range $slice_range;
proxy_cache_valid 200 206 1d;
  • slice 1m:每段 1MB;
  • 需要回源时带上 Range 头,只取需要的段;
  • 客户端的 Range 请求会被拆成对多个缓存段的命中;
  • 缓存键里要带 $slice_range,否则段与段之间会串。

四、缓存清除

Nginx 开源版没有内置的缓存清除指令(proxy_cache_purge 属于第三方模块 ngx_cache_purge,或商业版功能)。工程上更稳妥的做法是版本化 URL:

1
2
3
4
5
# 内容变化时换路径或换查询串,旧缓存自然失效
location /static/ {
proxy_cache api;
proxy_cache_key "$uri";
}
  • 静态资源用内容哈希命名(app.3f2a.js),天然免清除;
  • 接口可在版本升级时改路径(/v2/...);
  • 必须主动清除时,可编译 ngx_cache_purge,用 proxy_cache_purge api "$uri";,但要注意它的匹配语义和安全边界(仅内网/加访问控制)。

五、锁与更新:击穿保护

第 5 篇提过 cache_lock、proxy_cache_use_stale updating。这里补一个组合:

1
2
3
proxy_cache_lock on;
proxy_cache_lock_timeout 5s;
proxy_cache_use_stale updating error timeout http_500;
  • cache_lock on:同一键只有一个请求回源,其余等待,避免缓存失效瞬间打爆上游;
  • updating:允许在后台更新时先返回旧数据;
  • 二者配合是高并发下保护上游的常用组合。

六、常见坑

坑说明
默认键含全部参数命中率被参数稀释,按需裁剪
键里放 cookie/UA高基数字段让缓存几乎无效
slice 不配 $slice_range段之间互相覆盖,内容错乱
大文件整份缓存回源慢、易整体失效,用 slice
依赖 inactive 控制过期它是"未访问清理",不是过期时间
指望开源版 proxy_cache_purge开源版没有,需第三方模块或版本化 URL
缓存区未配 max_size磁盘被缓存吃满

参考链接

  1. Nginx 官方文档:ngx_http_proxy_module(proxy_cache_key) —— 缓存键;
  2. Nginx 官方文档:ngx_http_proxy_module(proxy_cache_path) —— 缓存区参数;
  3. Nginx 官方文档:ngx_http_slice_module —— 分段缓存;
  4. Nginx 官方文档:ngx_http_proxy_module(proxy_cache_lock / use_stale) —— 击穿保护;
  5. ngx_cache_purge 项目 —— 第三方缓存清除模块。

小结

  • 缓存键决定命中率,默认键含全部参数,按需裁剪、避免高基数字段;
  • levels 分层、inactive/max_size 控制磁盘;
  • 大文件用 slice 分段缓存,键里带 $slice_range;
  • 开源版无内置清除,优先版本化 URL;
  • cache_lock + use_stale updating 组合防击穿。

系列导航


Nginx 工程实践 -- 18. proxy_cache 进阶:缓存键、分段缓存与清除
https://bubao.github.io/posts/c8d9e0f1.html
作者
一念
发布于
2026年11月21日
许可协议