proxy_cache_valid 是 Nginx 控制反向代理缓存有效期的核心指令，仅设定不同状态码的本地缓存保留时间，不依赖后端响应头，需显式配置各状态码（如 200、404、5xx 等），且必须配合 proxy_cache_path、proxy_cache 和可缓存响应三者才能生效。

proxy_cache_valid 是 Nginx 控制反向代理缓存有效期（TTL）的核心指令，它不决定“是否缓存”，只决定“缓存多久”——针对不同 HTTP 状态码，由 Nginx 主动设定本地缓存的保留时间，完全不依赖后端响应头，因此更可控、更稳定。

---

状态码必须显式声明，不能靠默认

Nginx 默认仅对 200、301、302 响应做基础缓存尝试，且仍受后端响应头限制。若你没写 proxy_cache_valid 404 30s;，404 就不会被缓存；没写 proxy_cache_valid 301 7d;，301 可能按 any 或 fallback 规则处理，甚至不缓存。

CPA Update - Secure CLI Proxy API Maintenance

安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。

下载

• ✅ 正确做法：为关键状态码逐条配置

  proxy_cache_valid 200 206 304 1h;
  proxy_cache_valid 301 7d;
  proxy_cache_valid 302 2m;
  proxy_cache_valid 404 30s;
  proxy_cache_valid 500 502 503 504 10s;
  proxy_cache_valid any 5s;

• ⚠️ 注意顺序：any 是兜底，只匹配未被前面规则覆盖的状态码；同状态码后出现的规则会覆盖前面的。

---

缓存真正生效的三个必要条件

光写 proxy_cache_valid 没用，以下三项缺一不可：

• 在 http 块中定义缓存区：
  proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m max_size=1g;
• 在 location 或 server 块中启用该缓存区：
  proxy_cache my_cache;
• 上游响应本身要“可缓存”：
  • 默认拒绝含 Cache-Control: no-cache/private/no-store、Set-Cookie、Pragma: no-cache 的响应
  • 如需强制缓存，加：
    proxy_ignore_headers Cache-Control Set-Cookie Expires;

---

常见状态码的语义化时长建议

状态码	推荐时长	原因
200 206 304	1h ~ 1d	正常内容或协商成功，稳定性高
301	1d ~ 30d	永久重定向，语义承诺长期有效，适合 CDN 和浏览器长效复用
302	30s ~ 5m	临时跳转，设太长会掩盖上游变更，务必单独配置，勿与 301 合并
404	10s ~ 1m	防恶意探测，但过长会延迟新资源上线可见性
5xx 错误	5s ~ 30s	缓解雪崩，给后端留恢复窗口，不宜超过 1 分钟

---

验证缓存是否按预期工作

• 加响应头标识缓存状态：
  add_header X-Cache-Status $upstream_cache_status;
• 用 curl 多次请求观察变化：
  curl -I http://your-domain/path
  看 X-Cache-Status 是否从 MISS → HIT，响应时间是否明显下降
• 注意：304 不走 proxy_cache_valid，它由 proxy_cache_revalidate on; 控制缓存续期行为

---

和 CDN 缓存的关系要分清

proxy_cache_valid 只影响 Nginx 本机缓存，不影响 CDN。
要让 CDN 缓存指定时长，必须主动注入标准响应头：
add_header Cache-Control "public, max-age=3600";
否则 CDN 可能忽略你的 Nginx 缓存策略，按自身逻辑或后端头处理。

不复杂但容易忽略