Nginx本地缓存API

一、前言为什么 API 也需要 Nginx 本地缓存你是否面临这些 API 性能瓶颈❌ 商品详情页接口 QPS 高达 10w后端扛不住❌ 用户配置接口低频变更被频繁调用❌ 后端服务偶发超时导致用户体验卡顿❌ 活动接口在大促时直接被打垮Nginx 本地缓存proxy_cache是官方提供的服务端缓存机制专为 API 设计✅将 JSON 响应缓存到本地磁盘✅相同请求直接返回缓存绕过后端✅实现“缓存托底”——后端挂了也能返回旧数据本文将手把手教你为 API 接口配置 Nginx 本地缓存并提供生产级最佳实践。二、核心原理proxy_cache 如何缓存 API关键点缓存存储在本地磁盘可配置内存默认缓存键$scheme$proxy_host$request_uri支持按状态码200/404控制缓存策略三、基础配置5 步开启 API 缓存步骤 1定义缓存区域http 块http { # 定义 API 缓存区域 proxy_cache_path /var/cache/nginx/api levels1:2 # 目录层级防单目录文件过多 keys_zoneapi_cache:100m # 共享内存区100MB ≈ 80万 key inactive10m # 10分钟未访问则删除 max_size5g # 最大缓存 5GB use_temp_pathoff; # 关键避免临时文件拷贝 # 创建目录 # mkdir -p /var/cache/nginx/api chown nginx:nginx /var/cache/nginx/api }步骤 2在 API 路径启用缓存server { listen 80; server_name api.example.com; # 商品详情接口高频读、低频写 location /api/product/ { proxy_cache api_cache; proxy_cache_key $host|$request_uri; # 自定义 key # 仅缓存 200 响应有效期 5 分钟 proxy_cache_valid 200 5m; # 忽略后端 Cache-Control 头强制由 Nginx 控制 proxy_ignore_headers Cache-Control Expires Set-Cookie; # 透传真实 IP proxy_set_header X-Real-IP $remote_addr; proxy_pass http://product_backend; } # 用户配置接口几乎不变 location /api/user/config/ { proxy_cache api_cache; proxy_cache_valid 200 1h; # 缓存 1 小时 proxy_pass http://user_backend; } }步骤 3定义上游服务upstream product_backend { server 10.0.0.10:8080; server 10.0.0.11:8080; } upstream user_backend { server 10.0.0.20:8080; }四、高级配置精准控制 API 缓存行为4.1 缓存状态透传用于监控# 添加缓存状态头 add_header X-Cache-Status $upstream_cache_status always; # 可能的值 # - MISS未命中 # - HIT命中 # - EXPIRED过期正在后台更新 # - BYPASS跳过缓存如 POST 请求4.2 跳过缓存调试或写操作# POST/PUT/DELETE 不缓存 if ($request_method ~* ^(POST|PUT|DELETE)$) { set $nocache 1; } # 请求带 ?nocache1 时不走缓存 if ($arg_nocache 1) { set $nocache 1; } proxy_cache_bypass $nocache; proxy_no_cache $nocache;4.3 按用户隔离缓存个性化 API# 为登录用户缓存个性化内容 proxy_cache_key $host|$request_uri|$cookie_user_id; # 或从 Token 中提取用户 ID需 OpenResty # proxy_cache_key $host|$request_uri|$jwt_claim_user_id;五、生产级最佳实践API 专属优化5.1 缓存托底后端宕机时返回旧数据location /api/campaign/ { proxy_cache api_cache; proxy_cache_valid 200 30s; # 关键后端错误时使用过期缓存 proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504; # 后台更新缓存避免请求堆积 proxy_cache_background_update on; proxy_pass http://campaign_backend; }✅效果后端宕机 → 用户仍能看到最近一次活动数据大促期间服务 SLA 从 95% 提升至99.95%5.2 性能优化建议项目推荐值说明缓存目录SSD 磁盘避免 HDD I/O 瓶颈inactive≥ 业务更新周期商品详情设 5-10 分钟max_size≤ 磁盘 80%防止占满磁盘keys_zone100MB 起每 1MB ≈ 8000 个 key5.3 清理缓存PurgingNginx 开源版不支持 PURGE可通过脚本清理# 根据 URL 计算缓存 key 的哈希需与 proxy_cache_key 一致 KEYapi.example.com|/api/product/123 HASH$(echo -n $KEY | openssl md5 | cut -d -f2) # 删除缓存文件 LEVEL1${HASH: -1} LEVEL2${HASH: -3:2} rm -f /var/cache/nginx/api/$LEVEL1/$LEVEL2/$HASH # 重载 Nginx非必须但推荐 nginx -s reload企业方案使用 Nginx Plus 的proxy_cache_purge指令。六、验证与监控6.1 检查缓存是否生效curl -I http://api.example.com/api/product/123 # 查看响应头 # X-Cache-Status: HIT6.2 监控缓存指标# 查看缓存目录大小 du -sh /var/cache/nginx/api # 日志记录缓存状态 log_format api_cache $remote_addr - $upstream_cache_status [$time_local] $request $status $body_bytes_sent; access_log /var/log/nginx/api_cache.log api_cache;七、常见问题排查问题原因解决缓存未生效后端返回Cache-Control: no-cache添加proxy_ignore_headers Cache-Control;缓存穿透大量唯一 ID如 /api/user/随机字符串规范 API 设计或返回 404磁盘写满max_size未设置设置合理的max_size中文乱码编码不一致确保后端返回 UTF-8八、结语感谢您的阅读如果你有任何疑问或想要分享的经验请在评论区留言交流