一、起源

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 判定与误判

命中层次的判定需要三类证据同时确认,单一证据容易得出相反结论:

  1. 开发者工具的网络面板:Size 显示 disk cache 或 memory cache,说明未产生请求。
  2. Nginx 访问日志的 cs=:取值为 HIT 时,请求止于代理缓存。
  3. 后端访问日志:是否新增记录,用于确认回源是否真实发生。

两处容易误判:

  • 阶段三的 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 与目录占用
更新内容后仍返回旧值 只清理了一层缓存,浏览器副本仍在有效期 同时核对浏览器缓存与代理缓存的状态

四、总结

  1. 浏览器缓存与代理缓存的对象不同,前者省网络往返,后者省后端计算;两层可以叠加,但不应缓存同一份内容造成清理困难。
  2. 强缓存由 Cache-Control: max-age 或 Expires 决定,协商缓存由 ETag 与 Last-Modified 决定;no-cache 是"需校验",no-store 才是"不存储"。
  3. 长缓存必须与文件名指纹配合,否则更新无法生效;HTML 入口应使用 no-cache 避免发版后仍加载旧页面。
  4. keys_zone 决定可缓存的键数量,max_size 决定磁盘上限,inactive 决定未被访问多久后淘汰,三者作用不同。
  5. 缓存键与 proxy_cache_valid 决定"什么被缓存"与"缓存多久",配置错误是命中率异常与内容串号的主要原因。
  6. proxy_cache_lock、proxy_cache_background_update、proxy_cache_use_stale 组合起来把失效瞬间的并发回源降为一次,是缓存层抵御突发流量的关键。
  7. 开源版缺少原生清理能力,需要删除文件、引入第三方模块或使用版本化缓存键实现失效。
  8. 需要精确控制失效时间的内容应放在 Redis 等可按键删除的存储中,代理缓存只承担按时间过期的共享内容。