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