如何配置 proxy_pass 实现针对不同 API 版本的灰度反向代理转发-Nginx-PHP中文网

准确识别API版本是灰度转发前提，常用URL路径、请求头或查询参数；推荐用map指令映射版本到后端服务，支持正则与默认值；可结合X-Gray-Tag等请求头实现精细化分流；rewrite可清理路径并透传X-API-Version供后端识别。

如何配置 proxy_pass 实现针对不同 api 版本的灰度反向代理转发

识别请求中的 API 版本标识

灰度转发的前提是能准确识别当前请求属于哪个 API 版本。常见方式有三种：URL 路径（如 /v1/users、/v2/users）、请求头（如 X-API-Version: v2）、或查询参数（如 ?version=v2）。Nginx 本身不解析 JSON 或业务逻辑，所以必须依赖这些显式、可匹配的字段。

用 map 指令动态映射后端服务地址

推荐使用 map 指令将版本标识映射为上游服务地址，避免重复 if 判断。它在 server 块外定义，高效且支持正则与默认值：

map $uri $backend {
    ~^/v1/      http://api-v1-cluster;
    ~^/v2/      http://api-v2-canary;
    default     http://api-v1-cluster;
}
<p>upstream api-v1-cluster { server 10.0.1.10:8080; }
upstream api-v2-canary { server 10.0.1.20:8080 weight=5; }  # 可加 weight 控制灰度流量比例
</p>

这样，所有以 /v2/ 开头的请求自动走灰度集群，其余走稳定集群。注意：map 匹配的是原始 $uri（已解码），不包含 query string。

结合请求头实现更灵活的灰度策略

若需按用户身份、灰度标签等做精细化分流，可读取自定义请求头：

map $http_x_gray_tag $backend {
    "v2"        http://api-v2-canary;
    "beta"      http://api-beta-cluster;
    default     http://api-v1-cluster;
}

然后在 location 中使用：

Umbrel Proxy Manager

高效管理与交互 Umbrel 代理服务，支持 Docker 容器。自动发现运行服务，将内部 Docker IP 映射为可访问的外部地址。

下载

location /api/ {
    proxy_pass $backend;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

客户端只需带上 X-Gray-Tag: v2 即可命中灰度后端。该方式与路径解耦，适合 A/B 测试或内部人员白名单场景。

保留原始路径并透传版本信息

灰度服务可能仍需知道原始请求版本，尤其当后端未剥离前缀时。可用 rewrite 清理路径，并通过 header 透传：

location ~ ^/v2/(.*)$ {
    rewrite ^/v2/(.*)$ /$1 break;
    proxy_pass http://api-v2-canary;
    proxy_set_header X-API-Version "v2";
    proxy_set_header X-Original-Path $uri;
}

这样既把 /v2/users 转为 /users 发给后端，又让后端明确知道自己处理的是 v2 请求，便于日志追踪或兼容逻辑判断。