Nginx 工程实践 -- 5. 代理缓存 proxy_cache

反向代理天然处在上游服务的必经之路上,在这里加一层缓存,可以让重复请求不再打到后端:降低源站压力、缩短首字节时间、并在源站抖动时用旧数据兜底。本篇讲清楚 proxy_cache 的存储结构、缓存键、失效与击穿保护。

flowchart TD
    A["请求"] --> B{"proxy_cache_bypass /
proxy_no_cache?"} B -->|"是"| U["回源 upstream"] B -->|"否"| C{"缓存命中?"} C -->|"命中未过期"| H["HIT 直接返回"] C -->|"命中已过期"| S["STALE / UPDATING
use_stale / cache_lock"] C -->|"未命中"| M["MISS 回源并写入缓存"]

一、缓存要解决什么

  • 源站压力:热点接口被反复请求,后端重复计算、查库;
  • 延迟:静态内容和"看起来静态"的响应,直接从磁盘返回;
  • 可用性:源站短暂故障时,用一份过期缓存继续服务,而不是直接 502。

它不解决"数据实时性"——缓存必然引入一致性问题,所以要先想清楚哪些接口可缓存、能容忍多久的旧数据。

二、缓存的层级

1
浏览器缓存 → CDN → 反向代理缓存(Nginx) → 应用/数据库
  • 浏览器缓存:Cache-Control / ETag,只对单个用户有效;
  • CDN:在离用户更近、规模更大的节点缓存,通常按 URL 全局共享;
  • 反向代理缓存:在源站前一跳,缓存粒度可控、能结合业务做 key 和失效;
  • 应用缓存:进程内或 Redis,处理更细粒度、更个性化的数据。

本节聚焦 Nginx 这一层。它适合缓存全局共享、更新不频繁、能容忍秒级到分钟级延迟的响应。

三、定义缓存区:proxy_cache_path

1
2
3
4
5
6
7
# http 块
proxy_cache_path /var/cache/nginx/api
levels=1:2
keys_zone=api:10m
inactive=60m
max_size=1g
use_temp_path=off;

| 参数 | 作用 | | :— | :— | — | :— | | levels | 缓存文件的目录层级。1:2 表示两级,第一级 1 个字符、第二级 2 个字符,避免单目录文件过多 | | keys_zone | 共享内存区,格式 名称:大小。存缓存键和元数据,不存响应体;大小按 key 数量规划 | | inactive | 超过该时间未被访问的缓存会被清理,即使还没过期 | | max_size | 缓存区总大小上限,超出后由 manager 进程按 LRU 清理 | | use_temp_path | off 时直接写最终文件,省掉"临时文件 + rename",通常更快 | | min_free | 保留的空闲空间 | | manager_* / loader_* | 管理进程和启动加载进程的频率/批量参数 | | purger_* | 主动清理(purger)相关参数,需配合 purger 能力 |

同一个缓存区可以在多个 location 复用;按业务/大小分开更利于排错。

四、缓存键:proxy_cache_key

默认值是:

1
proxy_cache_key $scheme$proxy_host$request_uri;

等价于 $scheme$proxy_host$uri$is_args$args。也就是说,协议 + 代理目标 + URI(含查询串) 决定一个缓存条目。

需要区分"不同用户看到不同内容"时,把身份信息加入 key:

1
proxy_cache_key "$scheme$host$request_uri$cookie_session";

需要忽略某些参数时,先用 map 归一化,再放进 key,避免 ?t=123 这类随机参数把命中率打没。

五、什么时候不缓存

Nginx 默认会尊重上游的部分指令,不会缓存这些响应:

  • 上游带 Set-Cookie(默认不缓存,除非显式忽略);
  • 上游 Cache-Control 含 private / no-store;
  • 请求方法不在 proxy_cache_methods(默认 GET HEAD)。

相关开关:

1
2
3
4
proxy_cache_methods GET HEAD;   # 默认;要缓存 POST 才加
proxy_cache_min_uses 1; # 同一请求出现几次后才缓存,默认 1
proxy_cache_bypass $cookie_nocache $arg_nocache;
proxy_no_cache $http_authorization; # 带 Authorization 就不缓存

需要强制缓存某些"上游说不要缓存"的响应时,用 proxy_ignore_headers 忽略 Expires、Cache-Control、Set-Cookie、Vary 等——但这等于替业务做决定,慎用。

六、有效期与降级

1
2
3
4
5
6
7
8
9
proxy_cache_valid 200 302 10m;   # 按状态码覆盖有效期
proxy_cache_valid 404 1m;

proxy_cache_use_stale error timeout updating
http_500 http_502 http_503 http_504;

proxy_cache_background_update on;
proxy_cache_lock on;
proxy_cache_lock_timeout 5s;
  • proxy_cache_valid [code ...] time:覆盖上游给的有效期,适合统一缓存策略;
  • proxy_cache_use_stale:源站出现指定错误/超时时,先返回过期缓存;updating 表示"边回源边用旧缓存",需配合 proxy_cache_background_update on;
  • proxy_cache_lock:同一个 key 只放一个请求回源,其余请求等待或读旧缓存,防止缓存失效瞬间大量请求同时打到后端(击穿)。

七、失效与 purge

  • 被动失效:inactive 到期、max_size 超限后由 manager 清理;
  • 主动 purge:标准版 Nginx 的 proxy_cache_purge 通常来自第三方模块(如 ngx_cache_purge),也有商业版内置;
  • 临时绕过:proxy_cache_bypass 让某个请求跳过缓存,用于调试或强制刷新;
  • 精确失效:按 key 删除文件较繁琐,更常见的做法是版本化 key——资源变更时改变 URL 或 key 前缀,让旧缓存自然过期。

八、观测:$upstream_cache_status

1
2
add_header X-Cache-Status $upstream_cache_status always;
log_format cache '$remote_addr "$request" $upstream_cache_status $upstream_response_time';

常见取值:

值含义
MISS未命中,已回源
HIT命中缓存
EXPIRED缓存过期,已回源
STALE命中过期缓存(配合 use_stale)
UPDATING正在后台更新
BYPASS主动绕过缓存
REVALIDATED通过条件请求重新验证

排查命中率时,先看 X-Cache-Status 的分布,再决定是 key 太细、min_uses 太高,还是 inactive 太短。

九、完整配置模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
# ---- http 块 ----
proxy_cache_path /var/cache/nginx/api levels=1:2 keys_zone=api:10m
inactive=60m max_size=1g use_temp_path=off;

map $request_method $cacheable_method {
default 0;
GET 1;
HEAD 1;
}

# ---- server 块 ----
server {
listen 80;
server_name example.com;

location /api/ {
proxy_pass http://backend;
proxy_http_version 1.1;

proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

proxy_cache api;
proxy_cache_key "$scheme$host$request_uri";
proxy_cache_methods GET HEAD;
proxy_cache_valid 200 10m;
proxy_cache_valid 404 1m;
proxy_cache_bypass $cookie_nocache $arg_nocache;
proxy_no_cache $http_authorization;
proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
proxy_cache_lock on;

add_header X-Cache-Status $upstream_cache_status always;
}
}

十、常见问题

现象原因 / 处理
缓存了登录后的私有数据key 里没区分身份;用 proxy_no_cache $cookie_session; 或把身份加进 key
命中率很低key 含随机参数/时间戳;min_uses 过高;inactive 过短
失效瞬间后端被打爆开 proxy_cache_lock
源站挂了直接 502配 proxy_cache_use_stale,让旧缓存兜底
缓存区文件极多levels 层级不合理,或 max_size 设得过大
改了配置没生效缓存区元数据在共享内存,nginx -s reload 后旧条目仍在;确认是否命中了旧 key

参考链接

  1. Nginx 官方文档:ngx_http_proxy_module —— proxy_cache* 系列指令;
  2. Nginx 官方文档:ngx_http_upstream_module —— $upstream_cache_status、$upstream_response_time;
  3. Nginx 官方文档:ngx_http_map_module —— 归一化缓存键;
  4. ngx_cache_purge(第三方模块) —— 主动清理 proxy / FastCGI / SCGI / uWSGI 缓存。

小结

proxy_cache_path 建缓存区,proxy_cache_key 定义"什么算同一条",proxy_cache_valid / proxy_cache_use_stale 管有效期与降级,proxy_cache_lock 防击穿。缓存不是银弹:先确认接口可缓存、能容忍多大延迟,再决定 key 和失效策略;上线后用 $upstream_cache_status 观测命中率。

系列导航


Nginx 工程实践 -- 5. 代理缓存 proxy_cache
https://bubao.github.io/posts/b4e2d3f5.html
作者
一念
发布于
2026年11月21日
许可协议