企业官网建设流程全解析

Nacos 如何对同一配置做 beta 灰度发布并按客户端 IP 命中灰度版本？

【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos

本文解决的问题是：同一个namespaceId + groupName + dataId的配置，如何额外发布一份只对被指定客户端 IP 可见的 beta 版本，并验证命中与退出灰度的完整流程。Nacos 中灰度版本是同一 Config 身份下的从属发布状态（namespaceId -> groupName -> dataId -> grayName），不是新的一条顶层配置。beta 内置规则按grayName=beta存储，匹配条件是请求标签ClientIp在逗号分隔的 beta IP 列表中，优先级为Integer.MAX_VALUE（内置规则中最高）。以下内容基于 Nacos 3.x 的灰度模型（config_info_gray表 +GrayRule），相关语义定义见 Config 灰度发布规范。

操作前的两个前提

1. 有一个可通过 HTTP 访问的 Nacos 服务端。下文所有接口路径都带有/nacos前缀，例如/nacos/v3/admin/cs/config；命令中的http://<Nacos 服务地址>需要你替换为实际可访问的协议、主机和端口。
2. 从 3.3 版本线开始，运行时不再支持从旧表config_info_beta、config_info_tag向config_info_gray的兼容迁移。如果你的部署来自 3.0 之前版本且使用过 beta 灰度发布，必须先完成相关数据迁移再升级，否则本文流程不适用于旧表中的数据。

第一步：发布正式配置

beta 版本依附于正式配置，先确保正式版本存在。向POST /nacos/v3/admin/cs/config提交 form 表单发布（字段与 集成测试的表单构造 一致）：

curl -X POST 'http://<Nacos 服务地址>/nacos/v3/admin/cs/config' \ -d 'dataId=gray.example.com' \ -d 'groupName=DEFAULT_GROUP' \ -d 'content=formal-content' \ -d 'tag=' \ -d 'appName=' \ -d 'src_user=' \ -d 'configTags=' \ -d 'desc=' \ -d 'use=' \ -d 'effect=' \ -d 'type=text' \ -d 'schema='

成功时响应为{"data": true}（测试中对该布尔值做了断言）。不传namespaceId时默认使用publicnamespace。

第二步：用 betaIps 请求头发布 beta 版本

关键点：同一个发布接口，只需额外携带betaIps请求头，携带betaIps的发布会写入 beta 灰度版本，而不是覆盖正式配置；不带灰度选择字段的发布才写正式配置。

curl -X POST 'http://<Nacos 服务地址>/nacos/v3/admin/cs/config' \ -H 'betaIps: 10.0.0.2' \ -d 'dataId=gray.example.com' \ -d 'groupName=DEFAULT_GROUP' \ -d 'content=beta-content' \ -d 'tag=' \ -d 'appName=' \ -d 'src_user=' \ -d 'configTags=' \ -d 'desc=' \ -d 'use=' \ -d 'effect=' \ -d 'type=text' \ -d 'schema='

betaIps的取值是要命中的客户端 IP，逗号分隔可写多个 IP。示例中的10.0.0.2、gray.example.com、DEFAULT_GROUP等均为示例值，替换为你自己的 dataId、group 和客户端 IP。成功后同样返回{"data": true}，此后该配置同时拥有正式版本和grayName=beta的灰度版本，两者共享namespaceId + groupName + dataId，但内容、md5、最后修改时间和灰度规则各自独立。

第三步：通过 Admin beta 查询接口验证 beta 版本已生效

验证用专门的 beta 查询端点，而不是正式配置查询。注意：Admin 正式查询不会静默返回灰度内容，要检查 beta 版本必须走 beta 端点：

curl 'http://<Nacos 服务地址>/nacos/v3/admin/cs/config/beta?dataId=gray.example.com&groupName=DEFAULT_GROUP'

namespaceId可省略（省略时为public）。命中时data中包含该配置的身份、beta 内容和规则，示例结果（字段来自 beta Admin API 集成测试 的断言）：

{ "data": { "dataId": "gray.example.com", "groupName": "DEFAULT_GROUP", "namespaceId": "public", "content": "beta-content", "grayName": "beta", "grayRule": "<包含 betaIps 的序列化灰度规则>" } }

其中grayRule为序列化后的灰度规则，测试断言其内容包含发布时传入的betaIps值。如果该配置当前没有 beta 版本，接口返回 HTTP 404，错误码为RESOURCE_NOT_FOUND，错误消息为Config is not in beta。

第四步：按客户端 IP 验证运行时灰度命中

运行时查询端点是GET /nacos/v3/client/cs/config，供客户端获取实际生效的配置：

curl 'http://<Nacos 服务地址>/nacos/v3/client/cs/config?dataId=gray.example.com&groupName=DEFAULT_GROUP'

命中逻辑由 Config 发布与查询规范 定义：运行时查询先从客户端 IP、显式 tag 和连接标签构建请求标签，再遍历已排序的灰度版本，返回第一个命中的灰度版本；未命中才回退正式配置。因此：

• 从betaIps列表中的机器（本例中源 IP 为10.0.0.2的客户端）发起该请求，返回的是 beta 内容，响应还包含命中的灰度版本的 md5、encryptedDataKey、最后修改时间、配置类型和灰度元数据；
• 从列表外的机器发起同一请求，返回的是正式配置内容。

当存在多个灰度版本时，按优先级降序匹配，优先级相同再按grayName排序；beta 规则优先级为Integer.MAX_VALUE，是内置规则中最先被匹配的。响应中是否包含 beta/tag 元数据字段的验证，可参考 Client API 测试场景说明 中ConfigOpenApiITCase对GET /v3/client/cs/config的描述。

第五步：停止灰度，删除 beta 版本

确认灰度完成后，删除 beta 版本即可退出灰度：

curl -X DELETE 'http://<Nacos 服务地址>/nacos/v3/admin/cs/config/beta?dataId=gray.example.com&groupName=DEFAULT_GROUP'

删除灰度版本只移除该版本，不删除正式配置。删除后再执行第三步的 beta 查询会返回 404（Config is not in beta），此时所有客户端都拿回正式配置，这一查询结果就是灰度已停止的判定依据。

可选分支：Console 侧存在等价的/nacos/v3/console/cs/config/beta查询与删除端点（见 Console API 测试场景说明），行为差异是 beta 不存在时返回 HTTP 200 且data=null，而不是 404；Console 发布走 Console 请求头体系。

限制与边界

• 单个配置的最大灰度版本数受nacos.config.gray.version.max.count限制，默认值为10；beta 与 tag 灰度版本都计入该限制。
• 内置灰度规则只有两类：beta（ClientIp命中逗号分隔的 beta IP 列表）和tag（grayName为tag_{tag}，按请求 tag 匹配）。如果请求显式指定 tag 但未命中 tag 灰度，会返回 tag-specific not-found，而不是回退正式配置。
• 灰度内容持久化在config_info_gray表中，灰度发布或删除都会记录历史变更并触发携带对应grayName的 Config 变更事件；beta/tag 变更在 3.3 版本线之后不得再通过 legacyisBeta/tag字段做旧表迁移。
• 除 HTTP 接口外，Maintainer SDK 通过BetaConfigMaintainerService提供 beta 和灰度发布的编程能力，适合把上述流程放进运维脚本，见 SDK Java 实现规范。

进一步阅读：Config 灰度发布规范、Config 发布与查询规范、Admin API 测试场景说明。

【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos