代理缓存

约 670 字大约 2 分钟

布欧-Lewyon

2026-05-15

Nginx 的代理缓存将后端响应缓存到本地磁盘，后续相同请求直接从缓存返回，降低后端负载、加快响应速度。

启用基础配置

http {
    # 定义缓存路径和参数
    proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=mycache:10m
                     max_size=1g inactive=60m use_temp_path=off;

    server {
        location /api/ {
            proxy_pass http://backend:3000;
            proxy_cache mycache;             # 使用定义的缓存
            proxy_cache_valid 200 302 10m;   # 200/302 响应缓存 10 分钟
            proxy_cache_valid 404 1m;        # 404 仅缓存 1 分钟
            proxy_cache_valid any 1m;        # 其他状态缓存 1 分钟
        }
    }
}

缓存参数详解

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=mycache:10m
                 max_size=1g inactive=60m use_temp_path=off;

参数	说明
`levels=1:2`	缓存目录层级（`/var/cache/nginx/c/29/xxx`）
`keys_zone=mycache:10m`	缓存元数据内存空间（1MB 约管理 8000 个 key）
`max_size=1g`	最大磁盘空间
`inactive=60m`	60 分钟未被访问则删除
`use_temp_path=off`	直接在缓存目录写入，避免跨文件系统

缓存键

# 默认缓存键
# proxy_cache_key "$scheme$request_method$host$request_uri";

# 自定义缓存键（区分用户）
proxy_cache_key "$scheme$request_method$host$request_uri$is_args$args";

# 忽略某些参数
proxy_cache_key "$scheme$request_method$host$uri";

缓存状态

通过 $upstream_cache_status 变量查看缓存命中状态：

# 在日志中记录缓存状态
log_format cache_log '$remote_addr - $upstream_cache_status [$time_local] "$request"';
access_log /var/log/nginx/cache.log cache_log;

# 也可以在响应头中返回
add_header X-Cache-Status $upstream_cache_status;

状态	含义
`HIT`	缓存命中
`MISS`	缓存未命中
`EXPIRED`	缓存过期
`STALE`	缓存过期但允许使用过期内容
`UPDATING`	缓存正在更新
`BYPASS`	已配置 `proxy_cache_bypass`
`REVALIDATED`	缓存被 `If-Modified-Since` 验证仍有效

缓存绕过与刷新

# 绕过缓存（带 X-No-Cache 头的请求不缓存）
location /api/ {
    proxy_cache mycache;
    proxy_cache_bypass $http_x_no_cache;
    proxy_no_cache $http_x_no_cache;
}

# 手动刷新缓存（Nginx Plus 支持 PURGE 方法）
# 或通过删除缓存文件
sudo rm -rf /var/cache/nginx/*

缓存场景配置

http {
    proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=api_cache:100m
                     max_size=10g inactive=60m;

    server {
        listen 80;
        server_name api.example.com;

        location / {
            proxy_pass http://backend:3000;
            proxy_cache api_cache;

            # 根据状态码设定不同缓存时间
            proxy_cache_valid 200 302 5m;
            proxy_cache_valid 404 30s;

            # 缓存 GET 和 HEAD 请求，不缓存 POST
            proxy_cache_methods GET HEAD;

            # 忽略请求中的缓存控制头，强制缓存
            # 或保留客户端缓存控制
            proxy_ignore_headers Set-Cookie Cache-Control;

            # 缓存状态头
            add_header X-Cache-Status $upstream_cache_status;
        }

        # 无缓存的特殊路径
        location /auth/ {
            proxy_pass http://backend:3000;
            proxy_cache off;
        }
    }
}

小结

proxy_cache_path 在 http 块定义缓存，proxy_cache 在 location 块启用。
proxy_cache_valid 按状态码设置缓存时长。
通过 $upstream_cache_status 和响应头查看缓存命中率。
proxy_cache_bypass 和 proxy_no_cache 可条件性绕过缓存。
适用于 GET/HEAD 响应，API 数据和后端渲染页面效果显著。

上一节：请求头与超时下一节：WebSocket 代理