nginx 无 proxy_cache_lock_age 指令，真实有效的是 proxy_cache_lock_timeout（控制等待锁超时）和 proxy_cache_use_stale updating（启用旧缓存响应），配合 proxy_cache_key 稳定化与 proxy_cache_background_update 实现高效缓存更新。

Nginx 没有 proxy_cache_lock_age 这个指令。截至 2026 年 5 月，该参数不存在于官方 ngx_http_proxy_module 中，也不在任何稳定版 Nginx 的文档或源码中。

你实际想调优的，是控制「多个请求同时发现缓存失效时，如何协调回源行为」的问题。真正起作用、必须配置且常被混淆的，是以下两个真实指令：

⚠️ 注意：proxy_cache_lock_age 是误传或混淆名称，切勿在配置中使用，Nginx 会报错或静默忽略。

---

proxy_cache_lock_timeout：控制“等多久才放弃锁”

这是你要关注的核心参数。它定义：
当多个请求同时对同一 key 缓存 MISS，且 proxy_cache_lock on 已启用时，后续请求愿意等待首个回源完成的最大时长。

• 超时前：等待首个响应写入缓存，成功则直接 HIT
• 超时后：放弃等待，各自发起回源 → 可能引发并发击穿

合理取值逻辑：

• 基于后端 P95 响应时间（从 $upstream_response_time 日志统计）
• 推荐设为 P95 的 1.2–1.5 倍，常见范围是 3–8 秒
  • 后端 P95 = 2.4s → 设 proxy_cache_lock_timeout 3s
  • 后端 P95 = 5.2s → 设 proxy_cache_lock_timeout 7s

---

proxy_cache_use_stale updating：让等待不“空等”

光调 timeout 不够。更关键的是：让等待中的请求不必干等，而是先返回旧缓存。

启用后，即使缓存已过期、首个请求正在后台回源，Nginx 仍可立即用旧内容响应用户。

CPA Update - Secure CLI Proxy API Maintenance

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

下载

proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;

✅ 效果：

• 用户无感知延迟，P99 响应时间大幅下降
• 锁竞争压力显著降低（多数请求根本不进等待队列）
• 配合 proxy_cache_background_update on，实现“前台秒回 + 后台静默刷新”

---

proxy_cache_key：确保锁能真正复用

锁只在 cache key 完全一致时生效。key 设得过细（比如含随机参数、变动 header），会导致本该共用一把锁的请求各自排队。

常见问题写法（❌）：

proxy_cache_key "$scheme$host$request_uri"; # 若 $request_uri 含 ?t=1623456789，每次都不一样

推荐写法（✅）：

# 忽略时间戳、utm 等扰动参数
proxy_cache_key "$host:/api/order/status";

# 或标准化 query（保留必要参数）
proxy_cache_key "$scheme$host$uri$is_args$args";
proxy_ignore_args "ts" "utm_source" "random_id";

---

协同生效的最小可靠配置片段

proxy_cache_lock on;
proxy_cache_lock_timeout 5s;

proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
proxy_cache_background_update on;

proxy_cache_key "$host$uri"; # 稳定、去噪
proxy_ignore_headers Set-Cookie; # 防止因 cookie 导致缓存失效

这套组合能在大规模缓存更新时：
✔️ 抑制 90%+ 的并发回源
✔️ 保障用户始终有响应（新或旧）
✔️ 避免 worker 连接长时间阻塞
✔️ 后台安静刷新，不影响主线程

不复杂但容易忽略