Nginx通过map指令结合upstream变量实现灰度路由，如根据$cookie_version选择backend_gray或backend_stable，再由proxy_pass统一转发；不推荐在location中直接匹配Header/Cookie。
Nginx 本身不直接支持“灰度发布”这一业务概念，但可以通过 location 匹配 + 请求特征（如 Header、Cookie、参数、IP）结合 upstream 和 proxy_pass 实现灵活的流量分流，从而达成灰度路由效果。关键在于：**用 location 精确识别灰度请求，再将其代理到指定的灰度 upstream**。
用 location 匹配灰度标识（Header / Cookie / 参数）
灰度通常依赖可被客户端携带、服务端可识别的标识。Nginx 的 location 本身不支持按 Header 或 Cookie 匹配，但可通过 map 指令预判，并配合 if 或直接在 proxy_pass 中引用变量实现路由决策。
更推荐的方式是：**不在 location 路径上做灰度判断，而是在通用 location 内，用 map + upstream 变量动态选择后端集群**。但若坚持用 location，可借助正则匹配带灰度标记的 URL 路径（如 /api/v2/gray/ 或 /gray/user/info）：
-
✅ 推荐（显式路径灰度）：
location ~ ^/gray/(.*)$ {<br> proxy_pass http://upstream_gray/$1;<br>}
把灰度请求统一导向upstream_gray，后端服务需适配该路径前缀。 -
⚠️ 不推荐（location 无法直接读 Cookie/Header）：
不要写类似location ~* "X-Release: gray" { ... }—— 这是非法语法，Nginx location 不解析请求头。
用 map + upstream 变量实现动态灰度路由（主流做法）
这是生产中最常用、最灵活的方式：先用 map 提取灰度依据（如 Cookie 中的 version=gray），生成一个 upstream 名称变量，再在 proxy_pass 中引用它。
示例配置片段：
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
upstream backend_stable { server 192.168.1.10:8080; }
upstream backend_gray { server 192.168.1.11:8080; }
<p>map $cookie_version $backend_upstream {
default backend_stable;
"gray" backend_gray;
"~*v2" backend_gray; # 支持正则匹配
}</p><p>server {
listen 80;
location / {
proxy_pass <a href="https://www.php.cn/link/23f6fd077f1e5af83a3fcbdc64dbceb2">https://www.php.cn/link/23f6fd077f1e5af83a3fcbdc64dbceb2</a>;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}这样，当用户请求携带 Cookie: version=gray，就会自动打到灰度集群；其余走稳定集群。无需修改 location 路径，对前端透明。
结合 IP 或 User-Agent 做小流量灰度
适合内部测试或定向验证。仍建议用 map 判断，而非复杂 if 嵌套：
- 按内网 IP 段灰度：
map $remote_addr $backend_upstream {<br> default backend_stable;<br> ~^10\.10\. backend_gray;<br>} - 按特定 User-Agent（如测试 App）：
map $http_user_agent $backend_upstream {<br> default backend_stable;<br> ~*TestApp/2\.5\.0 backend_gray;<br>}
注意：$http_* 变量名是将 Header 名转为小写、中划线换下划线（如 User-Agent → $http_user_agent）。
进阶：多级灰度与权重控制（需 stream 模块或 lua）
纯 Nginx 标准模块不支持基于百分比的随机灰度（如 5% 流量进灰度）。若需此能力，有两类方案：
-
轻量级：用
split_clients指令（属于 http_split_clients_module，默认启用），基于变量哈希分桶：split_clients "$request_id" $backend_upstream {<br> 5% "backend_gray";<br> * "backend_stable";<br>}
注意：需确保$request_id或其它变量具备足够离散性（推荐用$binary_remote_addr或$cookie_uid）。 -
高灵活性：集成
nginx-lua-module，在access_by_lua_block中编写 Lua 脚本，实现复杂规则（如登录用户 ID % 100 < 5 → 灰度）。
标准 Nginx 不支持在 location 内直接写条件 proxy_pass，所以所有“灰度逻辑”应前置到变量定义阶段（map / split_clients），再由 proxy_pass 统一消费。
