一、起源
1.1 两类缓存的对象不同
Nginx 场景下的缓存分为两层,二者的缓存对象与失效控制方式都不同:
| 维度 | 浏览器缓存 | 反向代理缓存(proxy_cache) |
|---|---|---|
| 缓存位置 | 客户端 | Nginx 所在主机 |
| 缓存对象 | 响应内容与校验信息 | 后端响应 |
| 命中后是否到达服务端 | 强缓存命中时不产生请求 | 到达 Nginx 但不回源 |
| 失效控制 | 响应头 + 客户端行为(刷新、清缓存) | 缓存策略 + 主动清理 + 过期淘汰 |
| 主要收益 | 省去网络往返 | 省去后端计算与数据库查询 |
两层缓存可以叠加:静态资源命中浏览器缓存时不产生任何请求;未命中但命中代理缓存时不回源。
1.2 两类成本
- 重复传输成本:同一静态资源在多次页面访问中被重复下载,占用带宽并拉长首次渲染时间。
- 重复计算成本:动态接口的响应取决于后端计算与数据库查询,同一结果在短时间内被重复生成。
1.3 引入缓存的新增代价
- 一致性窗口:内容更新后,缓存中的旧副本在过期或被清除前仍会被返回。
- 失效判定的复杂度:需要区分"可共享"与"与用户相关"的响应,判定错误会把个性化内容发给其他用户。
- 资源占用:代理缓存占用磁盘与共享内存,极端情况下缓存目录写满会影响服务。
- 排障路径变长:同一次请求可能命中任意一层缓存,问题定位需要先确认命中层次。
1.4 取舍
- 静态资源优先交给浏览器缓存,代理缓存只承担跨用户共享的内容,避免两层都缓存同一份数据造成清理困难。
- 动态接口只在"响应对所有用户一致且允许短时间陈旧"时缓存;涉及登录态的响应必须排除在共享缓存之外。
- 缓存时间的选择依据是"内容可接受的陈旧时长",而不是"越长越好"。
二、原理
2.1 强缓存与协商缓存
浏览器缓存由响应头决定使用哪种模式:
| 模式 | 判定依据 | 命中后的行为 | 是否产生请求 |
|---|---|---|---|
| 强缓存 | Cache-Control: max-age 或 Expires 未过期 | 直接使用本地副本 | 不产生请求 |
| 协商缓存 | 强缓存过期或未声明,且响应带 ETag 或 Last-Modified | 带校验头发起请求,服务端返回 304 或 200 | 产生请求,但 304 无响应体 |
校验头的对应关系:
| 响应头 | 请求头 | 服务端判定 |
|---|---|---|
Last-Modified | If-Modified-Since | 文件修改时间未变化则返回 304 |
ETag | If-None-Match | 内容标识未变化则返回 304 |
两者的差别:Last-Modified 精度到秒,同一秒内的多次修改无法区分;ETag 基于内容标识,精度更高,但多实例部署时若标识生成规则包含节点信息会导致校验失效,表现为反复返回 200。
2.2 Cache-Control 指令的含义
| 指令 | 作用范围 | 含义 |
|---|---|---|
max-age=n | 私有与共享 | 相对过期时间,优先级高于 Expires |
s-maxage=n | 仅共享缓存 | 覆盖 max-age,只对代理缓存生效 |
no-cache | 私有与共享 | 允许缓存,但每次使用前必须向服务端校验 |
no-store | 私有与共享 | 完全不缓存,包括不写入磁盘 |
private | 共享缓存 | 禁止共享缓存存储,浏览器可存储 |
public | 共享缓存 | 允许共享缓存存储 |
must-revalidate | 私有与共享 | 过期后必须校验,禁止使用陈旧副本 |
immutable | 私有与共享 | 在有效期内不发起校验,适用于带指纹的资源 |
stale-while-revalidate=n | 共享 | 过期后 n 秒内可先用旧副本,同时后台更新 |
no-cache 与 no-store 常被混用:前者是"可以存但每次要校验",后者是"不存"。需要禁止留存的敏感响应应使用 no-store。
2.3 缓存决策流程
请求 -> 是否存在本地副本
|-- 无 -> 正常请求,按响应头决定是否存储
|-- 有 -> 强缓存是否有效
|-- 有效 -> 直接使用(不产生请求)
|-- 无效 -> 是否带校验头
|-- 是 -> 请求服务端(可能返回 304)
|-- 否 -> 正常请求
2.4 代理缓存的结构
proxy_cache_path 把缓存分为共享内存与磁盘两部分:
proxy_cache_path /var/cache/nginx/proxy
levels=1:2 # 目录层级,决定文件的目录分布
keys_zone=proxy_cache:10m # 共享内存区名称与大小
max_size=2g # 磁盘缓存上限
inactive=60m # 未被访问多久后淘汰
use_temp_path=off; # 直接写目标目录,减少一次重命名
- 共享内存(
keys_zone):存放键、元信息与引用计数,大小决定可缓存的键数量,不决定缓存数据量。键数量不足时表现为较早的缓存被提前淘汰。 - 磁盘目录:存放响应体与响应头。
levels=1:2表示两级子目录,用于分散文件、避免单目录文件数过多。 - 写文件时先在临时目录落盘再重命名,
use_temp_path=off让文件直接写目标目录,减少一次跨目录移动。
2.5 缓存键与有效性
| 指令 | 作用 | 默认值与常见改法 |
|---|---|---|
proxy_cache_key | 决定"什么算同一个缓存" | 默认含协议、proxy_host 与请求 URI;需要区分设备或语言时加入 $http_accept_language 等变量 |
proxy_cache_valid | 决定不同状态码的缓存时长 | 只写时长时仅对 200、301、302 生效;完全不声明该指令时,缓存时长改从响应头的 X-Accel-Expires、Expires、Cache-Control 中取得 |
proxy_cache_min_uses | 同一键被请求多少次后才缓存 | 默认 1,热点内容可提高以减少冷内容占用 |
proxy_cache_bypass | 条件成立时跳过读取但仍写入 | 常用于强制刷新(如带特定 Cookie 或参数) |
proxy_no_cache | 条件成立时不写入缓存 | 用于排除带 Set-Cookie 或错误页的响应 |
proxy_cache_revalidate | 过期后用校验头向后端确认 | 开启可减少重复传输完整响应体的开销 |
proxy_cache_key 选择错误是"缓存串号"的常见原因:键中缺少区分维度时,不同用户的响应会互相覆盖;键中包含过多变量时,命中率下降。
2.6 缓存状态
通过 $upstream_cache_status 观察当前请求与缓存的关系:
| 状态 | 含义 | 常见成因 |
|---|---|---|
MISS | 缓存中不存在,回源并写入 | 首次请求、刚被淘汰、键变化 |
HIT | 命中缓存,未回源 | 正常命中 |
EXPIRED | 存在但已过期,回源并更新 | 超过 proxy_cache_valid 时长 |
BYPASS | 因 proxy_cache_bypass 条件成立而跳过读取 | 强制刷新 |
STALE | 使用陈旧副本,因后端不可用且允许 | 配置了 proxy_cache_use_stale |
UPDATING | 正在使用陈旧副本同时后台更新 | 配置了后台更新 |
REVALIDATED | 校验通过,继续使用缓存 | 开启 proxy_cache_revalidate |
命中率由 HIT 与总请求数计算,观察方式见 3.3。
2.7 缓存锁与后台更新
热点键在失效瞬间会收到大量并发请求,若不做约束,这些请求会同时回源,形成回源风暴。
proxy_cache_lock on;:同一键在同一时刻只允许一个请求回源,其余请求等待;等待超时由proxy_cache_lock_timeout控制。proxy_cache_background_update on;:过期后由一个后台子请求更新缓存,当前请求先返回陈旧副本。proxy_cache_use_stale updating;:允许在后台更新期间返回陈旧副本,否则等待更新的请求会被阻塞。proxy_cache_use_stale error timeout http_500 http_502 http_504;:后端故障时返回陈旧副本,把故障对客户端表现为内容陈旧而非不可用。
这组配置把"缓存失效时的回源压力"从并发数降到 1,是缓存层抵御突发流量的主要手段。
2.8 淘汰与清理
缓存有两条淘汰路径,容易混淆:
| 路径 | 触发者 | 触发条件 |
|---|---|---|
inactive | cache manager | 文件在指定时间内未被访问,与容量无关 |
max_size | cache manager | 缓存总量超过上限时按最近最少使用淘汰 |
需要主动清理缓存时,开源版没有原生清除指令,可选手段:
- 删除缓存文件后由 cache loader 在下次启动时重建索引;重载或重启会影响共享内存中的索引。
- 使用第三方模块
ngx_cache_purge,通过一个受控的 location 按键清除。 - 接受"修改
proxy_cache_key中的版本变量"带来的整体失效,例如键中加入应用版本号,发版即视为全量刷新。 - 使用
proxy_cache_bypass配合内部参数实现单次强刷,但不清理已有副本。
2.9 与 Redis 缓存的边界
代理缓存与 Redis 缓存解决的不是同一个问题:
| 维度 | Nginx 代理缓存 | Redis 缓存 |
|---|---|---|
| 缓存粒度 | 整个 HTTP 响应 | 任意数据结构或计算结果 |
| 失效控制 | 时间驱动,主动清理能力弱 | 支持按键精确删除与事件失效 |
| 适用对象 | 多用户共享的完整响应 | 需要细粒度更新与复用计算结果的场景 |
| 一致性控制 | 弱,依赖过期时间 | 可选择多种更新顺序与一致性方案 |
判定方式:内容的失效需要精确控制时放 Redis;内容对所有用户一致且允许按时间过期时放代理缓存。两者混合使用时需要明确各自的失效路径,避免只清了一层而另一层仍在返回旧内容。
2.10 缓存不生效的常见原因
| 原因 | 表现 | 核对方式 |
|---|---|---|
响应带 Set-Cookie 或 Vary: * | 默认不写入缓存,始终 MISS | 查看后端响应头 |
响应带 Cache-Control: no-cache 或 private | 每次校验或不允许共享缓存存储 | 查看后端响应头 |
proxy_cache_bypass 条件恒为真 | 始终 BYPASS | 核对条件变量取值 |
| 缓存键中包含了每次变化的值 | 每次都是新键 | 打印 proxy_cache_key 实际取值 |
keys_zone 过小 | 缓存频繁被提前淘汰 | 观察键数量与内存区大小 |
后端响应头含 Vary 且维度多 | 命中率异常低 | 检查 Vary 头 |
| 请求方法不是 GET 或 HEAD | 不缓存 | 检查请求方法 |
后端以 X-Accel-Expires: 0 明确禁止 | 始终 MISS | 查看后端响应头 |
三、实现
3.1 浏览器缓存:静态资源与 HTML 分离
server {
listen 80;
server_name static.example.com;
root /usr/share/nginx/html;
# 带内容指纹的静态资源:长期强缓存,且不再校验
location ~* \.(js|css|woff2|png|jpg|jpeg|gif|svg|ico)$ {
expires 30d;
add_header Cache-Control "public, max-age=2592000, immutable";
etag on;
access_log off;
}
# HTML 入口:不缓存,保证发版后立即生效
location ~* \.html$ {
add_header Cache-Control "no-cache";
etag on;
}
# 禁止把带用户信息的接口响应写入共享缓存
location /api/ {
add_header Cache-Control "private, no-store";
proxy_pass http://backend;
}
}
要点:强缓存必须与文件名指纹配合。资源内容变化时文件名同时变化,才能既使用长缓存又保证更新生效;未加指纹的资源应使用较短的 max-age 或协商缓存。
3.2 反向代理缓存完整配置
http {
# 声明缓存目录与共享内存
proxy_cache_path /var/cache/nginx/proxy
levels=1:2
keys_zone=proxy_cache:20m
max_size=2g
inactive=60m
use_temp_path=off;
# 带 Set-Cookie 的响应默认不写入缓存;此处显式声明,
# 使配置含义不依赖默认行为,也避免日后开启 proxy_ignore_headers 时误缓存
map $upstream_http_set_cookie $no_cache_cookie {
default 1;
"" 0;
}
# 带特定参数时跳过读取缓存,实现单次强刷
map $arg_refresh $bypass_cache {
default 0;
"1" 1;
}
server {
listen 80;
server_name cache.example.com;
location /api/ {
proxy_pass http://backend;
proxy_cache proxy_cache;
proxy_cache_key "$scheme$request_method$host$request_uri";
proxy_cache_valid 200 302 10m;
proxy_cache_valid 404 1m;
proxy_cache_min_uses 2;
proxy_cache_revalidate on;
# 热点回源保护
proxy_cache_lock on;
proxy_cache_lock_timeout 5s;
proxy_cache_background_update on;
proxy_cache_use_stale error timeout updating http_500 http_502 http_504;
# 条件跳过与排除
proxy_cache_bypass $bypass_cache;
proxy_no_cache $no_cache_cookie;
# 传递客户端信息并输出命中状态
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $remote_addr;
add_header X-Cache-Status $upstream_cache_status;
}
}
}
3.3 命中率观测
# 在日志格式中包含缓存状态,便于按 URL 统计
log_format cache_main '$remote_addr - [$time_local] "$request" '
'$status $body_bytes_sent '
'rt=$request_time urt=$upstream_response_time '
'ua=$upstream_addr cs=$upstream_cache_status';
access_log /var/log/nginx/access.log cache_main;
# 缓存状态分布
awk '{for(i=1;i<=NF;i++) if($i ~ /^cs=/) print $i}' /var/log/nginx/access.log | sort | uniq -c | sort -rn
# 整体命中率(HIT 占非空状态的比例)
awk '{for(i=1;i<=NF;i++) if($i ~ /^cs=/){v=substr($i,4); if(v!="-"){t++; if(v=="HIT")h++}}} END {if(t>0) printf "hit=%.2f%% (%d/%d)\n", h/t*100, h, t}' /var/log/nginx/access.log
# 命中率最低的 URL(先按 URL 聚合再统计状态)
awk '{for(i=1;i<=NF;i++) if($i ~ /^cs=/){v=substr($i,4); if(v!="-"){t[$7]++; if(v=="HIT")h[$7]++}}} END {for(k in t) if(t[k]>20) printf "%.2f%% %d/%d %s\n", h[k]/t[k]*100, h[k], t[k], k}' /var/log/nginx/access.log | sort -n | head -20
# 缓存目录占用
du -sh /var/cache/nginx/proxy
find /var/cache/nginx/proxy -type f | wc -l
3.4 单次强刷与缓存清理
# 单次跳过缓存读取(配置了 proxy_cache_bypass $arg_refresh 时)
curl -s -i "http://cache.example.com/api/list?refresh=1" | grep -i x-cache-status
# 确认当前是否命中
curl -s -i http://cache.example.com/api/list | grep -i x-cache-status
# 按键定位缓存文件(键的 MD5 决定文件路径,可由第三方工具或日志辅助定位)
find /var/cache/nginx/proxy -type f -newermt '-10 minutes' | head
# 使用 ngx_cache_purge 时的清理方式(需要受控 location)
curl -s -X PURGE http://cache.example.com/api/list
清理后应再次请求并确认首个请求为 MISS、后续为 HIT,以验证清理确实生效。
3.5 验证命令
# 语法与配置核对
nginx -t
nginx -T | sed -n '/proxy_cache_path/,/;/p'
# 验证强缓存与协商缓存
curl -sI http://static.example.com/app.9f3c1a.js | grep -iE 'cache-control|etag|expires|last-modified'
curl -sI -H 'If-None-Match: "<etag>"' http://static.example.com/app.9f3c1a.js | head -1
# 验证第二次请求是否命中代理缓存
curl -s -o /dev/null -w "%{http_code} %{time_total}\n" http://cache.example.com/api/list
curl -s -o /dev/null -w "%{http_code} %{time_total}\n" http://cache.example.com/api/list
# 验证缓存锁:并发请求热点键,确认后端只收到一次回源
for i in $(seq 1 50); do curl -s -o /dev/null "http://cache.example.com/api/hot" & done; wait
grep -c 'cs=MISS' /var/log/nginx/access.log
# 验证后端故障时返回陈旧副本
# 停止后端后重复请求,观察状态是否为 STALE
curl -s -i http://cache.example.com/api/list | grep -i x-cache-status
3.6 分层缓存的感知路径
3.4 与 3.5 以 curl 为观察手段,每次只呈现一次请求的结果,命中层次的差别表现为状态字符串的不同。把两层缓存放进一段连续操作中观察,可以看到请求在哪一层被拦下,以及失效点如何逐层后移。
3.6.1 前置准备
- 准备一个带内容指纹的静态资源与一个走
proxy_cache的动态接口,两者的响应头需分别满足 2.10 节所列的缓存条件。 - 将
proxy_cache_valid临时调短(例如10s),使过期可在等待中观察到;生产常用的10m不适合作为观察对象。 - 浏览器开发者工具的网络面板中开启日志保持,并确认"禁用缓存"处于关闭状态。该选项开启时浏览器缓存层始终不参与,现象会与配置不符。
- 同时打开 Nginx 访问日志与后端访问日志的实时输出:前者关注
cs=与urt=,后者关注是否新增记录。
3.6.2 四段观察序列
| 阶段 | 操作 | 请求止于 | 开发者工具表现 | Nginx 状态 | 后端日志 |
|---|---|---|---|---|---|
| 一 | 首次访问 | 后端源站 | Size 为完整体量,Time 为完整网络耗时 | MISS | 新增一条 |
| 二 | 地址栏回车再次访问 | 浏览器缓存 | Size 显示 disk cache 或 memory cache,Time 接近 0 | 无新增记录 | 无新增记录 |
| 三 | 清空浏览器缓存后访问 | Nginx 代理缓存 | Size 仍为完整体量,Time 明显短于阶段一 | HIT | 无新增记录 |
| 四 | 等待超过缓存有效期后访问 | 后端源站 | Size 为完整体量,Time 回到阶段一的量级 | EXPIRED | 新增一条 |
两个补充观察:
- 删除缓存文件、重载配置或改变
proxy_cache_key中的版本变量后,状态回到MISS,后端日志再次新增,对应两层缓存同时失效的情形。 - 停止后端后重复请求,状态为
STALE,客户端仍获得完整内容但内容为旧副本,对应以陈旧副本代替不可用的取舍。
3.6.3 判定与误判
命中层次的判定需要三类证据同时确认,单一证据容易得出相反结论:
- 开发者工具的网络面板:
Size显示disk cache或memory cache,说明未产生请求。 - Nginx 访问日志的
cs=:取值为HIT时,请求止于代理缓存。 - 后端访问日志:是否新增记录,用于确认回源是否真实发生。
两处容易误判:
- 阶段三的
Size仍为完整体量,原因是响应体确实被完整传回,只是由 Nginx 从本地磁盘读出而非从后端取得。因此Size不能作为代理缓存是否命中的依据,Time与urt=只能作为间接证据,cs=才是直接证据。 - 浏览器的强制刷新与清空缓存不等价:强制刷新会在请求中附加
no-cache,连协商缓存一并跳过;需要模拟首次访问的行为时,使用清空缓存更准确。协商缓存命中时状态码为 304、响应体为空,这一层发生在 Nginx 之前,与代理缓存无关。
3.7 常见问题归因
| 现象 | 常见原因 | 核对手段 |
|---|---|---|
| 强缓存不生效,每次仍发请求 | 同时设置了 no-cache,或响应头被上层覆盖 | 用 curl -I 核对最终响应头 |
| 协商缓存始终返回 200 | ETag 在多实例下不稳定,或后端忽略校验头 | 对比两次请求的 ETag |
代理缓存始终 MISS | 响应带 Set-Cookie、请求带 Authorization、方法非 GET | 按 2.10 逐项核对 |
| 命中率随时间剧烈波动 | 缓存键包含变化值,或 inactive 过短 | 观察键分布与缓存文件时间 |
| 缓存内容串号 | 缓存键缺少区分维度,或未排除 Set-Cookie 响应 | 检查键定义与 proxy_no_cache |
| 缓存失效瞬间后端压力升高 | 未开启缓存锁与后台更新 | 检查 proxy_cache_lock 与 use_stale updating |
| 磁盘被缓存写满 | max_size 未设置或设置过大 | 检查 max_size 与目录占用 |
| 更新内容后仍返回旧值 | 只清理了一层缓存,浏览器副本仍在有效期 | 同时核对浏览器缓存与代理缓存的状态 |
四、总结
- 浏览器缓存与代理缓存的对象不同,前者省网络往返,后者省后端计算;两层可以叠加,但不应缓存同一份内容造成清理困难。
- 强缓存由
Cache-Control: max-age或Expires决定,协商缓存由ETag与Last-Modified决定;no-cache是"需校验",no-store才是"不存储"。 - 长缓存必须与文件名指纹配合,否则更新无法生效;HTML 入口应使用
no-cache避免发版后仍加载旧页面。 keys_zone决定可缓存的键数量,max_size决定磁盘上限,inactive决定未被访问多久后淘汰,三者作用不同。- 缓存键与
proxy_cache_valid决定"什么被缓存"与"缓存多久",配置错误是命中率异常与内容串号的主要原因。 proxy_cache_lock、proxy_cache_background_update、proxy_cache_use_stale组合起来把失效瞬间的并发回源降为一次,是缓存层抵御突发流量的关键。- 开源版缺少原生清理能力,需要删除文件、引入第三方模块或使用版本化缓存键实现失效。
- 需要精确控制失效时间的内容应放在 Redis 等可按键删除的存储中,代理缓存只承担按时间过期的共享内容。