背景与问题

在分布式系统里做灰度发布，很多团队第一反应是“按机器比例放量”或者“网关随机分流 5% 流量”。这两种方式都能用，但一旦业务里有会话粘性、缓存命中率、用户体验一致性这类要求，问题就会迅速冒出来：

• 同一个用户今天命中旧版本，下一次请求又跑到新版本
• 缓存被打散，灰度期间命中率明显下降
• 服务实例扩缩容后，请求映射大面积抖动
• 注册中心实例列表变化频繁，导致灰度比例不稳定
• 某些“重点用户”无法稳定停留在灰度环境，问题复现困难

我自己做这类方案时，最早踩的坑就是：只关注“分多少流量”，没关注“同一个用户是否稳定落到同一组实例”。结果业务方反馈“体验忽新忽旧”，排查半天才发现，随机分流天然不适合这类场景。

这时候，把一致性哈希和服务发现结合起来，就是一个很实用的方案：

• 服务发现负责告诉你：当前有哪些实例、哪些是灰度实例、权重如何
• 一致性哈希负责保证：同一个 key（如 userId、tenantId、sessionId）尽量稳定命中相同目标
• 灰度策略负责控制：哪些用户、哪些租户、哪些比例进入新版本

这篇文章不讲“灰度发布的大而全理论”，而是聚焦一个很实际的问题：如何在分布式架构中，用一致性哈希 + 服务发现，做出“稳定、可控、可回滚”的灰度发布。

方案概览

先看整体思路。

1. 服务实例启动后注册到服务发现组件（如 Consul、Nacos、Eureka）
2. 实例元数据里标记版本、环境、灰度标签、权重等信息
3. 调用方拉取或订阅实例列表
4. 根据路由策略先过滤实例池：
   • 普通流量池
   • 灰度流量池
   • 指定租户专属池
5. 对用户 key 做一致性哈希，稳定选择实例
6. 当实例上下线时，仅少量 key 迁移，避免全量抖动

flowchart TD
    A[客户端请求 userId] --> B[路由层/SDK]
    B --> C{灰度规则匹配?}
    C -- 是 --> D[灰度实例池]
    C -- 否 --> E[正式实例池]
    D --> F[一致性哈希选择实例]
    E --> F
    F --> G[目标服务实例]
    G --> H[返回结果]

这个方案的关键价值不在于“高级”，而在于它解决了两个非常核心的工程问题：

• 稳定性：同一个用户尽量固定命中同一版本
• 可控性：灰度范围由规则控制，而不是随机碰运气

核心原理

1. 一致性哈希为什么适合灰度

普通取模路由的典型写法是：

hash(userId) % N

问题在于，只要实例数量从 N 变成 N+1，几乎所有用户的映射都可能改变。对于灰度来说，这种抖动非常致命。

一致性哈希的思路是把实例映射到一个哈希环上，请求 key 也映射到环上，然后顺时针找到最近的实例。这样在节点增减时，只有局部 key 会迁移。

flowchart LR
    A[Key:user-1001] --> B[Hash环]
    B --> C[Instance-A]
    B --> D[Instance-B]
    B --> E[Instance-C]
    B --> F[顺时针寻找最近节点]

优点

• 扩缩容时迁移范围小
• 同一个 key 路由稳定
• 容易做“按用户/租户维度”的灰度粘性

局限

• 如果节点少、哈希分布不均，会出现热点
• 需要虚拟节点来平衡负载
• 实例列表变化过于频繁时，仍然会造成抖动

2. 服务发现承担什么职责

服务发现不是只提供“有哪些机器”。在灰度发布中，它最好还能承载实例元数据：

• version=stable | canary
• weight=100
• zone=az1
• tenant_scope=vip
• status=healthy

例如：

{
  "id": "order-service-10.0.0.12:8080",
  "name": "order-service",
  "address": "10.0.0.12",
  "port": 8080,
  "metadata": {
    "version": "canary",
    "weight": "50",
    "zone": "az1",
    "healthy": "true"
  }
}

有了这些元数据，调用方才能先做规则过滤，再做一致性哈希。

3. 灰度路由的常见分层

灰度路由不要只靠一条规则，建议分成三层：

第一层：强规则优先

比如：

• 指定 userId
• 指定 tenantId
• 指定 header
• 指定来源渠道

这层用于“点杀式灰度”，最适合验证关键用户、内测账号、压测租户。

第二层：比例规则

比如：

• 对 hash(userId) % 100 < 5 的用户走灰度

这层用于放量，从 1% -> 5% -> 20% -> 50%。

第三层：一致性哈希选实例

在确定“这个用户属于灰度池还是正式池”后，再在该池内用一致性哈希选具体实例，保证路由稳定。

sequenceDiagram
    participant C as Client
    participant R as Router
    participant D as Service Discovery
    participant S as Service Instance

    C->>R: 请求(userId, headers)
    R->>D: 获取实例列表及元数据
    D-->>R: stable/canary 实例集合
    R->>R: 规则判断(强规则/比例规则)
    R->>R: 在目标实例池做一致性哈希
    R->>S: 转发到选中实例
    S-->>C: 响应

4. 为什么不能“全靠注册中心权重”

不少团队会问：注册中心不是支持权重吗？直接给灰度实例低权重不就好了？

问题是，权重只解决“概率分布”，不解决“用户稳定性”。

• 今天这个用户可能被分到 canary
• 下一次又可能被分到 stable
• 对有状态、缓存、本地会话、个性化推荐这类业务很不友好

所以更稳妥的做法是：

• 先按规则决定用户属于哪个版本池
• 再在池内做一致性哈希

这是本文最重要的设计边界之一。

方案对比与取舍分析

如果系统特点是下面这些，我会优先推荐本文方案：

• 需要用户级别稳定路由
• 服务实例会动态扩缩容
• 有缓存、本地状态或个性化逻辑
• 希望精准控制灰度对象而非纯概率分流

不太适合的场景也要说清楚：

• 服务完全无状态，随机分流已足够
• 实例数量很少且几乎不变
• 调用链极短，不值得引入额外复杂度
• 业务方对“同一用户跨版本跳转”不敏感

实战代码（可运行）

下面用 Python 写一个可运行的简化示例，模拟：

• 服务发现返回 stable / canary 实例
• 按用户灰度规则分组
• 在分组内做一致性哈希
• 支持虚拟节点

说明：这是一个可运行的演示程序，方便你理解核心机制。生产环境还需要加入缓存、订阅更新、熔断、健康检查等能力。

import hashlib
import bisect
from dataclasses import dataclass, field
from typing import List, Dict, Optional


def md5_int(value: str) -> int:
    return int(hashlib.md5(value.encode("utf-8")).hexdigest(), 16)


@dataclass(frozen=True)
class Instance:
    id: str
    host: str
    port: int
    metadata: Dict[str, str] = field(default_factory=dict)

    def addr(self) -> str:
        return f"{self.host}:{self.port}"


class ConsistentHashRing:
    def __init__(self, virtual_nodes: int = 100):
        self.virtual_nodes = virtual_nodes
        self.ring = []
        self.node_map = {}

    def add_node(self, node: Instance):
        for i in range(self.virtual_nodes):
            key = f"{node.id}#{i}"
            h = md5_int(key)
            self.ring.append(h)
            self.node_map[h] = node
        self.ring.sort()

    def add_nodes(self, nodes: List[Instance]):
        for node in nodes:
            self.add_node(node)

    def get_node(self, key: str) -> Optional[Instance]:
        if not self.ring:
            return None
        h = md5_int(key)
        idx = bisect.bisect_left(self.ring, h)
        if idx == len(self.ring):
            idx = 0
        return self.node_map[self.ring[idx]]


class MockServiceDiscovery:
    def __init__(self):
        self.instances = [
            Instance("stable-1", "10.0.0.1", 8080, {"version": "stable", "healthy": "true"}),
            Instance("stable-2", "10.0.0.2", 8080, {"version": "stable", "healthy": "true"}),
            Instance("stable-3", "10.0.0.3", 8080, {"version": "stable", "healthy": "true"}),
            Instance("canary-1", "10.0.1.1", 8080, {"version": "canary", "healthy": "true"}),
        ]

    def get_instances(self, service_name: str) -> List[Instance]:
        # 演示用，忽略 service_name
        return [x for x in self.instances if x.metadata.get("healthy") == "true"]


class GrayRouter:
    def __init__(self, discovery: MockServiceDiscovery):
        self.discovery = discovery

    def is_canary_user(self, user_id: str, headers: Dict[str, str]) -> bool:
        # 强规则：header 指定走灰度
        if headers.get("x-canary") == "1":
            return True

        # 比例规则：5% 用户灰度
        return md5_int(user_id) % 100 < 5

    def route(self, service_name: str, user_id: str, headers: Dict[str, str]) -> Optional[Instance]:
        instances = self.discovery.get_instances(service_name)

        stable_pool = [x for x in instances if x.metadata.get("version") == "stable"]
        canary_pool = [x for x in instances if x.metadata.get("version") == "canary"]

        target_pool = canary_pool if self.is_canary_user(user_id, headers) and canary_pool else stable_pool

        ring = ConsistentHashRing(virtual_nodes=128)
        ring.add_nodes(target_pool)

        # 这里要用稳定业务 key，而不是 requestId
        return ring.get_node(user_id)


def main():
    discovery = MockServiceDiscovery()
    router = GrayRouter(discovery)

    test_users = [
        ("10001", {}),
        ("10002", {}),
        ("10003", {"x-canary": "1"}),
        ("10004", {}),
        ("10005", {}),
    ]

    for user_id, headers in test_users:
        instance = router.route("order-service", user_id, headers)
        if instance:
            print(
                f"user_id={user_id}, headers={headers}, "
                f"route_to={instance.id}({instance.addr()}), version={instance.metadata.get('version')}"
            )
        else:
            print(f"user_id={user_id}, no instance available")


if __name__ == "__main__":
    main()

运行方式

python gray_router.py

你会看到的效果

• 同一个 user_id 多次运行，通常会稳定落到同一实例
• x-canary=1 的用户会优先进入灰度池
• 如果灰度池为空，会自动回退到 stable（生产上是否允许回退，要按业务决定）

代码中的关键设计点

1. 哈希 key 必须稳定

正确示例：

• userId
• tenantId
• deviceId
• sessionId（谨慎使用，生命周期要明确）

错误示例：

• requestId
• 当前时间戳
• 随机数
• 每次都会变化的 traceId

这个坑特别常见。你以为用了“一致性哈希”，结果因为 key 不稳定，最终效果跟随机分流没区别。

2. 先分池，再哈希

注意代码里是先通过 is_canary_user() 判断用户是否进入灰度池，再在目标池里做一致性哈希。

不要这样做：

• 先对所有实例做哈希
• 命中灰度实例就算灰度，命中正式实例就算正式

这种做法的结果是灰度比例失控，而且实例上下线时用户版本归属会变化。

3. 灰度池为空时的回退策略要明确

示例代码里做了自动回退，但生产环境要区分两类业务：

• 读请求：通常允许回退到 stable
• 写请求/流程型请求：如果用户已进入 canary，贸然回退可能导致状态不一致

所以最好把策略做成可配置：

• fallback_to_stable=true|false
• strict_version_affinity=true|false

常见坑与排查

这一部分是最值得认真看的，因为方案原理不难，真正难的是线上抖动和边界行为。

1. 注册中心实例列表频繁变化，导致路由抖动

现象

• 同一用户短时间内命中不同实例
• 缓存命中率下降
• 某些实例负载突然升高

根因

• 注册中心频繁推送实例变更
• 瞬时不健康、心跳抖动导致实例反复上下线
• 路由层每次都即时重建哈希环

排查方式

• 统计实例列表变更频率
• 查看健康检查日志是否过于敏感
• 对比一分钟内哈希环版本变化次数

解决建议

• 给健康检查加抖动容忍和失败阈值
• 路由层做实例列表本地缓存
• 使用“延迟摘除”而不是瞬时剔除
• 变更时批量合并，避免每次都重建

2. 虚拟节点太少，负载不均

现象

• 某台机器始终比别人更热
• 某些 userId 分布特别集中
• 明明是 3 台机器，流量却接近 6:2:2

根因

• 真实节点数量少
• 没有虚拟节点或虚拟节点数量过低

排查方式

• 输出环上节点分布
• 抽样 10 万个 key 看映射比例
• 观察实例 QPS 分布是否偏斜

解决建议

• 一般从 100~200 个虚拟节点起步
• 如果实例权重不同，可按权重生成不同数量的虚拟节点
• 做离线压测验证，而不是线上碰运气

3. 用错哈希维度，导致用户体验不一致

现象

• 同一用户不同请求落到不同版本
• 登录前后命中的实例变化很大

根因

• 登录前用 deviceId，登录后用 userId
• 某些请求没有用户标识，只能退化到 IP
• 不同语言 SDK 使用的 key 规则不一致

解决建议

• 明确统一的哈希主键优先级
• 网关层补齐标准化上下文
• 多语言环境统一哈希算法和编码方式

我见过一个非常隐蔽的坑：Java 用 UTF-8，某个 Python 脚本默认按另一个编码处理，结果同一 userId 哈希结果不同，跨语言调用链路完全对不上。

4. 灰度规则和实例标签不一致

现象

• 明明用户匹配了灰度规则，却没进灰度
• 某些实例被标记为 canary，但从未有流量

根因

• 元数据字段名不统一，如 gray / canary / version
• 标签大小写不一致
• 发布系统和路由系统使用不同约定

解决建议

• 统一元数据契约
• 启动时校验关键标签
• 在监控里输出“规则命中率”和“实例池命中率”

5. 灰度回滚后，旧缓存和新缓存相互污染

现象

• 灰度回滚后问题仍持续
• 某些用户数据异常，但代码已回退

根因

• 新旧版本共用缓存 key
• 数据结构或序列化格式不兼容

解决建议

• 缓存 key 带版本前缀
• 重要对象升级时保证前后兼容
• 回滚预案里包含缓存清理/隔离步骤

安全/性能最佳实践

安全方面

灰度发布虽然主要是架构问题，但也有安全边界。

1. 不要把灰度入口完全暴露给外部 header

如果只要加一个 x-canary: 1 就能进灰度环境，等于把内部版本暴露给外部用户，可能带来：

• 未发布功能泄露
• 新版本接口被恶意探测
• 调试能力被外部滥用

建议做法：

• 灰度 header 只对内网、测试账号或受签名保护的请求生效
• 结合网关鉴权，限制来源
• 对灰度命中行为做审计日志

2. 实例元数据不要承载敏感信息

注册中心元数据应只存路由所需信息，不要把这些内容塞进去：

• 数据库密码
• 内部访问令牌
• 完整配置明文

3. 灰度规则修改要可审计、可回滚

建议保留：

• 规则变更人
• 变更时间
• 变更前后 diff
• 回滚记录

这在故障时非常关键，不然你会陷入“到底是代码变了，还是规则变了”的混乱状态。

性能方面

1. 本地缓存实例列表与哈希环

不要每个请求都：

• 调注册中心
• 重建哈希环

正确方式：

• 订阅实例变化
• 在本地维护只读快照
• 快照变更时异步重建哈希环

2. 哈希环构建与请求转发解耦

建议使用“双缓冲”思路：

• 当前请求继续使用旧环
• 新实例列表到来后在后台构建新环
• 构建完成后原子切换

stateDiagram-v2
    [*] --> OldRingServing
    OldRingServing --> BuildingNewRing: 实例列表更新
    BuildingNewRing --> SwapRing: 新环构建完成
    SwapRing --> NewRingServing: 原子替换
    NewRingServing --> BuildingNewRing: 下次变更

3. 做容量估算时，不只看平均值

灰度放量时要关注：

• 单实例峰值 QPS
• 冷缓存恢复时间
• 下游依赖是否也支持灰度隔离
• 某些租户是否天然流量更高

一个简单估算思路：

灰度实例数 = (目标灰度流量QPS × 峰值冗余系数) / 单实例安全QPS

例如：

• 目标灰度 QPS = 800
• 冗余系数 = 1.5
• 单实例安全 QPS = 200

则至少需要：

(800 × 1.5) / 200 = 6 台

4. 观测指标要按“版本池”拆开

至少要有这些指标：

• stable / canary 请求量
• stable / canary 错误率
• 灰度命中用户数
• 路由回退次数
• 哈希环版本变更次数
• 实例池为空次数

如果只看服务整体成功率，很多灰度问题会被平均值掩盖掉。

一套更稳的落地建议

如果你准备在线上落地，我建议按下面节奏做，而不是一上来全量替换。

第一步：先做“规则分池”，不改实例选择

先验证：

• 用户分组规则是否正确
• 注册中心元数据是否可靠
• 命中率是否符合预期

第二步：池内引入一致性哈希

重点验证：

• 同一用户路由稳定性
• 扩缩容时迁移比例
• 缓存命中率变化

第三步：补齐观测和回滚能力

至少包括：

• 灰度命中日志
• 版本维度监控
• 一键关闭灰度
• 严格/宽松回退开关

第四步：再考虑跨可用区、权重和多集群

此时你才适合处理更复杂的问题：

• 同城多活下的版本亲和性
• zone 优先 + 一致性哈希
• 多集群注册中心视图不一致

边界条件与经验建议

这套方案很好用，但不是银弹。下面这些边界条件一定要提前想清楚。

1. 写链路是否允许跨版本

如果某个用户先在 canary 完成“下单”，随后请求又回退到 stable，业务是否能接受？如果不能，就必须开启严格版本亲和，宁可失败也不要回退。

2. 下游依赖是否同步灰度

你的服务灰度了，但下游服务没有按同样的用户 key 做稳定分流，最终链路上还是会出现跨版本穿透。特别是：

• 订单服务灰度了
• 库存服务没灰度
• 营销服务随机分流

最后问题会非常难查。

3. 用户量小于实例量时，一致性哈希收益有限

如果只有少量关键用户，且实例很多，那么再精细的哈希设计也可能分布不均。这时候可以考虑：

• 强规则绑定实例池
• 专门建立灰度集群
• 对特定用户做静态映射

总结

基于一致性哈希与服务发现做灰度发布，核心不是“让 5% 流量进新版本”这么简单，而是实现三个目标：

• 用户维度稳定：同一个 key 尽量固定到同一版本、同一实例池
• 扩缩容时低抖动：实例增减不引发大范围迁移
• 规则与实例解耦：先判定灰度归属，再在目标池内做一致性哈希

如果你只记住几个最关键的实践点，我建议是这几条：

1. 先分池，再哈希，不要把两者混成一层
2. 哈希 key 必须稳定，优先 userId / tenantId
3. 实例元数据要统一契约，版本标签别各写各的
4. 哈希环要本地缓存、异步更新、原子切换
5. 灰度回退策略要按业务链路区分，读写不要一刀切
6. 观测指标必须按 stable/canary 拆开

最后给一个很实际的建议：
如果你们现在还在用随机分流做灰度，不必急着“一步到位”。先把服务发现元数据标准化和灰度规则分池做好，再把一致性哈希引入池内路由，成功率会高很多，也更容易排障。

当你真正把这套机制跑稳后，会发现灰度发布不再只是“发版动作”，而是分布式系统里一项非常核心的流量治理能力。