使用 map 指令预定义语义化变量，再在 proxy_set_header 中引用，可避免多环境/路由/后端下的配置冗余，提升可读性与可维护性；支持按来源动态设置 x-forwarded-for、按 host/uri 自动映射 x-backend-id、按 user-agent 归类 x-device-type、条件化透传安全头。
直接用 proxy_set_header 写死值或固定变量，容易在多环境、多路由、多后端场景下重复堆砌配置。而配合 map 指令预先生成带业务语义的变量，再在 proxy_set_header 中引用，能显著减少冗余、提升可读性与可维护性。
按请求来源动态注入 X-Forwarded-For 策略
不同入口（公网/内网/运维通道）对 IP 追踪要求不同：公网需完整链路，内网可信任直连 IP，运维通道则需额外标记来源类型。
用 map 提前判断并生成策略标识：
map $http_x_forwarded_for $xff_strategy { "" "direct"; ~, "full"; default "direct"; }- 再在 location 中统一控制：
proxy_set_header X-Forwarded-For $xff_strategy;（实际需配合逻辑拼接，此处为示意语义）
更稳妥的做法是用map直接生成最终头值：map $http_x_forwarded_for $final_xff { "" "$remote_addr"; ~, "$http_x_forwarded_for, $remote_addr"; default "$remote_addr"; }
然后proxy_set_header X-Forwarded-For $final_xff;
根据 Host 或路径自动设置 X-Backend-ID
当 Nginx 同时代理多个业务子系统（如 api.example.com、admin.example.com、/legacy/），后端需要明确知道请求归属。手动在每个 location 里写 proxy_set_header X-Backend-ID "api" 易遗漏且难同步。
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
集中用 map 统一映射：
map $host $backend_id { api.example.com "api-v2"; admin.example.com "admin-fe"; default "default"; }-
map $uri $backend_id_legacy { ~^/legacy/ "legacy-v1"; ~^/v1/ "api-v1"; default $backend_id; }（嵌套 fallback） - 最终只需一行：
proxy_set_header X-Backend-ID $backend_id_legacy;
按 User-Agent 类型差异化透传 X-Device-Type
移动端、桌面端、爬虫、健康检查探针等，后端处理逻辑常有差异。与其在多个 location 中用 if 判断，不如用 map 提前归类：
map $http_user_agent $device_type { ~*android|ios "mobile"; ~*curl|httpie|checkmk "probe"; ~*msie|trident|edge "desktop"; default "unknown"; }- 后续所有需要该标识的位置，直接写：
proxy_set_header X-Device-Type $device_type; - 若需更细粒度（如区分 iOS 和 Android），可扩展正则捕获组，再用
$1引用
安全头的条件化透传（非动态值，而是条件启用）
比如只对 API 路径加 X-Content-Type-Options: nosniff，但又不想每个 location /api/ 都重复写 add_header ——这时 map 可驱动是否添加该头：
map $uri $add_nosniff { ~^/api/ 1; ~\.(js|css|html)$ 1; default 0; }- 配合
add_header X-Content-Type-Options nosniff always;不够灵活，应改用：proxy_set_header X-Content-Type-Options $add_nosniff;不行 —— 因为 header 值不能为 0/1
正确做法是：用map生成空字符串或固定值：map $uri $nosniff_value { ~^/api/ "nosniff"; ~\.(js|css|html)$ "nosniff"; default ""; }
再搭配：proxy_set_header X-Content-Type-Options $nosniff_value;（注意：Nginx 会忽略空值 header，等效于不发送）
