配置灰度发布

配置灰度发布用于在正式配置之外，为同一个配置资源发布一个或多个灰度版本。它适合先让少量客户端读取新内容，再决定是否扩大范围或发布为正式配置。

灰度版本不是新的顶层配置资源。它从属于同一个配置身份：

namespaceId -> groupName -> dataId -> grayName

正式配置和灰度配置共享 namespaceId、groupName 和 dataId，但可以有不同的内容、md5、加密数据 key 和灰度规则。

内置灰度规则

Nacos 当前内置两类常用规则：

同一个配置可以存在多个灰度版本。运行时查询会先评估灰度规则，再回退正式配置。

默认最多允许 10 个灰度版本，可通过 nacos.config.gray.version.max.count 调整。

查询行为

灰度查询遵循以下原则：

• 普通查询会先尝试匹配灰度规则，命中后返回灰度内容。
• 未命中灰度规则时，返回正式配置。
• 显式指定 tag 但没有命中对应 tag 灰度时，会返回 tag 维度的未找到结果。
• Admin 正式查询不应静默返回灰度内容。
• Admin beta 查询在 beta 版本存在时返回 beta 版本。

因此，灰度验证时要确认客户端是否带了预期的 IP 或 tag。不要只看正式配置详情页来判断灰度内容是否已经生效。

推荐流程

一个安全的灰度流程通常是：

发布正式配置
  -> 发布灰度版本
  -> 让指定客户端读取灰度
  -> 观察应用日志、指标和业务结果
  -> 确认后发布为正式配置，或停止灰度

建议把灰度和正式发布都纳入审计。灰度配置也会触发配置变更事件，相关客户端可能会收到通知并重新查询。

与加密和历史的关系

灰度配置和正式配置一样，可以受到配置加密插件影响。服务端会分别保存灰度内容和对应的加密数据 key。

灰度发布和删除也会写入历史。历史记录中会包含发布类型、grayName 和扩展信息，便于排查谁在什么时候发布了哪类灰度。

注意事项

• 灰度内容仍然是同一个配置资源的版本状态，不要用灰度来表达另一个独立配置。
• 灰度版本数量要控制，长期不用的灰度应及时停止。
• 灰度发布前确认客户端能正确传递 IP 或 tag。
• 灰度验证完成后，要明确选择“发布为正式配置”或“停止灰度”。
• 如果使用多节点集群，短时间内不同节点可能等待本地 dump 完成后才看到相同灰度视图。