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 | |
- 浏览器缓存:
Cache-Control/ETag,只对单个用户有效; - CDN:在离用户更近、规模更大的节点缓存,通常按 URL 全局共享;
- 反向代理缓存:在源站前一跳,缓存粒度可控、能结合业务做 key 和失效;
- 应用缓存:进程内或 Redis,处理更细粒度、更个性化的数据。
本节聚焦 Nginx 这一层。它适合缓存全局共享、更新不频繁、能容忍秒级到分钟级延迟的响应。
三、定义缓存区:proxy_cache_path
1 | |
| 参数 | 作用 | | :— | :— | — | :— | | 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 | |
等价于 $scheme$proxy_host$uri$is_args$args。也就是说,协议 + 代理目标 + URI(含查询串) 决定一个缓存条目。
需要区分"不同用户看到不同内容"时,把身份信息加入 key:
1 | |
需要忽略某些参数时,先用 map 归一化,再放进 key,避免 ?t=123 这类随机参数把命中率打没。
五、什么时候不缓存
Nginx 默认会尊重上游的部分指令,不会缓存这些响应:
- 上游带
Set-Cookie(默认不缓存,除非显式忽略); - 上游
Cache-Control含private/no-store; - 请求方法不在
proxy_cache_methods(默认GET HEAD)。
相关开关:
1 | |
需要强制缓存某些"上游说不要缓存"的响应时,用 proxy_ignore_headers 忽略 Expires、Cache-Control、Set-Cookie、Vary 等——但这等于替业务做决定,慎用。
六、有效期与降级
1 | |
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 | |
常见取值:
| 值 | 含义 |
|---|---|
MISS | 未命中,已回源 |
HIT | 命中缓存 |
EXPIRED | 缓存过期,已回源 |
STALE | 命中过期缓存(配合 use_stale) |
UPDATING | 正在后台更新 |
BYPASS | 主动绕过缓存 |
REVALIDATED | 通过条件请求重新验证 |
排查命中率时,先看 X-Cache-Status 的分布,再决定是 key 太细、min_uses 太高,还是 inactive 太短。
九、完整配置模板
1 | |
十、常见问题
| 现象 | 原因 / 处理 |
|---|---|
| 缓存了登录后的私有数据 | 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 |
参考链接
- Nginx 官方文档:ngx_http_proxy_module ——
proxy_cache*系列指令; - Nginx 官方文档:ngx_http_upstream_module ——
$upstream_cache_status、$upstream_response_time; - Nginx 官方文档:ngx_http_map_module —— 归一化缓存键;
- 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 观测命中率。
