如何用 Unleash 做灰度发布：GradualRollout 策略从 1% 到 100% 完整指南

如何用 Unleash 做灰度发布：GradualRollout 策略从 1% 到 100% 完整指南

【免费下载链接】unleashOpen-source feature management platform项目地址: https://gitcode.com/GitHub_Trending/un/unleash

Unleash 是一款流行的开源 feature flag（功能开关）管理平台。本文将带你从零理解灰度发布的核心思路，并逐步详解 Unleash 中GradualRollout 策略如何把新功能按 1% → 10% → 50% → 100% 的节奏安全地放给真实用户，附粘性分桶原理与常见问题排查清单。

什么是灰度发布？为什么选择 Unleash

灰度发布（又称金丝雀发布）的本质是：不要一次性把新功能推给所有人，而是先放给一小部分用户，观察指标没问题后再逐步放量。

传统做法是"先上线 1% 版本的代码"，但改代码、发版、回滚都很重。Unleash 的思路是：代码先全量部署到生产环境，用feature flag控制开关。SDK 在本地实时评估"这个用户该不该看到新功能"，你在管理界面拖动一个百分比滑杆，就能在几秒内完成放量或紧急关闭。

这种设计带来两个关键好处：

• 秒级回滚：出问题时把百分比调到 0%，无需重新发版；
• 隐私友好：评估逻辑运行在你自己的应用进程内，用户数据不会上传到 Unleash 服务端（见架构图中的 Privacy 说明）。

三种 GradualRollout 策略对比

Unleash 内置了三个灰度策略，区别在于按什么维度分桶：

它们的实现都在策略目录中，值得逐个看一下：

• gradual-rollout-user-id.ts
• gradual-rollout-session-id.ts
• gradual-rollout-random.ts

粘性分桶：为什么同一用户不会"忽开忽关"

gradualRolloutUserId的核心逻辑只有几行（见源码）：

// 对 userId 做归一化哈希，得到一个 1~100 的固定桶号 const normalizedUserId = normalizedStrategyValue(userId, groupId); return percentage > 0 && normalizedUserId <= percentage;

关键在normalizedStrategyValue：它用MurmurHash3对groupId:userId做哈希，再对 100 取模 +1，得到该用户固定的桶号（1~100）。实现见 util.ts。

这带来灰度发布最重要的两个性质：

1. 确定性：同一个用户永远落在同一个桶里，不会今天看到新功能、明天又看不到；
2. 单调放量：桶号为 5 的用户，在 1%、5%、10%…100% 的任何阶段都命中。也就是说50% 的灰度用户，一定包含 1% 阶段的那批用户，放量过程完全平滑、无跳变。

从 1% 到 100%：一个典型的放量节奏

在 Unleash 管理界面中创建 feature toggle 后，你会看到类似下面的特性列表，每个开关都带一个百分比标识和启用开关：

推荐的放量节奏（可按你的业务调整）：

操作方式非常简单：

1. 在 feature toggle 详情里选择GradualRollout策略（新版界面中即百分比滑杆）；
2. 选择按userId分桶，把percentage填为 1，保存；
3. 监控指标正常后，把数字改成 10、50，无需重启应用、无需发版，SDK 会轮询拉取最新配置并即时生效；
4. 达到 100% 并稳定运行一段时间后，记得清理代码中的 flag 分支——这也是功能开关生命周期管理的一部分。

💡 小技巧：groupId参数控制哈希的"盐"。默认情况下每个 feature 自动用自身名称做隔离，意味着不同开关的 1% 用户不重叠，适合 A/B 场景；如果你想让多个开关共享同一批灰度用户，可给它们设置相同的groupId。

FlexibleRollout：新一代灰度策略

Unleash 后来推出了更通用的flexibleRollout策略，把三个旧策略合并为一个，见 flexible-rollout-strategy.ts。它的核心概念是stickiness（粘性）：

• default：优先用userId，没有则用sessionId，都没有则随机——一个策略覆盖所有场景；
• random：等价于旧版gradualRolloutRandom；
• 任意上下文字段：比如remoteAddress，就能按 IP 灰度——非常适合"先开放给北京机房、再全网"的地域型灰度。

分桶算法与旧策略完全一致（同一个 MurmurHash3 归一化），所以老灰度桶的单调放量特性在新策略中依然成立。

常见问题排查清单

📌 相关文档与延伸阅读：

• 贡献指南与本地运行方式：CONTRIBUTING.md
• 后端整体架构说明：backend/overview.md
• 前端策略配置组件：frontend/src/component/
• 完整迁移历史（含 2019 年灰度策略引入记录）：CHANGELOG.md

小结

• GradualRollout 策略通过"哈希分桶 + 百分比比较"实现确定性灰度，保证 1% → 100% 放量过程平滑且可回滚；
• 按userId分桶是最稳妥的默认选择；需要地域、设备维度时，升级到FlexibleRollout的自定义 stickiness；
• 灰度只是发布链路的一环，配合 Unleash 的多环境（development/production）与变更审计，可以构建完整的低风险发布流程。

按上面的节奏把百分比从 1 拖到 100，你就能在 Unleash 里完成一次教科书级的灰度发布 🚀。

【免费下载链接】unleashOpen-source feature management platform项目地址: https://gitcode.com/GitHub_Trending/un/unleash