Nginx 缓存体系:三层 key、七态 X-Cache-Status 与锁/stale 策略

这是《Nginx 从入门到精通》系列的第 8 篇(全系列 15 篇 + 4 个实战项目)。目标:给同一个站点配出「静态 7 天 + HTML 5 分钟 + API 按参数 60 秒」三层缓存,每层都能用 X-Cache-Status 逐条验证;能把 MISS / HIT / EXPIRED / REVALIDATED / STALE / UPDATING / BYPASS 七种状态跑出来看一遍 ,并复盘一次缓存串号、把 proxy_cache_key 修对。

前置 :第 5 篇(proxy_pass 与 upstream)、第 7 篇(zone/resolve/被动摘流);实验复用 lab/00-env(按需)。 本文所有数字与输出均为 nginx 1.30.6(stable)实测,文末附自测 5 题与延伸阅读。


1. 先跑起来(5 分钟实验)

缓存这件事的坑几乎都在「我以为它会缓存」和「我以为它只缓存了该缓存的」之间。所以第一个实验不给完整配置,只做一件事:让 X-Cache-Status 出现在响应头里 ,然后亲眼看到「同样的请求,一个永远不缓存」。不改 lab/00-env 里任何一个文件:把 lab 栈起起来(提供 app1/app2/app3),再挂一个一次性网关容器 (配置在 /tmp,端口 18081)加入 lab 的 compose 网络。

bash 复制代码
cd nginx/lab/00-env
docker compose up -d                       # lab-app1/2/3 healthy,lab-gateway 占 :8080
mkdir -p /tmp/ch08lab/extra && : > /tmp/ch08lab/extra/locations.conf
cat > /tmp/ch08lab/default.conf <<'NGX'
log_format exp '$remote_addr "$request" $status rt=$request_time ucs=$upstream_cache_status';
proxy_cache_path /tmp/cache levels=1:2 keys_zone=pc:10m max_size=500m inactive=60m use_temp_path=off;
upstream app_pool { server app1:8080; server app2:8080; server app3:8080; }
server {
    listen 80; server_name _;
    access_log /var/log/nginx/lab_access.log exp;
    location /api/  { proxy_pass http://app_pool/; proxy_cache pc; proxy_cache_valid 200 10s;
                      add_header X-Cache-Status $upstream_cache_status always; }
    location /api2/ { proxy_pass http://app_pool/; proxy_cache pc; proxy_cache_valid 200 10s;
                      proxy_ignore_headers Cache-Control;   # 与 /api/ 的唯一差别
                      add_header X-Cache-Status $upstream_cache_status always; }
    include /etc/nginx/conf.d/extra/locations.conf;         # 第 5 节的实验位置放这里(子目录躲开 *.conf 通配)
}
NGX
docker run -d --name ch08-hook --network nginx-lab_default -p 18081:80 \
  -v /tmp/ch08lab:/etc/nginx/conf.d:ro nginx:stable-alpine; sleep 2
bash 复制代码
# ① A 位置:连发三次 → MISS / MISS / MISS(三次都回源)
for i in 1 2 3; do curl -s -o /dev/null -D- localhost:18081/api/json | grep -i x-cache-status; done
# ② B 位置(只多了 proxy_ignore_headers Cache-Control)→ MISS / HIT / HIT
for i in 1 2 3; do curl -s -o /dev/null -D- localhost:18081/api2/json | grep -i x-cache-status; done
# ③ 慢后端(/api2/slow 落到上游 /slow,sleep 2s):第一次 MISS rt=2.06s,再执行 → HIT rt=0.066s
curl -s -o /dev/null -D- -w 'rt=%{time_total}\n' localhost:18081/api2/slow | grep -Ei 'x-cache|rt='

docker rm -f ch08-hook && docker compose down   # 先删挂在网络上的容器,否则网络删不掉

差异只有一个原因:lab/00-env/app/app.py 对所有 响应都加了 Cache-Control: no-store(第 49、53 行)。no-store 是一句「不许存」,优先级高于 proxy_cache_valid,所以 A 位置每次 MISS;proxy_ignore_headers Cache-Control 让网关无视这句话,B 位置才开始缓存。生产里这条指令是手术刀 不是默认值:上游说 no-store 通常有理由(个人化页面、订单、Token),该改的是上游输出的头。

2. 核心概念

2.1 缓存在这套拓扑里分三层(外加一层 CDN)

层 谁在做 控制手段 本章要不要配 用户看到的效果
浏览器 / CDN 用户浏览器、CDN 厂商 expires / Cache-Control: max-age、s-maxage / ETag + If-None-Match / Vary 要(/static/ 7 天),不给 CDN 单独配 完全不发请求(F5 除外),或只到 CDN 为止
网关 proxy 缓存 Nginx proxy_cache proxy_cache_path / proxy_cache_key / proxy_cache_valid 本章主战场 不用回源,毫秒级
上游应用缓存 Redis / 进程内 业务代码 不配 回源了但很快

每层各有各的键和过期时间,所以「为什么我看到旧数据」永远先问一句:是哪一层给的旧数据 。本章只管网关这一层,但必须知道第一层的开关是响应头(Cache-Control/Expires/Vary)。另外,PHP 场景把 proxy_* 换成 fastcgi_*、WSGI 换成 uwsgi_* 即可:fastcgi_cache_path/fastcgi_cache_key/fastcgi_cache_valid 与本章指令一一同构,差别只在上游协议。

2.2 一次请求在 proxy_cache 里的判定链

text 复制代码
方法 ∈ {GET,HEAD} 且达 proxy_cache_min_uses ? ──否──> 直接回源,不缓存
   是 → 按 proxy_cache_key 算 key、查 zone 元数据
   ├─ 无条目 ─────────────────────────> 回源,再看响应能不能存(下表)
   ├─ 未过期 ─────────────────────────> HIT(毫秒级)
   ├─ 已过期 + revalidate on ──────────> 条件请求:304 → REVALIDATED / 200 → EXPIRED
   ├─ 已过期 + background_update on ───> 立刻回旧体 + 后台刷新:STALE / UPDATING
   └─ 回源失败 + use_stale 命中 ───────> STALE(宁可旧,不可 502)

「响应能不能存」的判据(官方文档口径,优先级从高到低):

判据 效果 说明
X-Accel-Expires: 0 不缓存 响应头里显式禁止;@时间戳 表示绝对过期时刻
X-Accel-Expires: N 缓存 N 秒 优先级高于 Cache-Control/Expires
Cache-Control: no-store / private / no-cache 不缓存 lab 的 app.py 就是踩这条
Set-Cookie 不缓存 默认行为 ,所以登录态页面天然不缓存;要缓存得 proxy_ignore_headers Set-Cookie
Vary: * / Vary: Xxx 前者不缓存;后者按该请求头分桶(均 ≥1.7.7) 实测见实验 2:别指望 Vary 替你补 key 维度
都没有 用 proxy_cache_valid 若 proxy_cache_valid 也没写 → 永不缓存(见坑 5)

2.3 X-Cache-Status 的七种取值(全部实测)

值 含义 本文实测触发方式 上线看它干什么
MISS 没命中,已回源并(尝试)写入 首次请求 命中率的分母
HIT 命中且未过期 第二次同 URL 请求 命中率的分子
EXPIRED 命中但过期,回源整份重取 proxy_cache_valid 200 2s 后等 3 秒 说明 TTL 太短或上游无 ETag
REVALIDATED 过期后用条件请求换到 304,复用旧体 proxy_cache_revalidate on + 源站有 ETag 最经济的刷新方式
STALE 回源失败/正在刷新,用旧值兜底 proxy_cache_use_stale 且后端全停 上游故障时用户是否还能看见页面
UPDATING 旧值已返回,后台正在刷新 proxy_cache_background_update on + 刷新窗口内并发 stale-while-revalidate 的现场
BYPASS 本次跳过缓存(proxy_cache_bypass 命中) 带 Cookie: nocache=1 排查「为什么这个用户永远回源」

常被说成「六态」,官方文档的取值是七个(多了 UPDATING,$upstream_cache_status 自 0.8.3 起提供)。本文把七个全跑了一遍,因为 UPDATING 恰恰是「后台刷新是否生效」的唯一证据。

2.4 缓存 key 就是身份:默认值与必须补的维度

proxy_cache_key 默认是 $scheme$proxy_host$request_uri(官方文档原句)。它只描述「哪个 URL」,不描述「谁在问」。所以真正的 key 设计是列出所有会让响应体不同的维度:

维度 变量 不加会怎样(实测/推演)
查询参数 $args(已含在 $request_uri 里) 参数不同被视为不同资源------这部分默认是对的;但 ?a=1&b=2 与 ?b=2&a=1 是两条缓存,白白降低命中率
用户身份 $cookie_sid / $http_authorization 串号:B 用户拿到 A 用户的页面(实验 2 实测)
压缩维度 $http_accept_encoding 乱码 :缓存里存了 gzip 体,明文客户端直接拿到 1f 8b(实验 2 实测)
设备/终端 $http_user_agent 的归一化结果 移动端页面发给 PC;维度太细会击穿命中率,建议用 map 归成 3 类
站点 / 语言 $host / $http_accept_language 多域名互相污染;英文用户看到中文页

一条经验:key 里的变量越少,命中率越高、串号风险越大。宁可让 key 稍微多一维(失掉一点命中率),也不能让不同用户的响应共用同一条缓存。

2.5 三种「让它提前失效」的手段

手段 写法 适用 代价
TTL proxy_cache_valid 200 5m; 一切常规内容 最长滞后 = TTL
版本号进 key proxy_cache_key "$host$uri?$args&v=17"(发版时改数字) 静态资源、可预期的发布 需要发布流程配合;旧 key 等 inactive 回收
主动清除 开源版:直接删缓存文件 + nginx -s reload;或第三方 ngx_cache_purge 模块;官方 proxy_cache_purge/proxy_cache_path purger= 属商业订阅 内容运营、紧急下架 删文件会丢元数据一致性,重载是必须的一步

生产建议:版本号 + TTL 兜底;purge 是锦上添花,不是架构基石------网关一重启 purge 通道就没了。

2.6 三种事故模式

模式 现象 根因 证据 正解
串号 用户 A 看到用户 B 的页面/接口数据 key 缺用户维度;或上游 Set-Cookie 被 proxy_ignore_headers 粗暴忽略 X-Cache-Status: HIT + 响应体里出现别人的 Cookie/Authorization key 补维度,或对个人化路径 proxy_no_cache 1
放大 命中率很高但内存/磁盘吃紧,或缓存被无数种 key 装满 key 维度太细(完整 UA、时间戳、随机参数) keys_zone 满、max_size 反复淘汰、MISS 率反而高 key 只留影响响应体的维度,无关参数用 map 归一
雪崩 到点整批缓存同时过期,上游瞬时被打满 同一批 key 用同一个 TTL 写入 固定时刻 QPS 尖峰 + MISS 齐涨 proxy_cache_lock on、use_stale updating + background_update on、TTL 加抖动

3. 指令详解

指令 默认值 上下文 说明与坑
proxy_cache_path(含 use_temp_path) ---(必写);use_temp_path 默认 on(≥1.7.10) http 定缓存盘:levels=1:2 是两层子目录(文件名 = key 的 MD5),keys_zone=pc:10m 存元数据(1MB≈8000 key ),max_size 超限按 LRU 删,inactive(默认 10m)是「没被访问就删」。use_temp_path on 会先写临时目录再跨目录改名,不同盘就变成整份拷贝 → 必须 off
proxy_cache off http/server/location 指定用哪个 keys_zone。off 会关掉上层继承的缓存,不是「什么都不做」
proxy_cache_key $scheme$proxy_host$request_uri 同上 身份定义。默认值不含用户/压缩维度,是串号与乱码的总根源
proxy_cache_valid ---(不写则只能靠上游头的 Expires/Cache-Control) 同上 只写时间(proxy_cache_valid 5m;)时只作用于 200/301/302;要按码定制就逐个写。不写它 + 上游也没有缓存头 = 永远 MISS(实测见坑 5)
proxy_cache_methods / _min_uses GET HEAD / 1 同上 想把 POST 也缓存必须显式加,且 key 要含 $request_body,否则必串号;min_uses 2 可挡爬虫把冷数据写满磁盘,代价是热点要两次才进缓存
proxy_cache_lock off 同上 同一个 key 只放一个请求回源,其余排队等(击穿保护)。十并发冷请求实测:关 10 次回源、开 1 次回源(实验 5)
proxy_cache_lock_timeout / _lock_age 均 5s 同上 前者是排队等锁上限(超时后自己回源且不写缓存,设太短等于没锁);后者是「持锁请求太慢就再放一个」
proxy_cache_use_stale / _background_update 均 off(后者 ≥1.11.10) 同上 前者:回源失败返回旧值,常用 error timeout updating http_500 http_502 http_503 http_504(少写 http_502 就会在上游重启时给用户看 502);后者:过期即回旧值 + 后台刷新,必须把 updating 放进去才生效
proxy_cache_revalidate off(≥1.5.7) 同上 过期后用 If-None-Match/If-Modified-Since 换 304,省流量又保鲜。上游没 ETag/Last-Modified 就等于没开
proxy_cache_bypass / proxy_no_cache 空 location(if in location) 前者「本次不读缓存」,后者「本次不写缓存」。值非空且非 0 即生效;生产常写 $cookie_nocache $http_authorization
proxy_ignore_headers --- http/server/location 可忽略 X-Accel-Expires/Expires/Cache-Control/Set-Cookie/Vary 等。能不用就不用,忽略等于把上游的保护拆了
slice 0(关闭,≥1.9.8) 同上 大文件按块缓存:slice 1m; + key 里加 $slice_range + 缓存 206。1MB 块太少会「打开大量文件」,太大则大文件首字节慢
add_header ... always 无 同上 X-Cache-Status 必须带 always(≥1.7.5),否则 5xx/304 响应里看不到,恰好是最需要看的场景

4. 完整配置示例

下面这份是「可以落地的三层缓存」:静态交给浏览器、HTML 交给网关短缓存、API 按参数短缓存。

nginx 复制代码
# /etc/nginx/lab/nginx.conf(容器用 -c 指定;校验必须带 -c)
user  nginx;
worker_processes  1;
error_log  /var/log/nginx/lab_error.log warn;
pid        /var/run/nginx.pid;

events { worker_connections  1024; }

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    # 2.3 的前提:把 ucs 打进访问日志,事后才能算命中率
    log_format  main  '$remote_addr - $remote_user "$request" '
                      '$status $body_bytes_sent rt=$request_time '
                      'urt=$upstream_response_time up=$upstream_addr '
                      'ucs=$upstream_cache_status xff="$http_x_forwarded_for"';
    access_log  /var/log/nginx/lab_access.log  main;

    sendfile           on;
    keepalive_timeout  65;
    gzip on;
    gzip_vary on;                                  # 让下游知道同一 URL 有多种编码
    gzip_types text/css application/javascript application/json text/plain;

    resolver 127.0.0.11 valid=5s ipv6=off;

    # 两个盘:页面缓存小、分片缓存大,分开便于各自设 max_size 与淘汰策略
    proxy_cache_path /data/cache      levels=1:2 keys_zone=pc:10m  max_size=2g  inactive=60m use_temp_path=off;
    proxy_cache_path /data/cache_file levels=1:2 keys_zone=pcf:10m max_size=20g inactive=6h  use_temp_path=off;

    # 带 Authorization 的请求既不读也不写缓存(默认行为不会替你排除,见坑 2)
    map $http_authorization $skip_cache { default 1; "" 0; }

    upstream app_pool {
        zone app_pool 64k;
        server app1:8080 resolve max_fails=3 fail_timeout=10s;
        server app2:8080 resolve max_fails=3 fail_timeout=10s;
        server app3:8080 resolve max_fails=3 fail_timeout=10s;
    }

    server {
        listen 80;
        server_name _;
        root  /usr/share/nginx/html;
        index index.html;
        # ---- L1 静态:只做客户端缓存,7 天,网关不落盘 ----
        location /static/ {
            alias /usr/share/nginx/html/;
            expires 7d;                             # 生成 Expires + Cache-Control: max-age=604800
            add_header Cache-Control "public";      # 注意:会与上面那条并存,见坑 6
            access_log off;
        }

        # ---- L2 HTML:网关缓存 5 分钟 + 击穿保护 + 旧值兜底 ----
        location / {
            proxy_pass http://app_pool;
            proxy_set_header Host $host;
            proxy_cache pc;
            proxy_cache_key "$scheme$host$request_uri|ae=$http_accept_encoding";
            proxy_cache_valid 200 5m;  proxy_cache_valid 404 1m;
            proxy_cache_lock on; proxy_cache_lock_timeout 5s;   # 同一 key 只放一个回源
            proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
            proxy_cache_background_update on;       # 先给旧值,后台刷新
            proxy_cache_bypass $cookie_nocache $skip_cache;  proxy_no_cache $cookie_nocache $skip_cache;
            add_header X-Cache-Status $upstream_cache_status always;
        }

        # ---- L3 API:按 uri+args 缓存 60 秒,个人化请求一律绕开 ----
        location /api/ {
            proxy_pass http://app_pool/;
            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_connect_timeout 2s;
            proxy_cache pc;
            proxy_cache_key "$scheme$host$uri?$args|ae=$http_accept_encoding";
            proxy_cache_valid 200 60s;  proxy_cache_valid 404 10s;
            proxy_cache_min_uses 2;                 # 一次性参数别占盘
            proxy_cache_use_stale error timeout http_502 http_503 http_504;
            proxy_cache_bypass $cookie_nocache $http_authorization;  proxy_no_cache $cookie_nocache $http_authorization;
            add_header X-Cache-Status $upstream_cache_status always;
        }

        # ---- 大文件:1MB 分片缓存(视频/镜像/安装包)----
        location /dl/ {
            proxy_pass http://app_pool;
            slice 1m; proxy_cache pcf;              # slice ≥1.9.8
            proxy_cache_key "$host$request_uri$slice_range";
            proxy_cache_valid 200 206 1h;           # 206 必须显式允许
            proxy_set_header Range $slice_range;
            add_header X-Cache-Status $upstream_cache_status always;
        }

        location = /healthz { access_log off; return 200 "gateway ok\n"; }
        location /nginx_status { stub_status; allow 127.0.0.1; deny all; }
    }
}

相对 lab/00-env 改了这几处(其余原样保留):

# 位置 改动 为什么
1 http 新增两条 proxy_cache_path(/data/cache、/data/cache_file) 缓存必须先有盘和 zone;use_temp_path=off 避免跨目录拷贝
2 http 新增 map $http_authorization $skip_cache 开源版默认不因 Authorization 跳过缓存(实验 2 实测),必须自己挡
3 log_format main 末尾加 ucs=$upstream_cache_status 命中率只能从日志算,不能靠感觉
4 location / 原来是 try_files,现在改为 proxy_pass 到 app_pool 并挂 proxy_cache pc 让 HTML 走网关缓存(静态回退改用 /static/)
5 location /api/ 与新增 location /dl/ API 加 proxy_cache 一组 + proxy_connect_timeout 2s;大文件加 slice 分片缓存(并补 gzip_vary on) API 可控缓存、大文件按块命中;gzip_vary 让压缩维度对下游可见

缓存目录的落地位置:/data/cache。若容器内没有该目录,nginx -t 会直接报 proxy_cache_path ... failed(目录不存在),必须先 mkdir -p /data/cache /data/cache_file 或把它挂成 volume。

5. 必做实验

实验台沿用第 1 节的一次性网关(:18081),再补一个静态源 ch08-origin(自带 ETag、支持 Range)------EXPIRED/REVALIDATED 与 slice 都靠它。把实验位置一次写进第 1 节预留的 extra/locations.conf,五个实验直接复用:

bash 复制代码
mkdir -p /tmp/ch08html
head -c 5242880 /dev/urandom > /tmp/ch08html/big.bin        # slice 用的 5MB 文件
printf '<h1>hello cache</h1>\n' > /tmp/ch08html/page.html    # 有 ETag / Last-Modified
cat > /tmp/ch08origin.conf <<'NGX'                          # gzip on 但 gzip_vary off
server { listen 80; root /srv/www; gzip on; gzip_vary off; gzip_min_length 1; access_log /var/log/nginx/origin_access.log; }
NGX
docker run -d --name ch08-origin --network nginx-lab_default \
  -v /tmp/ch08html:/srv/www:ro -v /tmp/ch08origin.conf:/etc/nginx/conf.d/default.conf:ro nginx:stable-alpine
cat > /tmp/ch08lab/extra/locations.conf <<'NGX'   # 只放 location,被第 1 节 server{} 的 include 拉进去
location /leak/    { proxy_pass http://app_pool/; proxy_cache pc; proxy_cache_valid 200 10s; proxy_cache_key "$scheme$proxy_host$request_uri"; proxy_ignore_headers Cache-Control; add_header X-Cache-Status $upstream_cache_status always; }
location /fixed/   { proxy_pass http://app_pool/; proxy_cache pc; proxy_cache_valid 200 10s; proxy_cache_key "$scheme$proxy_host$request_uri|c=$cookie_sid"; proxy_ignore_headers Cache-Control; add_header X-Cache-Status $upstream_cache_status always; }
location /stale3/  { proxy_pass http://app_pool/slow; proxy_connect_timeout 1s; proxy_cache pc; proxy_cache_valid 200 5s; proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504; proxy_cache_background_update on; proxy_ignore_headers Cache-Control; add_header X-Cache-Status $upstream_cache_status always; }
location /nolock/  { proxy_pass http://app_pool/slow; proxy_cache pc; proxy_cache_valid 200 10s; proxy_ignore_headers Cache-Control; add_header X-Cache-Status $upstream_cache_status always; }
location /lock/    { proxy_pass http://app_pool/slow; proxy_cache pc; proxy_cache_valid 200 10s; proxy_cache_lock on; proxy_ignore_headers Cache-Control; add_header X-Cache-Status $upstream_cache_status always; }
location /reval/   { proxy_pass http://file_origin/; proxy_cache pc; proxy_cache_valid 200 2s; proxy_cache_revalidate on; add_header X-Cache-Status $upstream_cache_status always; }
location /noreval/ { proxy_pass http://file_origin/; proxy_cache pc; proxy_cache_valid 200 2s; add_header X-Cache-Status $upstream_cache_status always; }
location /gzbad/   { proxy_pass http://file_origin/; proxy_cache pc; proxy_cache_valid 200 10s; proxy_cache_key "$scheme$proxy_host$request_uri"; add_header X-Cache-Status $upstream_cache_status always; }
location /dl/      { proxy_pass http://file_origin/; slice 1m; proxy_cache pcf; proxy_cache_key "$host$request_uri$slice_range"; proxy_cache_valid 200 206 1h; proxy_set_header Range $slice_range; add_header X-Cache-Status $upstream_cache_status always; }
NGX
echo 'proxy_cache_path /tmp/cachefile levels=1:2 keys_zone=pcf:10m max_size=1g inactive=60m use_temp_path=off;' >> /tmp/ch08lab/default.conf
echo 'upstream file_origin { server ch08-origin:80; }' >> /tmp/ch08lab/default.conf   # 这两行在 http 段
docker exec ch08-hook nginx -t && docker exec ch08-hook nginx -s reload   # 之后改配置都走这两步 + 清缓存

实验 1:命中与不命中的耗时差,以及 $args 是 key 的一部分

bash 复制代码
s() { curl -s -o /dev/null -D h.txt "$1"; printf '%-46s %s\n' "$1" \
      "$(grep -i '^x-cache-status' h.txt | tr -d '\r' | cut -d' ' -f2)"; }
s localhost:18081/api2/json ; s localhost:18081/api2/json      # MISS 然后 HIT
s localhost:18081/api2/json?x=1 ; s localhost:18081/api2/json?x=1   # MISS / HIT
s localhost:18081/api2/json?x=2                                 # MISS(新参数=新资源)
s 'localhost:18081/api2/json?y=1&x=1' ; s 'localhost:18081/api2/json?x=1&y=1'   # 都是 MISS(& 要加引号)
观测 实测 为什么
命中耗时 MISS rt=2.01--2.06s → HIT rt=0.002--0.066s(后端 sleep 2s 的路径) 命中不建上游连接,只有内存查 key + 读盘
?x=1 / ?x=2 各自独立 MISS $request_uri 含 query string,不同参数天然不同 key
?y=1&x=1 vs ?x=1&y=1 两条都 MISS key 是字符串比较、不排序;前端统一参数顺序能显著提高命中率

实验 2:key 缺维度的两种真实事故:串号与乱码

bash 复制代码
# ① 串号:key 只有 URL(/leak/)→ bob 拿到 alice 的 Cookie,且 ucs=HIT
curl -s -H 'Cookie: sid=alice' localhost:18081/leak/json | grep '"Cookie"'      # "sid=alice"
curl -s -H 'Cookie: sid=bob'   localhost:18081/leak/json | grep '"Cookie"'      # 还是 alice!
curl -s -H 'Cookie: sid=bob'   localhost:18081/fixed/json | grep '"Cookie"'     # ② 修法:key 加 $cookie_sid → "sid=bob"
# ③ 乱码:源站 gzip on + gzip_vary off,key 无压缩维度
curl -s --compressed -o g1 -D h.txt localhost:18081/gzbad/page.html   # MISS + Content-Encoding: gzip
curl -s              -o g2 -D h.txt localhost:18081/gzbad/page.html   # HIT
head -c 8 g2 | od -A n -t x1                                          # 1f 8b 08 00 ...
观测 实测 结论
别人的 Cookie "sid=alice" 出现在 bob 的响应里,状态 HIT 串号不需要 CVE,只要 key 少一维
修 key 后 alice / bob 各 MISS 一次,之后各自 HIT 多一维 key 买的是「不串号」
明文客户端 HIT + Content-Encoding: gzip + 首字节 1f 8b 这就是最常见的「gzip 乱码」事故的完整复现

为什么 :gzip_vary off 意味着源站不告诉下游「同一 URL 有编码变体」,而 key 里又没有 $http_accept_encoding,于是压缩体被当成唯一版本存下来。两种修法都实测过:key 加 |ae=$http_accept_encoding 后 gzip/明文各一条(MISS、MISS、HIT、HIT);或在代理侧写 proxy_set_header Accept-Encoding ""; 让源站永远回明文、由网关自己 gzip on(所有客户端共用一条明文缓存,命中率最高,代价是网关多耗 CPU)。

实验 3:过期之后的两种走法:EXPIRED 与 REVALIDATED

用静态源(自带 ETag/Last-Modified)对照 /noreval/(默认)与 /reval/(proxy_cache_revalidate on),两者都 proxy_cache_valid 200 2s:

bash 复制代码
s localhost:18081/reval/page.html?u=9 ; sleep 3 ; s localhost:18081/reval/page.html?u=9
s localhost:18081/noreval/page.html?z=1 ; sleep 3 ; s localhost:18081/noreval/page.html?z=1
docker exec ch08-origin tail -5 /var/log/nginx/origin_access.log
位置 状态序列 源站日志 含义
/reval/ MISS → HIT → REVALIDATED → REVALIDATED 200 → 304 0 → 304 0 过期后只发条件请求,304 无响应体,流量≈0
/noreval/ MISS → HIT → EXPIRED 200 过期即整份重取,浪费带宽与上游 CPU

结论:只要上游有 ETag 或 Last-Modified 就打开 proxy_cache_revalidate on------它是「既不返回旧数据、又不重复传大文件」的唯一手段。

实验 4:上游宕机:STALE、UPDATING 与「冷 URL 一定失败」

bash 复制代码
s localhost:18081/stale3/ ; s localhost:18081/stale3/   # MISS 2.005s → HIT 0.001s;sleep 6 后条目过期
s localhost:18081/stale3/ & sleep 0.3 ; s localhost:18081/stale3/ & sleep 0.3 ; s localhost:18081/stale3/ & wait
#   STALE 0.002s / UPDATING 0.0017s / UPDATING 0.0025s   ← 三个请求全在毫秒级返回旧值
sleep 3 ; s localhost:18081/stale3/                      # HIT(后台刷新已完成)
docker stop lab-app1 lab-app2 lab-app3                   # 后端全停
curl -s -o b.txt -D h.txt -w 'code=%{http_code} rt=%{time_total}s\n' localhost:18081/stale3/
# code=200 rt=0.016517s  X-Cache-Status: STALE   正文仍是 app=app1 / path=/slow
curl -s -o /dev/null -D h.txt -w 'code=%{http_code} rt=%{time_total}s\n' localhost:18081/stale3/coldkey9   # code=504 rt=3.018420s  ucs=MISS
docker start lab-app1 lab-app2 lab-app3

三条结论:① 有旧值就一定能看到 STALE (上游全挂时用户仍拿 200);② 没有旧值就一定失败 ------冷 URL 在三个后端全停时是 504,耗时 3.02s ≈ 3 台 × proxy_connect_timeout 1s;③ UPDATING 只出现在后台刷新窗口内 ,窗口长度≈上游响应时间,所以它是验证 background_update 是否真生效的唯一证据。这就是「雪崩」的兜底:use_stale updating + background_update on + proxy_cache_lock on。

实验 5:击穿保护与分片缓存

bash 复制代码
run() { docker exec ch08-hook sh -c "rm -rf /tmp/cache/*; : > /var/log/nginx/lab_access.log"; docker exec ch08-hook nginx -s reload >/dev/null; sleep 1.5
        for i in $(seq 10); do curl -s -o /dev/null -w "%{time_total}\n" "localhost:18081/$1" & done | sort -n | sed -n '1p;10p'; wait
        docker exec ch08-hook sh -c "grep '$1' /var/log/nginx/lab_access.log | awk '{print \$NF}' | sort | uniq -c"; }
run nolock/cold-a    # 10 ucs=MISS       → 10 次回源,耗时都 ≈2.01s
run lock/cold-b      # 1 MISS + 9 HIT    → 只有 1 次回源,最慢 2.02--2.52s(看它等锁等了多久)
curl -s -o d1 -D h.txt -w '%{http_code}\n' localhost:18081/dl/big.bin   # 200 MISS
docker exec ch08-hook sh -c 'find /tmp/cachefile -type f | wc -l'        # 5(5MB 切成 5 块)
curl -s -o d2 -D h.txt -w '%{http_code}\n' localhost:18081/dl/big.bin   # 200 HIT
curl -s -o d3 -D h.txt -w '%{http_code}\n' -H 'Range: bytes=0-2500000' localhost:18081/dl/big.bin  # 206 HIT
cmp d1 d2 && echo same
观测 实测 为什么
无锁十并发 10 条 MISS,耗时都 ≈2.01s 10 个请求各自回源,上游看到 10 倍流量------真雪崩时就是它压垮后端
有锁十并发 1 条 MISS + 9 条 HIT,最慢 2.02--2.52s 后 9 个排队等锁,锁释放后直接读刚写好的缓存;代价是最慢那个多等一段(实测 0--0.5s,取决于排队时刻)
5MB 文件 缓存目录出现 5 个 文件,第二次整取 HIT slice 1m 把响应切成 5 个可独立命中的块
Range: bytes=0-2500000 206 + HIT + Content-Range: bytes 0-2500000/5242880 跨块范围请求只取需要的块,这才是视频拖进度条能秒开的原因

6. 验收自测(5 题)

先盖住「答案要点」自己写一遍,再逐条对照;答不上来的回对应小节重读。

Q1. proxy_cache_valid 200 10s; 写了,proxy_cache_key 没写,上游返回 Cache-Control: no-store。请求会命中缓存吗?

答案要点:不会,永远 MISS。no-store 属于「响应能不能存」的判据,优先级高于 proxy_cache_valid;proxy_cache_valid 只在响应头里没有 X-Accel-Expires/Expires/Cache-Control 时才说话。要么让上游去掉 no-store,要么用 proxy_ignore_headers Cache-Control(有风险,见第 1 节)。默认 key 是 $scheme$proxy_host$request_uri,与这个问题无关。

Q2. 十个人同时请求一条还没缓存的慢接口,proxy_cache_lock on 之后上游会收到几次请求?最慢的那个人等多久?

答案要点:绝大多数情况只会有 1 次 回源(实测 10 并发冷请求:无锁 10 次,有锁 1 次 MISS + 9 次 HIT)。其余请求在 proxy_cache_lock_timeout(默认 5s)内排队,等锁释放后直接读刚写好的缓存;持锁请求若超过 proxy_cache_lock_age(默认 5s),会再放一个请求回源。实测最慢请求 2.02--2.52s(排队 0--0.5s),这是「用一点点延迟换上游十倍流量」的典型交易。

Q3. 缓存里有 5 分钟的旧页面,上游此刻挂了。用户会看到 502 还是旧页面?取决于哪条指令?

答案要点:取决于 proxy_cache_use_stale 是否包含 error/timeout/http_502 等条件。配了(且条目只是过期、未被 inactive 删除)→ 返回旧页面并标记 STALE(实测 200 + rt=0.0165s);没配 → 502/504。注意两个盲区:inactive 到期的条目会被真删,那时 use_stale 也无能为力;冷 URL(从没缓存过)在任何配置下都只能失败,实测三个后端全停时是 504、耗时 3.02s。

Q4. 你想让「静态 7 天、HTML 5 分钟、API 60 秒」同时成立,expires 7d 和 proxy_cache_valid 5m 分别作用在哪一层?

答案要点:expires 7d 只写响应头 (Expires + Cache-Control: max-age=604800),管浏览器/CDN 这一层,网关自己不留副本;proxy_cache_valid 200 5m 管网关 proxy_cache 的条目有效期,浏览器看不到它。两者互不替代。实践中 HTML 还要显式给客户端 Cache-Control: no-cache(或极短 max-age),否则浏览器 7 天不发请求,网关缓存再准也没机会更新。

Q5. 有用户反馈「同一个 URL 有时看到别人的数据,有时又正常」。给三条最可能的 key 缺陷和验证方法。

答案要点:① key 缺用户维度($cookie_sid/$http_authorization)------用两个不同 Cookie 连续请求,看响应体里的身份字段是否被别人覆盖(实验 2 实测:bob 拿到 sid=alice);② 上游发了 Set-Cookie 却被 proxy_ignore_headers Set-Cookie 忽略,等于把「按用户渲染」的响应缓存成公共资源------用 curl -D- 看响应是否带 Set-Cookie;③ proxy_cache_key 用了 $uri 而漏掉 $args,参数不同却共用条目------用 ?uid=A / ?uid=B 对打确认。统一验证入口:响应头 X-Cache-Status 是 HIT 且响应体身份不对,就一定是 key 问题,不是上游问题。

7. 常见坑

  1. 命中率怎么看都 0,但配置「看起来没问题」 。现象:X-Cache-Status 永远是 MISS。根因:上游发了 Cache-Control: no-store(lab 的 app.py 就是),或 Set-Cookie 未处理。正解:先 curl -D- 看上游响应头,再决定改上游还是 proxy_ignore_headers。
  2. 带 Authorization 的接口被缓存,A 用户拿到 B 的结果 。现象:换 Bearer 之后响应仍是 HIT。根因:开源版不会 因为 Authorization 自动跳过缓存(实验 2 实测),「Authorization 会绕过缓存」的说法不成立。正解:显式 proxy_cache_bypass $http_authorization; proxy_no_cache $http_authorization;。
  3. 磁盘 IO 高、缓存目录写满而 max_size 明明够 。现象:字节总量没到上限,盘却满了。根因:use_temp_path 默认 on(跨盘改名 = 整份拷贝);max_size 只管字节总量、不管 inode。正解:use_temp_path=off + 缓存盘单独挂载;监控 df -i,必要时 proxy_cache_min_uses 2 挡冷数据。
  4. 命中率极低、缓存目录一直很小 。现象:刚热起来的数据很快就没了。根因:inactive(默认 10m)是「没被访问就删」,比业务周期短时刚热就被丢;它与 proxy_cache_valid 是两个独立倒计时。正解:把 inactive 调到 ≥ 业务访问周期(如 60m),再用 ucs= 统计确认。
  5. 配了 proxy_cache pc 却一次都不缓存 。现象:状态永远 MISS。根因:既没写 proxy_cache_valid,上游也不给 Expires/Cache-Control:没有任何「能存多久」的依据 → 永不写盘(实测 /tmp/cache 一直是 4.0K 空目录)。正解:明确写 proxy_cache_valid,或让上游给 Cache-Control: max-age。
  6. 响应里出现两条 Cache-Control 。现象:curl -D- 看到两条同名字段。根因:expires 7d 生成一条 max-age,add_header Cache-Control "public" 又追加一条。正解:合成一条 add_header Cache-Control "public, max-age=604800";,不要与 expires 混用。
  7. 上游重启那几秒用户全是 502 。现象:滚动发布期间错误率飙升。根因:proxy_cache_use_stale 没写或漏了 http_502;同时 proxy_connect_timeout 仍是默认 60s,冷 URL 要等到超时才失败。正解:use_stale error timeout updating http_500 http_502 http_503 http_504 + proxy_connect_timeout 2s(实测 1s 时冷 URL 3.02s 失败:3 台后端各 1s)。

8. 延伸阅读

文档页 解决什么问题
ngx_http_proxy_module proxy_cache 全组指令:proxy_cache_path 的 path 参数、use_temp_path、purger、proxy_cache_valid 的按码定制
ngx_http_upstream_module 本章用作上游的 upstream/zone/resolve,以及 $upstream_cache_status 的定义
ngx_http_slice_module slice 分片缓存的官方示例与 $slice_range 用法
内建变量索引 $upstream_cache_status、$request_uri、$cookie_* 的准确含义
nginx CHANGES 版本行为变化(background_update 1.11.10、slice 1.9.8、Vary 处理 1.7.7)的唯一权威出处

章节依赖 :本篇承接第 5 篇的反向代理与第 7 篇的 upstream/zone/摘流------use_stale 正是第 7 篇故障摘除之后「用户看不到报错」的兜底;第 9 篇用本篇写进日志的 ucs= 算命中率、定位 EXPIRED 突增,第 12 篇的压测与磁盘阈值告警直接建立在本篇 max_size/inactive 之上,第 15 篇用本篇的三类事故模式(串号/放大/雪崩)做复盘。


系列导航:第 1 篇进程模型 → 第 2 篇安装升级 → 第 3 篇配置语法 → 第 4 篇静态站与 location → 第 5 篇反向代理 → 第 6 篇 rewrite 与 server_name → 第 7 篇负载均衡进阶 → 第 8 篇(本篇)缓存体系 → 第 9 篇日志排障 → 第 10 篇 HTTPS 与安全 → 第 11 篇 Lua 与 OpenResty → 第 12 篇性能调优 → 第 13 篇高可用架构与网关 → 第 14 篇可观测性与工程化 → 第 15 篇故障案例库

相关推荐
时间海8711 小时前
前端表单如何防止重复提交
后端
稀土蚯蚓2 小时前
OLAP 分析引擎:StarRocks、Doris、ES、ClickHouse,存算分离、列式存储 Parquet
后端
旋律4142 小时前
序列化与反序列化
后端
TSuperman3 小时前
一次由高危漏洞引发的 Nginx 1.30.7 跨发行版安全升级实战
后端
静水深码3 小时前
文生图提示词的工程师写法:把玄学话术拆成结构化模板
人工智能·后端·代码规范
码云社区5 小时前
Spring Boot智慧物业系统源码:合同到期提醒、续签资料与资产协作
java·spring boot·后端·物业管理·物业系统·智慧物业
旋律4145 小时前
数据倾斜
后端
泡海椒6 小时前
jquick-pdf 热力图实战:Object 数组三元素的数据契约与模板还原
后端
行百里er6 小时前
【Spring Insight 技术分享】如何给 AI 接口调用做滑动窗口限流
spring boot·后端·spring cloud