不同版本引擎有啥区别_版本差异与升级注意事项【说明】

微服务引擎1.x升级2.x时配置中心断连属正常闪断，因切换至kie导致短暂重启；需改用kie协议、json格式含labels的配置文件，并升级sdk，升级不可回退。

微服务引擎 1.x → 2.x：配置中心断连是正常现象，不是故障

升级过程中出现 Connection refused 或 Connection was closed 错误，本质是配置中心（从旧版切换为 KIE）短暂重启导致的连接闪断，不是网络或代码问题。

• 升级窗口期内，ConfigCenterClient 会持续重试，但所有配置读写请求都会失败，此时切勿人工干预或反复重试接口
• 已运行的微服务业务不受影响，只是无法动态刷新配置；升级完成后连接自动恢复，无需重启服务
• 若你在升级中正执行灰度发布、配置热更或 A/B 测试，务必暂停——这些操作依赖配置中心实时响应，此时极易出错

spring Cloud 项目接入配置中心：必须改用 KIE 协议，否则“业务场景治理”不可用

引擎 2.x 底层配置中心已替换为 KIE，而 1.x 使用的是旧协议（如基于 zookeeper 或自研 http 接口）。不切换接入方式，会导致控制台功能缺失、配置推送失效。

• 检查你项目中的 spring.cloud.servicecomb.config.client.serverUri 配置，它必须指向 /kie/v1 接口，例如 http://your-engine-endpoint:30100/kie/v1
• 旧版 SDK（如 servicecomb-java-chassis 1.x）不兼容 KIE 的 label 匹配逻辑，需升级到支持 2.x 引擎的 SDK 版本（通常 ≥ 2.10.0）
• “业务场景治理”功能（如熔断策略按环境/服务维度生效）底层强依赖 labels 字段，旧协议无此概念，跳过切换等于放弃该能力

导入配置文件失败：JSON 格式 + 必填 labels 是硬性门槛

2.x 引擎不再接受传统 properties 或 YAML 格式的配置文件，也不再兼容无范围标识的扁平 key-value。报 文件为空 或 格式错误，基本都是结构没对上。

• 必须是合法 JSON，根节点为 {"data":[...]}，不能是数组直接开头或带 bom 头
• key 和 value 是字符串类型，必填；labels 是对象，也必填——哪怕只填 {"environment":"prod"}，空对象 {} 或缺字段都会拒收
• value_type 必须显式指定，比如 JSON 内容要写 "value_type":"json"，不能省略或写成 "json"
• 示例片段（注意缩进无关，但字段名和嵌套层级不能错）：

  { "data": [{ "key": "app.timeout.ms", "labels": { "environment": "prod", "service": "order-service" }, "value": "5000", "value_type": "text", "status": "enabled" }] }

升级后无法回退：别在生产环境做“试试看”

引擎升级是单向操作，控制台不提供降级按钮，也没有 rollback 接口。一旦确认升级，旧版配置中心数据虽保留，但新引擎不再识别其存储格式。

• 升级前必须完成全量配置导出（用 2.x 要求的 JSON 格式），并验证导出内容可被新引擎成功导入
• 若使用了自定义配置监听逻辑（如手动轮询 /v1/configs），需同步检查响应结构是否从 flat list 变为带 labels 的嵌套结构
• 最易被忽略的一点：SDK 连接池复用旧连接时，可能因协议升级后 TLS 握手参数变化（如禁用 TLS 1.1）导致静默失败，建议升级后抓包确认首次连接是否走通 /kie/v1/health