Nginx默认不缓存POST请求，需显式配置proxy_cache_methods、proxy_cache及含$request_body的proxy_cache_key，并按幂等性分级设置TTL与缓存策略，配合bypass和no_cache机制保障安全与可控。
默认情况下，Nginx 和大多数边缘节点（如阿里云 ESA）**不缓存 POST 请求**，因为 POST 语义上常代表“有副作用的操作”，比如提交表单、创建资源等。但现实中，很多 POST 是幂等的查询类请求（例如 GraphQL 查询、搜索 API、带 JSON body 的条件筛选），这类请求完全适合缓存——关键在于显式启用并精准控制。
明确启用 POST 缓存的必要配置
仅靠 proxy_cache_methods GET HEAD POST; 不够，必须同步满足以下三点：
-
开启缓存区：在 location 或 server 块中声明
proxy_cache my_cache;（对应 http 块中已定义的proxy_cache_path） -
允许 POST 方法：设置
proxy_cache_methods GET HEAD POST;（PUT/DELETE 极少用，暂不建议） -
设计唯一缓存键：必须包含请求体内容，否则所有 POST 都会命中同一缓存项。推荐写法：
proxy_cache_key "$scheme$request_method$host$request_uri$request_body";
⚠️ 注意：$request_body在 Nginx 中需配合proxy_buffering on;和足够大的client_max_body_size才能稳定获取；若 body 过大或含二进制内容，可改用哈希：proxy_cache_key "$scheme$request_method$host$request_uri$arg_q$arg_f";（提取关键查询参数）
按业务语义分层设定缓存策略
不能对所有 POST “一刀切”缓存。应结合响应含义分级处理：
WebChat Voice Proxy
下载
⚠️ 已弃用 — 该技能已拆分为两个独立技能，以提升模块化程度：**webchat-https-proxy**（HTTPS/WSS 反向代理）和 **webchat-voi...**
-
幂等查询类 POST（如搜索、过滤、聚合）：
设置短 TTL（如proxy_cache_valid 200 302 5s;），搭配proxy_cache_lock on;防穿透，再启用proxy_cache_use_stale updating;，确保高并发下旧缓存仍可服务 -
配置/字典类只读 POST（如根据 ID 批量查地区码）：
可设长 TTL（proxy_cache_valid 200 10m;），并加proxy_ignore_headers Cache-Control;强制覆盖后端返回的 no-cache -
真正有副作用的 POST（如下单、发消息）：
用proxy_no_cache $request_method;或更细粒度地匹配路径（proxy_no_cache $uri ~ ^/api/v1/order/submit$;）彻底禁用缓存
安全绕过与强制刷新机制
即使启用了 POST 缓存，也要保留人工干预能力：
- 用
proxy_cache_bypass $http_x_refresh $arg_refresh;实现“带头或带参即绕过”——调试时加X-Refresh: 1即可直连后端取最新结果 - 用
proxy_no_cache $http_cache_control;尊重客户端主动发起的 no-cache 请求（如浏览器开发者工具勾选 Disable cache 时发出的请求） - 避免用 IP 或 Cookie 做 bypass 条件，易引发缓存污染和一致性问题
验证是否生效的关键检查点
上线后务必确认三点：
- 响应头中出现
X-Proxy-Cache: HIT或MISS（需在 Nginx 中添加add_header X-Proxy-Cache $upstream_cache_status;） - 相同 POST body 发起两次请求，第二次响应时间显著下降（如从 300ms → 5ms），且无后端日志新增
- 修改 body 内容（如改搜索关键词），命中不同缓存项，响应内容随之变化
