默认情况下Nginx proxy_cache不缓存POST请求，需同时满足缓存机制（正确配置proxy_cache_path、proxy_cache_methods、proxy_cache_valid等）、语义合理性（幂等只读响应、无Set-Cookie）和响应可控性（定制cache_key、忽略禁用头）三方面要求。
默认情况下，Nginx 的 proxy_cache 只缓存 GET 和 HEAD 请求，POST 不在默认列表中。要安全、有效地缓存 POST 响应，不能只加一句 proxy_cache_methods GET HEAD POST 就完事——必须同步满足缓存机制、语义合理性和响应可控性三个层面的要求。
必须启用并正确配置 proxy_cache_path
缓存功能的基础是磁盘与内存资源的预分配。该指令只能出现在 http 块顶层，否则 Nginx 启动会报错：
- 提前创建缓存目录并赋权：例如
sudo mkdir -p /var/cache/nginx/proxy && sudo chown nginx:nginx /var/cache/nginx/proxy - 定义 keys_zone（内存索引区）和 max_size（磁盘上限），例如：
proxy_cache_path /var/cache/nginx/proxy levels=1:2 keys_zone=my_cache:50m inactive=1d max_size=2g use_temp_path=off; -
use_temp_path=off推荐开启，避免写入临时路径再移动，减少 IO 延迟
显式声明可缓存方法并覆盖状态码规则
仅写 POST 不够，Nginx 要求 proxy_cache_methods 至少包含两个标准方法（如 GET 和 POST），且需与缓存区域绑定：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
- 在启用缓存的
location块内配置：proxy_cache my_cache;<br>proxy_cache_methods GET HEAD POST;
-
proxy_cache_valid必须明确列出 POST 可能返回的状态码，例如：proxy_cache_valid 200 201 400 5m;（不要依赖any，它优先级最低） - 若后端响应含
Cache-Control: no-cache或max-age=0，需强制忽略：proxy_ignore_headers Cache-Control Expires;
设计区分度高的缓存 key，避免污染
默认 key（如 $scheme$proxy_host$request_uri）对所有 POST 请求都一样，会导致不同请求体共用同一缓存项——这是最常见缓存错误。
- 不能直接用
$request_body（Nginx 默认不读取 body，key 计算时不可用） - 推荐方案：让前端将关键参数拼入 query string（改用 GET）；或由后端生成签名头（如
X-Request-Sign），再在 key 中引用：proxy_cache_key "$scheme$request_method$host$request_uri$is_args$args$http_x_request_sign"; - 确保 key 中包含请求方法（
$request_method），否则 GET 和 POST 可能命中同一缓存
确认后端响应具备缓存友好性
即使 Nginx 配置全对，若后端返回的内容本身不适合缓存，结果仍是无效缓存：
- 响应必须是幂等、只读的（如搜索接口、报表导出），不能含用户私有数据或时效敏感内容
- 响应头建议带
Cache-Control: public, max-age=300，且不含Set-Cookie（如有，需加proxy_ignore_headers Set-Cookie） - 通过
add_header X-Cache-Status $upstream_cache_status;验证是否真实命中（HIT/MISS/BYPASS）
