如何利用 map 指令动态控制 proxy_cache 的开启状态以应对不同业务线的加速需求-Nginx-PHP中文网

nginx 无法直接开关 proxy_cache，但可通过 proxy_cache_bypass 和 proxy_no_cache 控制缓存逻辑：用 map 指令基于 $host、$request_uri 或 $http_x_biz_line 等变量设置开关标志，在 location 中联动生效，实现按业务线精细化缓存控制。

如何利用 map 指令动态控制 proxy_cache 的开启状态以应对不同业务线的加速需求

Nginx 的 map 指令本身不能直接开关 proxy_cache，但可以通过控制 proxy_cache_bypass 和 proxy_no_cache 这两个指令的值，实现“逻辑上启用或禁用缓存”的效果。关键在于：让特定业务线的请求绕过缓存写入与读取，而其他请求正常走缓存流程。

用 `$host` 或 `$request_uri` 区分业务线

业务线通常对应独立子域名（如 api.example.com、admin.example.com）或路径前缀（如 /shop/、/cms/）。利用这些特征做映射最稳定、无歧义。

http {
    # 定义缓存区域（全局）
    proxy_cache_path /var/cache/nginx/business_cache levels=1:2 keys_zone=biz_cache:20m max_size=2g inactive=30m use_temp_path=off;

    # 根据 host 判断是否启用缓存（on = 缓存；off = 不缓存）
    map $host $cache_enabled {
        default "on";
        ~^test\.example\.com$ "off";   # 测试环境全 bypass
        ~^admin\.example\.com$ "off";    # 后台系统不缓存
        ~^dev-api\.example\.com$ "off";  # 开发 API 禁用
    }

    # 可选：按路径补充控制（例如 /healthz 始终不缓存）
    map $request_uri $cache_bypass_extra {
        ~^/healthz 1;
        ~^/metrics 1;
        default 0;
    }
}

在 location 中联动使用：

server {
    listen 80;
    location / {
        proxy_pass http://backend;

        proxy_cache biz_cache;
        proxy_cache_valid 200 302 5m;
        proxy_cache_valid 404 1m;

        # 关键：只有 $cache_enabled == "on" 且 $cache_bypass_extra == 0 时才真正缓存
        proxy_cache_bypass $cache_enabled $cache_bypass_extra;
        proxy_no_cache $cache_enabled $cache_bypass_extra;

        # 调试用头，确认策略是否生效
        add_header X-Cache-Enabled $cache_enabled;
        add_header X-Cache-Bypass $cache_bypass_extra;
        add_header X-Cache-Status $upstream_cache_status;
    }
}

✅ 注意：proxy_cache_bypass 和 proxy_no_cache 接收多个变量，只要其中任意一个为非空、非 0、非 "off"、非 "false" 的值，就触发 bypass 或 no_cache 行为。所以 "on" 和 "off" 配合时，建议统一用 "0"/"1" 或 "off"/"on"，避免语义混淆。

按请求头区分业务线（如 `X-Biz-Line`）

适合灰度发布或内部调用场景，前端或网关显式带上业务标识：

CPA Update - Secure CLI Proxy API Maintenance

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

下载

map $http_x_biz_line $cache_ttl {
    "" "60s";                # 未声明，默认短缓存
    "user" "10m";            # 用户中心业务
    "order" "2m";            # 订单类敏感数据，缓存更短
    "report" "1h";           # 报表类可长期缓存
    "test" "0s";             # 测试线完全不缓存（等价于 bypass）
}

# 在 location 中：
proxy_cache_valid 200 302 $cache_ttl;
proxy_cache_bypass $http_x_biz_line;
proxy_no_cache $http_x_biz_line;

⚠️ 注意：$http_x_biz_line 是客户端传来的头，需确保上游可信；若不可控，建议改用 $cookie_biz_id 或 $arg_biz（URL 参数）并配合白名单校验。

多条件组合判断（推荐用于复杂策略）

比如「仅当是生产环境 + 非管理路径 + 有合法 token」才启用缓存：

map $host:$request_uri:$http_authorization $final_cache_flag {
    ~*^(prod\.example\.com):(/(?!admin|health).+):(.{20,})  "1";
    default "0";
}

# 然后：
proxy_cache_bypass $final_cache_flag;
proxy_no_cache $final_cache_flag;

这种写法把判断逻辑收束到一个变量里，清晰且便于日志追踪。

不复杂但容易忽略