nginx proxy_pass 支撑复杂路由需分层设计：用 server 隔离业务域（如 api.example.com 独占 server），location 匹配路径语义（=、^~、~* 等类型精准控制），upstream 抽象后端，map 实现动态路由与灰度。
要让 Nginx 的 proxy_pass 支撑复杂多变的业务路由，关键不是堆功能，而是分层设计：用 server 隔离业务域、用 location 划分路径语义、用 upstream 抽象后端依赖、再靠 map 和条件逻辑应对动态规则。硬编码一条 proxy_pass 解决不了真实场景。
按业务域拆 server 块，避免配置污染
每个对外暴露的域名（如 api.example.com、admin.example.com）必须独占一个 server 块。这样 SSL 证书、访问控制、日志路径、限流策略才能各自独立生效。同一域名若需同时支持 HTTP 和 HTTPS，不要在一个 server 里用 if ($scheme = http) 判断跳转——性能差且易出错。直接写两个 server：一个 listen 80，一个 listen 443 ssl。
泛域名（如 *.example.com）可用 server_name _; 配合 map 指令做子域名白名单路由，例如只允许 app、dev、staging 开头的子域名接入，防止被恶意注册利用。
用 location 类型匹配不同流量特征
location 不是简单“匹配路径”，它的类型决定行为优先级和语义：
-
= /healthz：精确匹配，直接return 200，不走 upstream，响应最快 -
^~ /api/：前缀匹配，代理到 API 集群；建议加proxy_buffering off，避免流式接口（如 SSE、gRPC-Web）卡顿 -
~* \.(js|css|png|jpg|gif)$：正则匹配静态资源，配expires 1y和Cache-Control public -
^~ /ws/或~ ^/ws/：专用于 WebSocket，必须加三行：proxy_http_version 1.1;<br>proxy_set_header Upgrade $http_upgrade;<br>proxy_set_header Connection "upgrade";
proxy_pass 路径拼接必须精准控制
末尾斜杠决定是否截掉匹配前缀：
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
-
location /api/ { proxy_pass http://127.0.0.1:3000/; }→ 访问/api/users，后端收到/users -
location /api/ { proxy_pass http://127.0.0.1:3000; }→ 同样请求，后端收到/api/users -
location ~ ^/v[1-9]/这类正则匹配时，proxy_pass必须写完整目标地址（含协议、主机、端口、路径），不能省略 URI 部分，否则会报错
漏掉斜杠或写错路径，会导致后端 404、重定向错乱，甚至 WebSocket 握手失败。
统一 upstream + 动态 map，支撑灰度与多环境
把后端服务抽象成 upstream 块，命名体现版本和用途，例如：
upstream api_v2_cluster {<br> server 10.0.1.10:8080 weight=3;<br> server 10.0.1.11:8080;<br> health_check interval=3 fails=2 passes=2;<br>}
修改节点 IP、增删实例、调整权重，只需改一处。有状态服务启用会话保持：ip_hash（IPv6 下配合 hash $binary_remote_addr），或更可靠的 hash $cookie_session_id consistent（需前端种 cookie）。
环境差异（如测试环境调 mock 接口、生产走真实集群）用 map 定义变量：
map $host $backend_api {<br> default "api-v2.example.com";<br> ~^test\. example\.com "mock-api.example.com";<br> ~^staging\. example\.com "api-staging.example.com";<br>}
然后在 proxy_pass 中引用：proxy_pass https://$backend_api;，无需复制整段配置。
