背景与问题

在分布式系统里做灰度发布，真正难的往往不是“把新版本机器拉起来”，而是怎样把一部分请求稳定地路由到新版本，并且在服务实例频繁上下线、扩缩容、故障摘除时，仍然尽量保持用户体验一致。

很多团队一开始会用最直接的方法：

• 按机器比例分流：10% 流量打到 v2
• 按随机数分流：rand() < 0.1 进灰度
• 按网关权重分流：老版本 90，新版本 10

这些方法并不是不能用，但在中大型系统里，常见问题会很快暴露出来：

1. 用户请求不稳定

   • 同一个用户第一次进了 v2，第二次又回到 v1
   • 特别是涉及缓存、推荐、购物车、会话黏性时，体验会很割裂

2. 扩缩容影响灰度结果

   • 新增或移除实例后，大量请求重新分配
   • 导致命中率、缓存预热、会话一致性一起抖动

3. 服务注册信息变化快

   • 服务发现层一旦更新，路由层要立即感知
   • 如果处理不好，会出现“路由表撕裂”或“部分节点视图不一致”

4. 灰度策略和服务治理耦合混乱

   • 灰度规则散落在网关、SDK、服务端多个地方
   • 排查问题时，很难知道究竟是哪一层把请求导错了

我自己做过一次线上灰度，当时最痛的点就是：看起来只是 5% 灰度，实际上同一批用户在不同请求间不断漂移。业务方反馈“为什么我刚看到新页面，刷新一下又没了”。最后追下来，问题不是版本包，而是路由策略太“随机”。

所以，这篇文章的核心目标很明确：用一致性哈希保证用户路由稳定，用服务发现保证实例列表实时可用，把两者组合成一个可落地的灰度发布方案。

方案全景：为什么是一致性哈希 + 服务发现

先给出一个简化的设计思路：

• 服务发现负责告诉我们：

  • 当前有哪些实例
  • 每个实例属于哪个版本
  • 实例健康状态如何

• 一致性哈希负责决定：

  • 某个用户 / 某个租户 / 某个设备 ID 应该稳定地落到哪个实例或哪个版本
  • 当实例变化时，尽量减少重映射

• 灰度规则负责定义：

  • 哪些流量可以进入灰度
  • 灰度比例是多少
  • 是按用户、地域、租户还是请求特征进行切分

可以把它理解成三层职责：

flowchart LR
    A[客户端请求] --> B[灰度规则判断]
    B -->|命中灰度| C[一致性哈希选择灰度实例]
    B -->|未命中灰度| D[一致性哈希选择稳定实例]
    C --> E[服务发现实例列表]
    D --> E
    E --> F[目标服务实例]

这套方案的优点在于：

• 稳定性强：同一个哈希键通常会稳定命中相同实例或相同版本
• 扩缩容友好：一致性哈希能减少大面积请求迁移
• 治理边界清晰：服务发现管实例，哈希环管映射，灰度规则管入口
• 适合中间件化：可以放在网关、SDK 或 Service Mesh 扩展里实现

当然，它也不是银弹。后面我会专门讲取舍和边界条件。

核心原理

1. 一致性哈希解决了什么问题

普通哈希常见做法是：

index = hash(user_id) % N

这里 N 是实例数。问题在于，只要实例数从 10 变成 11，几乎所有用户都可能被重新映射。对于缓存、会话和灰度来说，这种抖动很要命。

一致性哈希的基本思想是：

1. 把哈希空间看成一个环
2. 把服务实例映射到环上的多个点（虚拟节点）
3. 把请求键也映射到环上
4. 顺时针找到第一个实例点作为目标节点

这样当某个实例加入或移除时，只有局部区间的键需要迁移，而不是全量重算。

flowchart TD
    A[哈希环 0~2^32-1] --> B[实例A 虚拟节点]
    A --> C[实例B 虚拟节点]
    A --> D[实例C 虚拟节点]
    E[请求键 user_123] --> F[映射到环上某点]
    F --> G[顺时针找到最近实例]

2. 为什么灰度发布适合用一致性哈希

灰度发布最怕“同一个用户反复横跳”。一致性哈希正好适合把用户维度的稳定性做出来。

常见哈希键可以是：

• user_id
• tenant_id
• device_id
• session_id
• 订单号、商户号 等业务主键

如果你的目标是“让同一个用户持续看到同一版本”，就应该优先选用户身份稳定且唯一的键，而不是 IP 这种容易变化的字段。

一个典型策略是：

• 先按灰度规则筛出“允许进入灰度的人”
• 再在灰度实例集合中做一致性哈希选路
• 非灰度人群则在稳定实例集合中做一致性哈希

这样能同时实现：

• 灰度比例可控
• 用户体验稳定
• 实例变动影响可接受

3. 服务发现提供实时实例视图

一致性哈希依赖一个前提：你得知道当前有哪些可用实例。

服务发现通常提供：

• 注册：实例启动后登记自身地址、版本、权重、健康状态
• 续约：定期心跳
• 摘除：实例异常或下线时移出列表
• 订阅：消费者实时感知实例变更

在灰度场景下，注册信息最好至少包含：

• instance_id
• host
• port
• version
• status
• weight（可选）
• zone / region（可选）

这里有个实践经验：不要把“版本号”只放在日志里，必须进入服务发现元数据。不然路由层根本无法按版本做实例筛选。

4. 请求路由的推荐流程

一个更完整的调用链如下：

sequenceDiagram
    participant Client as 客户端
    participant Gateway as 网关/路由层
    participant Registry as 服务发现
    participant Ring as 一致性哈希环
    participant Svc as 目标服务实例

    Client->>Gateway: 发起请求(user_id, headers)
    Gateway->>Registry: 拉取/订阅可用实例列表
    Registry-->>Gateway: 返回 v1/v2 实例元数据
    Gateway->>Gateway: 执行灰度规则判断
    Gateway->>Ring: 基于 user_id 进行一致性哈希
    Ring-->>Gateway: 返回目标实例
    Gateway->>Svc: 转发请求
    Svc-->>Gateway: 返回响应
    Gateway-->>Client: 响应结果

5. 方案对比与取舍分析

方案 A：纯随机/权重分流

优点：

• 实现简单
• 适合短期试验

缺点：

• 用户不稳定
• 实例变化后结果不可预测
• 不适合依赖会话、缓存、个性化状态的业务

方案 B：按用户 ID 做固定百分比分流

例如：

hash(user_id) % 100 < 10 -> 灰度

优点：

• 比随机稳定
• 适合决定“是否进入灰度”

缺点：

• 只能解决“进不进灰度”
• 不能很好解决“进入灰度后落到哪台实例”

方案 C：一致性哈希 + 服务发现

优点：

• 用户级稳定性强
• 适配实例变化
• 能和服务治理体系融合

缺点：

• 实现复杂度更高
• 需要处理本地缓存、订阅延迟、虚拟节点、故障摘除等问题

如果你的系统规模较小、实例数量少、业务无状态，方案 B 已经够用；但如果你已经进入多实例、频繁扩缩容、服务治理完善的阶段，方案 C 的价值会非常明显。

架构设计与容量估算

推荐架构

我更推荐把灰度决策收敛在统一路由层，比如网关或服务调用 SDK，而不是让每个业务服务自己写一套。

职责建议如下：

• 配置中心

  • 存灰度规则：人群、比例、白名单、地域等

• 服务发现

  • 存实例元数据：版本、健康状态、地址

• 路由层

  • 拉取规则
  • 订阅实例变化
  • 维护本地一致性哈希环
  • 输出最终目标实例

• 业务服务

  • 专注处理业务
  • 通过版本标识配合发布

容量估算的几个关键点

1. 哈希环大小

如果实例数不多，一致性哈希本身的存储不是瓶颈，真正影响均衡性的往往是虚拟节点数。

经验值：

• 小规模：每实例 50~100 个虚拟节点
• 中规模：每实例 100~300 个虚拟节点
• 对均衡要求高：可继续增加，但会带来构建和查找开销

2. 路由缓存刷新频率

不要每次请求都去服务发现中心查实例列表。一般做法是：

• 常驻本地缓存
• 基于订阅机制实时更新
• 失败时回退到最近一次快照

3. 灰度比例粒度

常见粒度：

• 1%
• 0.1%
• 指定白名单

如果用户规模很小，1% 可能样本都不够；如果日活很大，0.1% 也可能已经是相当大的流量。比例不是越细越好，而是要匹配你的验证目标和风险承受能力。

实战代码（可运行）

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

1. 服务发现维护实例列表
2. 一致性哈希构建哈希环
3. 灰度规则决定用户是否进入 v2
4. 请求根据用户 ID 稳定路由到对应版本实例

你可以直接保存成 gray_release_demo.py 运行。

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


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


@dataclass(frozen=True)
class ServiceInstance:
    instance_id: str
    host: str
    port: int
    version: str
    healthy: bool = True
    weight: int = 1

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


class ServiceRegistry:
    def __init__(self):
        self.instances: Dict[str, ServiceInstance] = {}

    def register(self, instance: ServiceInstance):
        self.instances[instance.instance_id] = instance

    def deregister(self, instance_id: str):
        self.instances.pop(instance_id, None)

    def set_health(self, instance_id: str, healthy: bool):
        if instance_id in self.instances:
            old = self.instances[instance_id]
            self.instances[instance_id] = ServiceInstance(
                instance_id=old.instance_id,
                host=old.host,
                port=old.port,
                version=old.version,
                healthy=healthy,
                weight=old.weight
            )

    def get_instances(self, version: Optional[str] = None) -> List[ServiceInstance]:
        result = []
        for ins in self.instances.values():
            if not ins.healthy:
                continue
            if version and ins.version != version:
                continue
            result.append(ins)
        return result


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

    def rebuild(self, instances: List[ServiceInstance]):
        self.ring = []
        self.nodes = {}
        for ins in instances:
            virtual_count = self.replicas * max(1, ins.weight)
            for i in range(virtual_count):
                key = f"{ins.instance_id}#{i}"
                h = md5_hash(key)
                self.ring.append(h)
                self.nodes[h] = ins
        self.ring.sort()

    def get_node(self, key: str) -> ServiceInstance:
        if not self.ring:
            raise RuntimeError("hash ring is empty")
        h = md5_hash(key)
        idx = bisect.bisect(self.ring, h)
        if idx == len(self.ring):
            idx = 0
        return self.nodes[self.ring[idx]]


class GrayRouter:
    def __init__(self, registry: ServiceRegistry, replicas: int = 100):
        self.registry = registry
        self.replicas = replicas
        self.rings: Dict[str, ConsistentHashRing] = {}

    def refresh(self):
        versions = set(ins.version for ins in self.registry.get_instances())
        self.rings = {}
        for version in versions:
            ring = ConsistentHashRing(replicas=self.replicas)
            ring.rebuild(self.registry.get_instances(version=version))
            self.rings[version] = ring

    def in_gray(self, user_id: str, gray_percent: int) -> bool:
        value = md5_hash(f"gray:{user_id}") % 100
        return value < gray_percent

    def route(self, user_id: str, gray_percent: int = 0) -> ServiceInstance:
        target_version = "v2" if self.in_gray(user_id, gray_percent) and "v2" in self.rings else "v1"
        if target_version not in self.rings:
            raise RuntimeError(f"no available instances for version={target_version}")
        return self.rings[target_version].get_node(user_id)


def bootstrap_registry() -> ServiceRegistry:
    registry = ServiceRegistry()
    registry.register(ServiceInstance("v1-node-1", "10.0.0.1", 8080, "v1"))
    registry.register(ServiceInstance("v1-node-2", "10.0.0.2", 8080, "v1"))
    registry.register(ServiceInstance("v1-node-3", "10.0.0.3", 8080, "v1"))

    registry.register(ServiceInstance("v2-node-1", "10.0.1.1", 8080, "v2"))
    registry.register(ServiceInstance("v2-node-2", "10.0.1.2", 8080, "v2"))
    return registry


def demo():
    registry = bootstrap_registry()
    router = GrayRouter(registry, replicas=120)
    router.refresh()

    users = ["u1001", "u1002", "u1003", "u1004", "u1005", "u1006", "u1007", "u1008"]

    print("=== 灰度 30% ===")
    for user_id in users:
        ins = router.route(user_id, gray_percent=30)
        print(f"user={user_id} -> version={ins.version}, instance={ins.instance_id}, addr={ins.address()}")

    print("\n=== 模拟 v2-node-2 故障摘除 ===")
    registry.set_health("v2-node-2", False)
    router.refresh()

    for user_id in users:
        ins = router.route(user_id, gray_percent=30)
        print(f"user={user_id} -> version={ins.version}, instance={ins.instance_id}, addr={ins.address()}")

    print("\n=== 模拟新增 v2-node-3 ===")
    registry.register(ServiceInstance("v2-node-3", "10.0.1.3", 8080, "v2"))
    router.refresh()

    for user_id in users:
        ins = router.route(user_id, gray_percent=30)
        print(f"user={user_id} -> version={ins.version}, instance={ins.instance_id}, addr={ins.address()}")


if __name__ == "__main__":
    demo()

运行效果说明

这个示例里有两个关键动作：

• in_gray(user_id, gray_percent)

  • 决定用户是否进入灰度版本
  • 它本质是稳定分流，而不是随机分流

• get_node(user_id)

  • 在某个版本实例集合内，用一致性哈希挑选目标实例
  • 同一个用户通常会持续落到同一台机器，除非实例变化影响到它所在区间

代码里的设计要点

1. 先定版本，再定实例

这是个很重要的顺序：

1. 先决定用户是否进灰度
2. 再在该版本实例集合内做一致性哈希

不要把 v1 和 v2 全混在一个哈希环里，否则你会很难精确控制灰度比例。

2. 灰度和实例选择用不同的哈希输入

示例中用了：

• gray:{user_id} 决定是否进灰度
• user_id 决定路由到哪台实例

这样做能减少策略耦合，后续调节灰度比例时更直观。

3. 实例健康状态直接影响哈希环构建

不健康实例不进入哈希环，这样调用方不会继续把流量打过去。

逐步验证清单

如果你想把这个方案从 demo 推到测试环境，我建议按下面顺序验证。

验证 1：同一用户路由稳定

对同一 user_id 连续发起多次请求，确认它始终命中同一版本、同一实例。

for _ in range(10):
    ins = router.route("u1001", gray_percent=30)
    print(ins.version, ins.instance_id)

验证 2：灰度比例大体符合预期

构造一批用户，统计进入 v2 的比例。

total = 10000
gray = 0
for i in range(total):
    uid = f"user_{i}"
    if router.route(uid, gray_percent=20).version == "v2":
        gray += 1
print("gray ratio =", gray / total)

验证 3：实例摘除后迁移范围是否可接受

把某个 v2 实例下线，观察有多少灰度用户被迁移到其他 v2 节点，而不是全量漂移。

验证 4：版本回滚是否生效

把 gray_percent 从 30 改回 0，确认所有用户稳定回到 v1。

常见坑与排查

这一部分很重要，因为真实线上问题通常不是“代码不会写”，而是“写完以后怎么知道路由为什么变了”。

坑 1：虚拟节点太少，流量分布严重倾斜

现象

• 某些实例负载明显偏高
• 灰度样本虽然比例正确，但实例间不均衡

原因

一致性哈希如果每个实例只有很少的节点，哈希环分布会不均匀。

排查方法

• 打印每个实例的虚拟节点数量
• 用一批样本用户统计每个实例命中次数
• 观察是否出现明显长尾

建议

• 每实例至少 100 个虚拟节点起步
• 如果实例权重不同，按权重扩展虚拟节点数
• 不要只拿几十个用户做均衡性判断，样本要足够大

坑 2：服务发现视图不一致

现象

• A 节点认为 v2 有 3 台机器
• B 节点认为 v2 只有 2 台
• 导致不同入口对同一用户算出的目标实例不同

原因

• 实例订阅延迟
• 本地缓存刷新不及时
• 配置变更和实例变更不是原子生效

排查方法

• 输出当前路由节点持有的实例快照版本号
• 比对各网关 / SDK 的本地实例列表
• 检查服务发现订阅日志与更新时间

建议

• 为实例列表增加版本号或时间戳
• 路由日志里打印“规则版本 + 实例版本”
• 使用“先构建新环，再原子替换旧环”的方式更新本地状态

坑 3：灰度键选择错误

现象

• 同一个真实用户在不同设备、不同网络下被当成不同流量
• 用户反馈版本体验不一致

原因

用了不稳定字段做哈希键，比如：

• IP
• User-Agent
• 临时 session

建议

优先级一般是：

1. user_id
2. tenant_id
3. device_id
4. 稳定 session

如果用户未登录，再考虑降级方案，但要接受稳定性会下降。

坑 4：实例摘除后触发雪崩

现象

• 一台实例故障摘除后，其他实例瞬间打满
• RT 和错误率一起升高

原因

一致性哈希只能减少迁移，不能凭空创造容量。如果灰度实例本来就很少，一台挂掉后剩余实例接不住流量，还是会出问题。

建议

• 灰度集群至少保留冗余实例
• 做好限流、熔断、降级
• 灰度初期宁可比例小一点，也不要让 v2 容量踩着红线跑

坑 5：回滚时“逻辑回滚”了，但“路由没回滚”

现象

配置里已经把灰度比例调成 0，但少量请求仍然进 v2。

原因

• 本地规则缓存未刷新
• 长连接或会话黏性还停留在旧实例
• 多层路由中某一层仍在执行旧规则

排查方法

按链路逐层看：

1. 网关规则版本
2. SDK 规则版本
3. 服务发现实例状态
4. 服务端日志中的实际版本标识

这类问题我踩过，最后发现是网关已经回滚，但客户端 SDK 本地缓存还保留了旧分流逻辑，导致回滚“看起来成功，实际上不彻底”。

安全/性能最佳实践

灰度发布常被理解成“流量治理问题”，但它其实也牵涉到安全和性能。

安全最佳实践

1. 不要信任客户端自带的灰度标记

如果客户端传一个 header：X-Gray-Version: v2，服务端就直接放行，这是有风险的。外部请求完全可能伪造这个头。

建议：

• 灰度决策在可信网关或服务端完成
• 客户端传来的标记只作参考，不作最终依据
• 对内部 Header 做签名或在内网层透传

2. 灰度白名单要有审计

很多线上事故不是出在算法，而是出在“谁把哪些账号加入了灰度名单”。

建议记录：

• 操作人
• 变更时间
• 变更前后内容
• 生效环境

3. 版本元数据要校验来源

服务发现中的 version 字段不能让任意实例随便注册成生产灰度版本，否则路由层可能把真实流量打到错误节点。

建议：

• 结合发布平台自动注册版本信息
• 对实例身份做认证
• 避免手工填写关键元数据

性能最佳实践

1. 哈希环在内存中维护，按变更重建

不要每次请求都重建哈希环。正确姿势是：

• 订阅到实例变更事件
• 后台线程重建新环
• 原子切换引用
• 请求线程只读访问

2. 避免请求路径上的远程依赖

一次路由决策如果还要实时查配置中心、查注册中心，延迟和可用性都会很难看。

建议：

• 配置本地缓存
• 实例列表本地缓存
• 失败时使用最近快照 + 短暂容忍窗口

3. 路由结果要可观测

至少打出这些日志字段：

• user_id 或脱敏后的 hash key
• gray_hit
• target_version
• target_instance
• rule_version
• registry_version

这样一旦用户反馈“为什么我进了旧版本”，你能快速知道是规则判断错了，还是实例选择错了。

4. 配合熔断与重试策略

一致性哈希强调稳定路由，但当目标实例临时不可用时，也不能死磕。

建议：

• 首选实例失败后，在同版本实例集合内做有限次重试
• 不要轻易跨版本重试，除非业务明确允许
• 重试次数控制在 1~2 次，避免放大故障

一个更贴近生产的落地建议

如果你准备把这个方案真正用起来，我建议从下面这个最小可行版本开始：

第一步：只做“按用户稳定进灰度”

先实现：

hash(user_id) % 100 < gray_percent

目标是先解决“同一用户是否进灰度”的稳定性问题。

第二步：在版本内加入一致性哈希选实例

当你已经有多个 v2 实例，并且发现灰度实例切换导致缓存抖动、用户漂移时，再引入一致性哈希。

第三步：把实例元数据纳入服务发现

确保服务发现里有：

• 版本
• 健康状态
• 权重
• 可选地域信息

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

上线前一定要有：

• 灰度命中率监控
• 各版本错误率 / RT 监控
• 一键回滚
• 白名单验证通道

很多团队不是不会做灰度，而是没有把“观测”和“回滚”当成方案的一部分。这点很关键。

总结

基于一致性哈希与服务发现做灰度发布，核心价值可以概括成一句话：

让流量分配不仅“可控”，而且“稳定”。

整套方案的关键点是：

1. 服务发现负责提供实时、可信的实例列表
2. 灰度规则负责决定哪些用户进入新版本
3. 一致性哈希负责让同一用户稳定命中同一实例，并减少实例变化带来的迁移
4. 观测、回滚、熔断决定了这套方案能不能真正用于生产

如果你只记住一个实践建议，我会建议你记这个：

先按“版本”做灰度切分，再在“版本内”做一致性哈希选实例。

这样设计最清晰，也最容易排查问题。

最后给一个适用边界：

• 适合

  • 多实例服务
  • 需要用户体验稳定
  • 有服务发现体系
  • 有扩缩容或故障摘除场景

• 不一定适合

  • 单体应用
  • 极小规模服务
  • 纯无状态、短连接、无需用户稳定性的场景

如果你的系统正好处在“随机灰度已经不太够用，但又不想一下子上复杂 Mesh”的阶段，这套方案通常是一个很实用的中间路径。它不花哨，但足够稳，也足够能打。