proxy_cache_bypass能绕过缓存但不破坏原有策略，因其仅跳过单次请求的缓存查找与更新，不影响其他请求的缓存生命周期和存储内容。
proxy_cache_bypass 为什么能绕过缓存但不破坏原有缓存策略
proxy_cache_bypass 的作用不是清空缓存，而是让当前请求“跳过缓存查找阶段”，直接打到后端。它和 proxy_cache_valid、proxy_cache_key 是解耦的——只要命中了 bypass 条件，Nginx 就不会查磁盘/共享内存里的缓存条目，也不会更新缓存；但其他没 bypass 的请求照常读写缓存。
关键点在于：它只影响单次请求的缓存路径选择，不影响缓存生命周期或存储内容。所以你可以在生产环境安全地用它做预览，而不会导致全站缓存失效或雪崩。
- 必须配合
proxy_cache指令启用缓存区域，否则 bypass 无意义 - bypass 判定发生在请求头解析之后、缓存 key 计算之前，因此可以依赖任意已解析的 header（如
X-Preview） - 值为非空字符串（如
"1"、"true"、"abc"）即触发 bypass；值为"0"或空字符串则不触发
如何用 X-Preview Header 触发实时预览而不污染线上流量
最稳妥的做法是约定一个低概率误触的 header 名，比如 X-Preview，并限制它的生效范围。不要用 Cache-Control: no-cache 这类通用 header，因为浏览器、CDN、中间代理都可能识别并透传，导致非预期 bypass。
示例配置片段：
location / {
proxy_cache my_cache;
proxy_cache_bypass $http_x_preview;
proxy_pass http://backend;
}
这样只要客户端带上 X-Preview: 1，该请求就直通后端；其余请求完全不受影响。
WebChat Voice Proxy
下载
⚠️ 已弃用 — 该技能已拆分为两个独立技能，以提升模块化程度：**webchat-https-proxy**（HTTPS/WSS 反向代理）和 **webchat-voi...**
- 确保后端服务不记录或不响应
X-Preview，避免被日志系统误判为异常流量 - 如果前端是 SPA，可在预览链接中动态注入 header（需 fetch API 配合
mode: 'cors'+ 后端允许该 header） - 测试时用
curl -H "X-Preview: 1" https://example.com/path，观察响应头是否含X-Cache: MISS或X-Cache: BYPASS（取决于你自定义的日志变量）
为什么不能只靠 proxy_cache_bypass 实现完整预览流程
proxy_cache_bypass 只解决“请求不走缓存”，但真实预览往往还需要后端渲染特定版本（如 draft 数据、未发布页面），这需要额外协作机制。
常见漏掉的环节：
- 后端没识别
X-Preview，导致 bypass 后返回的仍是线上数据——必须在应用层也读取该 header 并切换数据源 - 预览页带 cookie 或用户身份，而缓存 key 没包含
$cookie_*，导致不同用户看到彼此的 bypass 结果（缓存污染） - 静态资源（JS/CSS）仍走 CDN 缓存，造成 HTML 是预览版但 JS 是旧版，出现功能错位
- 没有设置
proxy_cache_lock on，高并发预览请求可能引发后端重复渲染（尤其模板渲染类服务）
生产环境上线前必须验证的三个细节
很多团队卡在灰度阶段，问题往往出在看似无关的配置组合上。
-
proxy_cache_key必须显式排除$http_x_preview，否则不同 preview 值会生成不同缓存 key，浪费空间且掩盖 bypass 行为 - 如果用了
proxy_cache_use_stale，要确认updating状态下 bypass 是否仍有效（Nginx 1.11.10+ 才保证 bypass 优先级高于 stale） - 某些云 WAF（如 Cloudflare、阿里云WAF）会默认 strip 自定义 header，需在 WAF 控制台白名单放行
X-Preview，否则 header 根本到不了 Nginx
最易被忽略的是 header 大小写——Nginx 内部统一转为小写存储（$http_x_preview），但客户端发 X-preview 或 x-preview 也能匹配；不过部分 WAF 或 LB 严格区分大小写，建议始终用 PascalCase 发送。
