概述
当生产环境已使用腾讯云 TSF（Tencent Service Framework）的 Consul 集群作为服务治理中心，并希望将已运行的服务迁移至北极星（Polaris）时，可采用本指引方案。本文档旨在帮助微服务应用将服务注册发现、配置管理及服务治理能力从 TSF Consul 平滑迁移到北极星集群。
适用对象： 使用公有云 TSF-Consul（共享实例）的所有客户
核心目标： 指导您将业务从共享版 TSF-Consul 平滑、安全地迁移至独占版 TSF-Polaris，解决共享架构的稳定性风险，并获得更强大的治理能力。完成迁移后，您的注册、配置、服务治理等数据流和控制面将完全由 TSF Polaris 承载，不再依赖 TSF Consul，TSF Consul 可考虑彻底下线。
迁移背景与价值
为什么需要迁移？
当前公有云 TSF-Consul 采用共享版架构，其核心组件（consul-server， consul-access， data-access）为多租户共用。随着业务规模增长，该架构存在以下固有风险：
稳定性风险：共享组件可能因个别租户的异常流量或操作影响全局稳定性。
性能瓶颈：共享资源存在性能上限，难以满足业务高速增长的需求。
运维复杂性：问题定位和故障隔离在共享环境下更为困难。
迁移至 TSF-Polaris 的价值
独占资源，稳定性提升：每个客户拥有独立的 Polaris 实例，彻底消除租户间干扰。
功能更强大：Polaris 提供比 Consul 更丰富的服务治理能力。
维度 | TSF Consul | 北极星（Polaris） |
服务注册发现 | 基于 Consul 协议 | 支持多协议（gRPC/HTTP），服务发现更高效 |
配置管理 | Consul KV | 独立配置中心，支持配置生效、版本管理 |
服务治理 | 功能有限 | 内置路由规则、熔断降级、访问限流、负载均衡 |
可观测性 | 基础监控 | 完善的监控面板与可观测性支持 |
多语言支持 | 主要面向 Java | 支持 Java、Go 等 |
扩展性 | 依赖 Consul 生态 | 开源生态，插件化架构，社区活跃 |
高性能与高可用：采用存算分离架构，支持水平无限扩展和跨地域容灾。
平滑过渡：提供分阶段迁移方案，保障业务在迁移过程中持续可用。
迁移策略概览
TSF Consul 迁移北极星采用分阶段平滑迁移策略，整个过程分为两个阶段：
阶段一：数据流迁移（后台操作）
TSF Consul 数据实时同步至 TSF Polaris
TSF Consul 控制台可读写，TSF Polaris 控制台仅可查看实例列表
说明：
完成阶段一后可以稳定运行在此状态，业务如有诉求再进行阶段二。
阶段二：应用切换与控制台迁移（客户配合操作）
第一步：客户更新应用 SDK，注册到 TSF Polaris
第二步：客户重新部署应用，切换注册配置中心
第三步：确认服务注册成功
最后：观察稳定后，完成控制台迁移，TSF Consul 禁止读写，彻底下线 TSF Consul
前提条件
在开始迁移之前，请确认以下条件已满足：
平台侧（运维人员）
已创建 TSF Polaris 实例，且实例状态正常运行
已具备数据同步机制的部署和运维能力
已盘点当前 TSF Consul 中的服务列表、配置文件清单、治理规则（路由、限流、熔断等）
客户侧（应用负责人）
已梳理当前应用的服务依赖关系
已了解各应用使用的 SDK 版本及配置方式
已评估应用对注册中心、配置中心的依赖程度
建议：迁移前对现有 TSF Consul 环境中的服务列表、服务实例数量、配置文件数量、治理规则进行完整盘点，形成资产清单，作为迁移验证的基线。
迁移步骤
阶段一：数据流迁移
阶段一由平台侧完成，通过数据同步机制将 TSF Consul 中的数据实时同步至 TSF Polaris。此阶段对客户业务完全透明，客户无需做任何修改。
1. 迁移内容
数据同步涵盖以下核心数据：
数据类型 | 说明 |
注册数据 | 服务信息、服务实例信息、实例元数据、健康检查状态 |
配置数据 | 配置分组、配置文件、配置版本历史 |
治理规则 | 路由规则、限流规则、熔断规则、访问控制策略 |
2. 费用说明
在步骤一开启前，您需要按要求创建北极星实例并在「迁移方案」Tab 页确认。确认后平台会将 TSF 的费用退回。
说明：
北极星实例创建要求，需要创建与 TSF Consul 同地域的北极星企业版实例，实例规格请同平台研发人员确认。
该北极星实例仅用于迁移，不可以用于其他业务。
3. 阶段一完成后的状态
阶段一完成后，系统处于以下状态：
操作 | TSF Consul | TSF Polaris |
读 | ✓ 可读 | ✓ 可读（仅可查看实例列表） |
写 | ✓ 可写 | × 不可写 |
TSF Consul 控制台正常读写，客户业务照常运行
TSF Polaris 控制台可以查看同步过来的数据，但不可写入
客户应用仍然注册在 TSF Consul 上，无需做任何修改
数据在后台实时同步，两端保持一致
说明：
重要：阶段一完成后，需确保数据同步稳定运行一段时间（建议观察不少于 3 天），确认同步链路稳定、数据无差异后，再决定是否启动阶段二。
阶段二：应用切换与控制台迁移
阶段二由客户配合完成，包括应用侧的 SDK 升级和重新部署，以及控制台的最终切换。阶段二分为三个步骤和最终收尾。
第一步：更新应用依赖为新版 SDK
更新应用依赖，使应用能够注册到 TSF Polaris，并按照指引接入配置和服务治理能力。
1. Maven 依赖更新
需要将 Spring Cloud TSF SDK 升级为新版 Spring Cloud Tencent SDK（支持 TSF Polaris）。
旧版本 TSF 使用 spring-cloud-tsf-dependencies 管理依赖版本，里面除了管理 TSF 本身涉及的组件，还包括 spring-boot-dependencies 和 spring-cloud-dependencies，因此需要进行以下修改
1.1 parent 依赖从 spring-cloud-tsf-dependencies 修改为 Spring Cloud 2021 对应的 Spring Boot Parent
<parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><!-- Spring Boot 版本号根据 Spring Cloud Tencent Release 信息进行调整 https://github.com/Tencent/spring-cloud-tencent/releases --><version>x.x.x</version></parent>
1.2 dependencyManagement 中添加 Spring Cloud 及 Spring Cloud Tencent（TSF）依赖 （该依赖在开源中央仓库，无需额外配置 Maven 仓库）
<dependencyManagement><dependencies><dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-dependencies</artifactId><!-- Spring Cloud 版本号根据 Spring Cloud Tencent Release 信息进行调整 https://github.com/Tencent/spring-cloud-tencent/releases --><version>xx.xx.xx</version><type>pom</type><scope>import</scope></dependency><dependency><groupId>com.tencent.cloud</groupId><artifactId>spring-cloud-tencent-dependencies</artifactId><!-- Spring Cloud Tencent（TSF）版本号根据 Spring Cloud Tencent Release 信息进行调整 https://github.com/Tencent/spring-cloud-tencent/releases --><version>xx.xx.xx</version><type>pom</type><scope>import</scope></dependency></dependencies></dependencyManagement>
2. 依赖修改
普通微服务
旧版本普通微服务中， 应用通过引用 spring-cloud-tsf-starter 依赖引入 TSF 治理能力，里面除了管理 TSF 本身涉及的组件还包括 spring-boot-starter-web、spring-cloud-starter-openfeign、 spring-cloud-starter-bootstrap 等开源可选的 Spring Cloud/Boot 依赖。TSF Spring Cloud 2024 SDK 完全开源，参考 Spring Cloud Consul 等其他开源项目，不默认包含这些可选依赖
按照以下步骤修改
2.1 去除 spring-cloud-tsf-starter 依赖
2.2 dependencies 引入开源 Spring Boot、Spring Cloud 依赖、Spring Cloud Tencent （TSF）依赖
<dependencies><!-- Web 服务需要 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!-- FeignClient 及相关用法需要 --><dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-starter-openfeign</artifactId></dependency><!-- Bootstrap 引导模式连接配置中心时需要 --><dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-starter-bootstrap</artifactId></dependency><!-- TSF 治理能力需要 --><dependency><groupId>com.tencent.cloud</groupId><artifactId>spring-cloud-starter-tencent-all</artifactId></dependency></dependencies>
微服务网关
旧版本 TSF 微服务网关中， 应用通过引用 spring-cloud-tsf-msgw-scg 依赖引入 TSF 治理能力，里面除了管理 TSF 本身涉及的组件还包括开源的 spring-cloud-starter-gateway 依赖，以及可选的 spring-cloud-starter-bootstrap 依赖。TSF Spring Cloud 2024 SDK 完全开源，参考 Spring Cloud Consul 等其他开源项目，不包含这些依赖
按照以下步骤修改
2.1 去除 spring-cloud-tsf-msgw-scg 依赖
2.2 dependencies 引入开源 Spring Cloud 依赖、Spring Cloud Tencent （TSF）依赖
<dependencies><!-- Spring Cloud Gateway 服务需要 --><dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-starter-gateway</artifactId></dependency><!-- Bootstrap 引导模式连接配置中心时需要 --><dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-starter-bootstrap</artifactId></dependency><!-- TSF 治理能力需要 --><dependency><groupId>com.tencent.cloud</groupId><artifactId>spring-cloud-starter-tencent-all</artifactId></dependency></dependencies>
第二步：重新部署应用，切换注册配置中心
应用依赖更新和配置调整完成后，通过 TSF 控制台重新部署应用，将注册配置中心切换为 TSF Polaris。
1. 控制台操作步骤
1.1 登录 TSF 控制台，进入目标应用的应用详情页面
1.2 编辑注册配置治理
1.3 开发框架选择 Spring Cloud
1.4 实例类别选择 独享实例（TSF Polaris）
1.5 选择可正常连通的 TSF Polaris 关联实例
1.6 保存配置
说明：
如果当前应用已存在部署组，不能直接修改注册配置治理类型。需先删除应用下的全部部署组，再修改注册配置治理设置；或新建一个应用进行迁移（推荐）。
2. 推荐方式：新建应用
2.1 在 TSF 控制台新建应用
2.2 开发框架选择 Spring Cloud
2.3 注册配置治理 > 实例类别选择 独享实例（TSF Polaris）
2.4 关联可正常连通的 TSF Polaris 实例
2.5 创建部署组，部署客户第一步改造后的新版本应用
3. 部署并启动应用
完成控制台配置后，部署新版本应用。应用启动后将自动注册到 TSF Polaris，并从 TSF Polaris 拉取配置。
第三步：确认服务注册成功
应用部署成功后，需确认服务已正确注册到 TSF Polaris。
1. 验证步骤
1.1 前往 TSF Polaris 控制台
1.2 进入服务列表页面
1.3 查找对应的服务名，确认以下信息：
服务已出现在列表中
服务实例数量与预期一致
实例状态为健康
实例心跳正常上报
1.4 检查配置中心，确认配置项已正确加载
1.5 进行服务间调用测试，验证服务发现和调用链路正常
2. 验证矩阵
验证项 | 验证方法 | 预期结果 |
服务注册 | TSF Polaris 控制台 > 服务列表 | 服务实例正常注册，状态健康 |
心跳上报 | 观察实例心跳时间戳 | 心跳持续正常上报 |
服务发现 | 调用方通过 Feign/RestTemplate 调用 | 服务调用成功，返回正确结果 |
配置拉取 | 查看应用日志 / Polaris 配置中心 | 配置正确拉取并生效 |
配置热更新 | 在 Polaris 修改配置值 | 应用实时感知变更 |
负载均衡 | 多次调用同一服务 | 请求按策略分发到不同实例 |
服务路由 | 配置路由规则，验证流量 | 流量按规则正确路由 |
熔断降级 | 模拟下游故障 | 熔断触发，降级逻辑生效 |
访问限流 | 高频请求同一服务 | 限流规则生效 |
