Nginx 流量镜像与灰度发布：mirror 模块、影子流量与按比例分流

upstream production {
    server 10.0.0.11:8080;
    keepalive 64;
}

upstream shadow {
    server 10.0.1.11:8080;    # 新版本所在环境
    keepalive 32;
}

location /api/ {
    # 镜像到内部 location
    mirror /mirror_shadow;
    # 是否把请求体也复制过去（默认 on）
    mirror_request_body on;

    proxy_pass http://production;
}

location = /mirror_shadow {
    internal;                       # 必须，禁止外部直接访问
    proxy_pass http://shadow$request_uri;
    # 影子环境不应改动生产侧上下文
    proxy_set_header Host shadow.internal;
    proxy_set_header X-Shadow-Request "1";
    proxy_set_header X-Original-Client $remote_addr;
}

location /api/ {
    mirror /mirror_v2;
    mirror /mirror_v3;
    proxy_pass http://production;
}

# 大文件上传路径：关闭请求体镜像，避免内存膨胀
location /upload/ {
    mirror /mirror_shadow;
    mirror_request_body off;
    client_max_body_size 500m;
    proxy_pass http://production;
}

location = /mirror_shadow {
    internal;
    proxy_pass http://shadow$request_uri;
    # 让应用识别影子请求并切换到只读通道
    proxy_set_header X-Shadow-Mode "readonly";
    proxy_set_header X-Shadow-Request-Id $request_id;
}

# 应用侧根据影子标记切换到影子数据源
# 伪代码语义：
#   if os.getenv("SHADOW_MODE") == "readonly":
#       db = shadow_readonly_replica
#       disable_outbound_sms()
#       disable_payment_gateway()

# 只镜像安全方法，避免写操作被复制
map $request_method $mirror_uri {
    default      "";
    "GET"        "/mirror_shadow";
    "HEAD"       "/mirror_shadow";
}

server {
    location /api/ {
        mirror $mirror_uri;         # 空字符串表示不镜像
        proxy_pass http://production;
    }
}

# 按用户标识稳定分流：同一用户始终落到同一版本
split_clients "${remote_addr}${http_user_agent}" $variant {
    5%      "canary";
    *       "stable";
}

upstream canary_backend {
    server 10.0.1.11:8080;
}
upstream stable_backend {
    server 10.0.0.11:8080;
}

server {
    location /api/ {
        proxy_pass http://$variant_backend;
    }
}

map $variant $variant_backend {
    "canary"  "canary_backend";
    default   "stable_backend";
}

# 优先用登录态里的用户 ID，未登录时回退到 IP
map $cookie_user_id $shard_key {
    default   $remote_addr;
    "~."      $cookie_user_id;
}

# 用哈希值的前若干位做分桶，比例调整时老用户保持稳定
map $cookie_user_id $bucket {
    default   "0";
    "~^(?<h>.)"  "$h";        # 简化示例：按首字符分桶
}
map $bucket $variant {
    default  "stable";
    "0"      "canary";
    "1"      "canary";
}

map $cookie_canary $canary_backend {
    default   "stable_backend";
    "1"       "canary_backend";
}

map $http_x_canary $canary_by_header {
    default   $canary_backend;
    "on"      "canary_backend";
}

server {
    location /api/ {
        # 头部优先级高于 Cookie，方便压测与人工放量
        proxy_pass http://$canary_by_header;
        add_header X-Served-By $canary_by_header always;
    }
}

# 用响应头标记版本，便于从日志统计灰度效果
log_format canary '$remote_addr "$request" $status '
                  'ver=$canary_by_header '
                  'upstream=$upstream_addr rt=$request_time';

access_log /var/log/nginx/access.log canary;

# 回滚：把灰度比例调回 0，只需改 map 后重载，无需改业务配置
sed -i 's/^    5%      "canary";/    0%      "canary";/' /etc/nginx/conf.d/canary.conf
nginx -t && nginx -s reload

# 回滚后确认灰度流量已归零
awk '$0 ~ /ver=canary/ {c++} END {print "canary requests:", c+0}' /var/log/nginx/access.log

# 影子服务把响应摘要写入对比日志，离线比对
# 日志格式示例（JSON 行）：
#   {"rid":"a1b2","path":"/api/order/7788","prod_hash":"9f3c","shadow_hash":"9f3c","ms":12}

# 统计影子与生产结果不一致的比例
python3 - <<'PY'
import json
diff = total = 0
for line in open('/var/log/shadow/compare.log'):
    r = json.loads(line)
    total += 1
    if r['prod_hash'] != r['shadow_hash']:
        diff += 1
print(f"total={total} diff={diff} rate={diff/max(total,1):.4%}")
PY

# 限制镜像带来的额外压力：只镜像部分流量
split_clients "${remote_addr}${uri}" $mirror_sample {
    10%     "/mirror_shadow";
    *       "";
}
server {
    location /api/ {
        mirror $mirror_sample;      # 只镜像 10% 的流量
        proxy_pass http://production;
    }
}

location = /mirror_shadow {
    internal;
    proxy_pass http://shadow$request_uri;
    # 透传请求 ID，保证日志可关联
    proxy_set_header X-Request-Id $request_id;
    proxy_set_header X-Mirror-Of    $host;
}