这是本节的多页打印视图。点击此处打印.

存量服务迁移

1: Eureka 迁移方案
2: Nacos 迁移方案

2.1: 协议兼容（推荐）
2.2: 配置迁移
2.3: 服务迁移

1 - Eureka 迁移方案

服务迁移

原理说明

北极星对Eureka的API进行了全兼容，因此，业务可以把北极星集群作为一个Eureka节点，加入到Eureka原来的集群中，基于Eureka原生的同步协议进行新老注册中心的服务数据双向同步。

在这种迁移模式下，用户可逐渐、分批次的将老集群中的eureka升级成北极星，升级过程对数据面不感知。新应用（使用Spring Cloud Tencent或其他北极星客户端），和存量应用（仍然使用Spring Cloud Netflix或者其他Eureka客户端），都可以接入到北极星完成注册发现，无需代码修改。

启动迁移

*** 安装北极星集群版 ***

需要先安装北极星集群版，可参考集群版安装

*** 迁移相关的参数说明 ***

北极星通过eureka-apiserver实现了与开源标准eureka接口全兼容，用户如果对eureka进行了一些定制，需要手动调整eurekaeureka-apiserver的相关参数。

所有的eureka相关的参数都在polaris.yaml中，在apiservers.option下面进行配置：

参数名	含义	示例
listenIP	eureka兼容的服务端监听IP	0.0.0.0
listenPort	eureka兼容的服务端监听端口	8761
namespace	通过eureka接口注册及发现的服务节点的命名空间，由于eureka本身没有命名空间的概念，所以针对eureka的服务管理操作必须在北极星某个命名空间下进行	default
refreshInterval	全量服务实例缓存的刷新间隔，单位秒	10
deltaExpireInterval	增量实例缓存的刷新间隔，单位秒	60
peersToReplicate	需要进行复制的对端eureka服务端节点列表	- 9.15.15.5:8761
customValues	自定义配置，用户如果对eureka服务端进行了定制并影响了参数，则可以把相关的参数填上，比如定制了dataCenterInfo，则可以将新的dci信息填入，北极星服务端会按照配置的信息进行下发	见" 定制dataCenterInfo"

*** 往北极星服务端添加eureka地址 ***

进入北极星集群中的其中一个节点，找到polaris.yaml配置文件，在apiservers.service-eureka.option下面，添加eureka服务端地址信息，用于做数据复制：

apiservers:
  - name: service-eureka
    option:
      ... // 其他配置
      peersToReplicate: // eureka服务端节点的地址列表
      - <eureka1 IP>:<eureka1 port>
      - <eureka2 IP>:<eureka2 port>

重启北极星服务端。

*** 往eureka服务端添加北极星服务端地址 ***

修改eureka服务端的配置，将北极星其中一个节点的地址，加入到原有的eureka集群中。

eureka:
  client:
    serviceUrl:
      defaultZone: http://<北极星服务端IP>:8761/eureka/

重启Eureka服务端。

*** 定制dataCenterInfo ***

如果用户对eureka-server进行了定制，比如定制了<dataCenterInfo class="com.netflix.appinfo.AmazonInfo">，那么可以在北极星把这个配置项加入，即可下发带有定制后的DCI相关的服务数据。

apiservers:
  - name: service-eureka
    option:
      ... // 其他配置
      customValues:
        dataCenterInfoClass: "com.netflix.appinfo.AmazonInfo"
        dataCenterInfoName: "myOwn"

迁移完成

配置好迁移后，可以在北极星控制台能同时查看到注册在eureka的实例，以及注册到北极星的实例，相互之间可以正常访问。

从eureka同步到北极星的服务实例，会打入internal-eureka-replicate:true的标签。

2 - Nacos 迁移方案

2.1 - 协议兼容（推荐）

提示

本章节仅适用于北极星服务端版本 >= 1.18.0

概述

如果你希望使用 Polaris 代替 Nacos 作为新的注册中心，Polaris 提供了协议兼容的方式，用户仅需要更改程序中的 nacos-client 的服务端接入地址即可。

准备Polaris服务端

需要预先安装好Polaris服务端，安装方式可参考：集群版安装

北极星服务端参数配置

apiservers:
  - name: service-nacos
    option:
      listenIP: "0.0.0.0"
      listenPort: 8848
      defaultNamespace: default
      connLimit:
        openConnLimit: false
        maxConnPerHost: 128
        maxConnLimit: 10240

在北极星的服务端配置文件 polaris-server.yaml 中，找到 apiservers 的配置，开启 service-nacos 的插件即可

参数描述

listenPort: 设置 nacos 协议兼容的 http 端口地址，grpc 端口会在该端口的基础上 + 1000
defaultNamespace: 设置 nacos 默认命名空间对应 Polaris 命名空间信息；默认情况下 polaris 的 default 命名空间 == nacos 的默认命名空间（public ）；即在默认 nacos 默认命名空间下配置下，如果用户连接的是 nacos-server，服务注册到的是 nacos 的 public 命名空间，如果连接的是 polaris，那么根据配置 defaultNamespace，则服务注册到的是 polaris 的 default 命名空间，配置中心同理。

注册发现

Nacos 服务名和北极星服务名映射关系

Nacos 字段	Nacos 字段值	北极星字段	北极星字段值描述
namespace	默认命名空间/非默认命名空间ID	namespace	default/命名空间名称
group	DEFAULT_GROUP	service	作为服务名的前缀
service	DEFAULT_GROUP	service	作为服务名的后缀，${group}__${service} 为最终的北极星服务名, 如果 group == DEFAULT_GROUP，则服务名为 ${service}
cluster	DEFAULT	instance.metadata	作为实例标签的一部份, 实例标签 key 为 internal-nacos-cluster

原生 Nacos-Client

Properties properties = new Properties();
properties.put(PropertyKeyConst.SERVER_ADDR, "北极星服务端IP:8848");
properties.put(PropertyKeyConst.NAMESPACE, "北极星命名空间名称");
properties.put(PropertyKeyConst.USERNAME, "可任意值");
properties.put(PropertyKeyConst.PASSWORD, "北极星用户/用户组的资源访问凭据 Token");

// 创建注册发现客户端
NamingService namingService = NacosFactory.createNamingService(properties);

Spring Cloud Alibaba

spring.cloud.nacos.username="可任意值"
spring.cloud.nacos.password="北极星用户/用户组的资源访问凭据 Token"
spring.cloud.nacos.discovery.server-addr="北极星服务端IP:8848"
spring.cloud.nacos.discovery.namespace="北极星命名空间名称"

Dubbo

dubbo
 registry
   address: nacos://北极星服务端IP:8848?username=可任意值&password={北极星用户/用户组的资源访问凭据 Token}
   parameters.namespace: 北极星命名空间名称
  metadata-report
    address: nacos://北极星服务端IP:8848

配置管理

Nacos 配置信息和北极星配置信息映射关系

Nacos 字段	Nacos 字段值	北极星字段	北极星字段值描述
namespace	默认命名空间/非默认命名空间ID	namespace	default/命名空间名称
group	DEFAULT_GROUP	group	北极星配置分组名称
dataId	application.yaml	file_name	北极星配置文件名称

原生 Nacos-Client

Properties properties = new Properties();
properties.put(PropertyKeyConst.SERVER_ADDR, "北极星服务端IP:8848");
properties.put(PropertyKeyConst.NAMESPACE, "北极星命名空间名称");
properties.put(PropertyKeyConst.USERNAME, "可任意值");
properties.put(PropertyKeyConst.PASSWORD, "北极星用户/用户组的资源访问凭据 Token");

// 注册配置客户端
ConfigService configService = new NacosConfigService(properties);

Spring Cloud Alibaba

spring.cloud.nacos.username="可任意值"
spring.cloud.nacos.password="北极星用户/用户组的资源访问凭据 Token"
spring.cloud.nacos.config.namespace="北极星命名空间名称"
spring.cloud.nacos.config.server-addr="北极星服务端IP:8848"
spring.cloud.nacos.config.group="北极星配置分组名称"

Dubbo

dubbo
  config-center
    address: nacos://北极星服务端IP:8848

2.2 - 配置迁移

概述

如果你希望使用 Polaris 代替 Nacos 作为新的配置中心，Polaris 提供 polaris-sync方案：通过 server-to-server 的迁移方式，将 Nacos 的配置迁移至 Polaris。

准备Polaris服务端

需要预先安装好Polaris服务端，安装方式可参考：集群版安装

准备 polaris-sync

说明：

polaris-sync 是基于 Java 编写的程序，如果你希望在 VM 上运行 polaris-sync，则需要在 VM 上安装相关 Java 运行环境。

Java 版本最低要求 JDK8

需要下载 polaris-sync 的最新 release 版本：下载地址。

下载完之后，将 polaris-sync-server-${version}.zip 进行解压

wget https://github.com/polarismesh/polaris-sync/releases/download/${version}/polaris-sync-server-${version}.zip

unzip polaris-sync-server-${version}.zip

完成上述步骤之后，进入 polaris-sync-server-${version}/conf 目录，可以看到两个配置文件，这里只需要关注 sync-config.json

➜  conf tree
.
├── sync-config.json      # 配置同步任务配置文件
└── sync-registry.json   # 服务同步任务配置文件

sync-config.json 配置

sync-config.json 是服务同步任务的配置文件，polaris-sync 启动之后会自动加载该配置文件，从中获取服务数据同步任务配置信息，并根据该信息创建对应的服务同步任务执行。

sync-config.json 配置文件的格式是 json，其配置内容主要由以下四个对象组成

tasks: 数组形式，定义的服务数据同步任务信息，即设置服务数据从那个源注册中心同步到目标注册中心
methods: 数组形式，定义服务数据同步的方式，当前支持 PULL 模式以及 WATCH 模式
health_check: 对象形式，定义是否需要对源注册中心以及目标注册中心进行健康检查，探测注册中心是否存活
report: 对象形式，定义 polaris-sync 在同步过程中产生的指标数据上报的目标位置

这里我们对 tasks 配置参数解析

参数 key	类型	名称	示例｜
name	string	同步任务 ID，唯一标识	nacos-to-polaris
enable	bool	同步任务是否开启	true
source	object	源配置中心信息	NULL
source.name	string	源注册中心实例别名	nacos
source.type	string	注册中心类型	nacos
source.server	object	源配置中心服务端信息	NULL
source.server.addresses	[]string	注册中心接入地址	[“127.0.0.1:8848”]
source.server.user	string	注册中心用户信息	nacos
source.server.password	string	注册中心用户密码信息	nacos
source.server.token	string	注册中心用户访问凭据 token	token-123
source.db	object	源配置中心数据库信息	NULL
source.db.jdbc_url	string	数据库 jdbc 信息	jdbc:mysql://127.0.0.1:3306/nacos
source.db.username	string	数据库账户	nacos
source.db.password	string	配置数据库账户密码	nacos
destination	object	目标配置中心信息	NULL
destination.name	string	目标配置中心实例别名	nacos
destination.type	string	目标配置中心类型	nacos
destination.server	object	目标配置中心服务端信息	NULL
destination.server.addresses	[]string	目标配置中心接入地址	[“127.0.0.1:8848”]
destination.server.user	string	目标配置中心用户信息	nacos
destination.server.password	string	目标配置中心用户密码信息	nacos
destination.server.token	string	目标配置中心用户访问凭据 token	token-123
destination.db	object	目标配置中心数据库信息	NULL
destination.db.jdbc_url	string	数据库 jdbc 信息	jdbc:mysql://127.0.0.1:3306/nacos
destination.db.username	string	数据库账户	nacos
destination.db.password	string	配置数据库账户密码	nacos
match	[]object	设置待同步的配置数据匹配规则	[{}]
match[${index}].namespace	string	待同步的服务命名空间的	namespace
match[${index}].config_group	string	待同步的配置分组	config_group

这里你可以参考 sync-config.json 的样例配置，根据你的实际情况进行调整 tasks 对象即可，examples/sync-config.json

说明：

nacos 默认命名空间下的配置数据，将同步到 polaris 中名称为 default 的命名空间
当 nacos 为配置数据同步的目标注册中心时，如果 nacos 开启了鉴权，则必须配置 nacos 的 admin 账户，因为在同步服务时，polaris-sync 会主动的在 nacos 创建对应的命名空间以完成服务同步任务。

启动 polaris-sync

完成 sync-config.json 的配置之后，启动 polaris-sync 执行配置数据同步

➜ cd polaris-sync-server-0.3.0-beta

➜ bash bin/start.sh

验证

启动 polaris-sync 之后，查看日志 loggers/polaris-sync.log 观察到有以下日志则同步任务正常运行

[Polaris] success to send post http://127.0.0.1:8090/config/v1/configfiles/release, method POST

登陆 nacos 控制台以及 polaris 控制台，查看配置是否同步到了 Polaris，以及在 Nacos 新增配置后，在 Polaris 控制台也能够实时看到。

何时结束

当你的所有应用均默认从 Polaris 拉取配置后，则可以关闭 polaris-sync 进程结束配置数据同步，然后便可以关停 Nacos 服务。至此完成配置数据从 Nacos 迁移至 Polaris。

2.3 - 服务迁移

概述

如果你希望使用 Polaris 代替 Nacos 作为新的注册中心，Polaris 提供了两种服务迁移的方式

polaris-sync方案：提供server-to-server的迁移方式，支持多语言应用的迁移，需额外部署polaris-sync迁移工具
双注册双发现方案：提供JavaAgent的迁移方式，用户代码无感的方式完成服务迁移，仅支持Java应用，无需额外部署polaris-sync迁移工具

在执行服务数据从一个注册中心迁移至另一个注册中心的过程中，往往需要双向访问：

迁移到新注册中心的服务，需要访问未迁移的服务。
未迁移至新注册中心的服务，需要访问已迁移的服务。

当前 Polaris 提供的两种服务迁移方式均能够满足该要求，接下来你可以通过以下内容了解如何通过服务数据同步或者多注册多发现进行服务迁移。

准备Polaris服务端

需要预先安装好Polaris服务端，安装方式可参考：集群版安装

服务数据同步

polaris-sync 提供server-to-server的迁移方式，支持 Nacos 和 Polaris 进行服务数据双向同步。你可以按照以下步骤编写 polaris-sync 服务迁移的任务配置。从而实现将服务数据从 Nacos 平稳的迁移至 Polaris。

准备 polaris-sync

说明：

polaris-sync 是基于 Java 编写的程序，如果你希望在 VM 上运行 polaris-sync，则需要在 VM 上安装相关 Java 运行环境。

Java 版本最低要求 JDK8

需要下载 polaris-sync 的最新 release 版本：下载地址。

下载完之后，将 polaris-sync-server-${version}.zip 进行解压

wget https://github.com/polarismesh/polaris-sync/releases/download/${version}/polaris-sync-server-${version}.zip

unzip polaris-sync-server-${version}.zip

完成上述步骤之后，进入 polaris-sync-server-${version}/conf 目录，可以看到两个配置文件，这里只需要关注 sync-registry.json

➜  conf tree
.
├── sync-config.json
└── sync-registry.json

sync-registry.json 配置

sync-registry.json 是服务同步任务的配置文件，polaris-sync 启动之后会自动加载该配置文件，从中获取服务数据同步任务配置信息，并根据该信息创建对应的服务同步任务执行。

sync-registry.json 配置文件的格式是 json，其配置内容主要由以下四个对象组成

tasks: 数组形式，定义的服务数据同步任务信息，即设置服务数据从那个源注册中心同步到目标注册中心
methods: 数组形式，定义服务数据同步的方式，当前支持 PULL 模式以及 WATCH 模式
health_check: 对象形式，定义是否需要对源注册中心以及目标注册中心进行健康检查，探测注册中心是否存活
report: 对象形式，定义 polaris-sync 在同步过程中产生的指标数据上报的目标位置

这里我们对 tasks 配置参数解析

参数 key	类型	名称	示例｜
name	string	同步任务 ID，唯一标识	nacos-to-polaris
enable	bool	同步任务是否开启	true
source	object	源注册中心信息	NULL
source.name	string	源注册中心实例别名	nacos
source.type	string	注册中心类型	nacos
source.addresses	[]string	注册中心接入地址	[“127.0.0.1:8848”]
source.user	string	注册中心用户信息	nacos
source.password	string	注册中心用户密码信息	nacos
source.token	string	注册中心用户访问凭据 token	token-123
destination	object	目标注册中心信息	NULL
destination.name	string	目标注册中心实例别名	nacos
destination.type	string	注册中心类型	nacos
destination.addresses	[]string	目标注册中心接入地址	[“127.0.0.1:8848”]
destination.user	string	目标注册中心用户信息	nacos
destination.password	string	目标注册中心用户密码信息	nacos
destination.token	string	目标注册中心用户访问凭据 token	token-123
match	[]object	设置待同步的服务数据匹配规则	[{}]
match[${index}].namespace	string	待同步的服务命名空间的	namespace
match[${index}].service	string	待同步的服务名称	service

这里你可以参考 sync-registry.json 的样例配置，根据你的实际情况进行调整 tasks 对象即可，examples/sync-registry.json

说明：

nacos 默认命名空间下的服务数据，将同步到 polaris 中名称为 default 的命名空间
当 nacos 为服务数据同步的目标注册中心时，如果 nacos 开启了鉴权，则必须配置 nacos 的 admin 账户，因为在同步服务时，polaris-sync 会主动的在 nacos 创建对应的命名空间以完成服务同步任务。

启动 polaris-sync

完成 sync-registry.json 的配置之后，启动 polaris-sync 执行服务数据同步

➜ cd polaris-sync-server-0.3.0-beta

➜ bash bin/start.sh

验证

启动 polaris-sync 之后，查看日志 loggers/polaris-sync.log 观察到有以下日志则同步任务正常运行

[LOG] success to watch for service cn.polarismesh.polaris.sync.core.tasks.
[Core][Pull]prepare to update from registry source-nacos, type NACOS, service service='nacos.test.3'}, group default, instances []
[Core][Watch]prepare to update service Service{namespace='default',  default instances []
[Core][Watch]prepare to update service Service{namespace='default',  default instances []
[Polaris] service not found to discover service Service='nacos.test.3'} to http://127.0.0.1:8090/v1/Discover
[Polaris] service not found to discover service Service{namespace='default', service='nacos.test.3'} to http://127.0.0.1:8090/v1/Discover

登陆 nacos 控制台以及 polaris 控制台，查看服务以及服务下的实例是否同步成功，实例能够稳定维持健康状态。

何时结束

当你的所有应用均默认注册到 Polaris 之后，则可以关闭 polaris-sync 进程结束服务数据同步，然后便可以关停 Nacos 服务。至此完成服务数据从 Nacos 迁移至 Polaris。

多注册多发现

Polaris 提供 JavaAgent 的迁移方式，无需额外部署 polaris-sync 迁移工具，仅支持 Java 应用的迁移

准备 polaris-java-agent

说明： polaris-java-agent 目前仅支持 Spring Cloud 以及 Dubbo

需要下载 polaris-java-agent 的最新 release 版本：下载地址。

下载完之后，将 polaris-sync-server-${version}.zip 进行解压

wget https://github.com/polarismesh/polaris-java-agent/releases/download/${version}/polaris-java-agent-${version}.zip

unzip polaris-java-agent-${version}.zip

完成上述步骤之后，进入 polaris-java-agent-${version} 目录，先看下目录结构

➜  polaris-java-agent-1.3.0-beta tree
.
├── conf
│   └── plugin
│       └── springcloud2021
│           └── application.properties           # Spring Cloud Java Agent 的插件配置
├── plugins
│   └── spring-cloud-2021-plugin-1.3.0-beta.jar  # Spring Cloud 2021 的 Java Agent 插件支持
└── polaris-agent-core-bootstrap.jar			 # Polaris Java Agent 主程序

编辑 application.properties

# 配置服务名称
spring.application.name=${服务名称信息}
# 开启 polaris java agent 的服务注册发现能力
spring.cloud.discovery.enabled=true
# 设置北极星注册中心地址
spring.cloud.polaris.address=grpc\://127.0.0.1\:8091
# 设置注册的命名空间信息
#  注意：
#   1. 如果需要开启多注册能力，需要确保已经在 Polaris 上创建了原本应用在 Nacos 的命名空间
#   2. 北极星的默认命名空间 default 等同于 nacos 的默认命名空间
spring.cloud.polaris.namespace=default
# 开启双注册双发现到 nacos
spring.cloud.nacos.enabled=true
# 设置 nacos 服务注册中心的地址
spring.cloud.nacos.discovery.server-addr=127.0.0.1\:8848
# 设置 nacos 的账户信息
spring.cloud.nacos.username=nacos
spring.cloud.nacos.password=nacos
# 是否开启从 nacos 拉取服务实例信息
spring.cloud.nacos.discovery.enabled=true
# 是否开启将服务注册到 nacos
spring.cloud.nacos.discovery.register=true

重启业务进程

重启业务进程时，需要设置 -javaagent 参数指定为 Polaris Java Agent 才能启用多注册多发现能力。

java -javaagent:xxx/polaris-agent-core-bootstrap.jar -jar {你的 Java 程序名称}.jar

验证

登陆 nacos 控制台以及 polaris 控制台，查看业务进程是否同时注册到 Nacos 以及 Polaris，并且实例均处于健康状态。

何时结束

当你的所有应用均通过 Polaris Java Agent 完成双注册双发现之后，可以通过调整 application.properties，设置 spring.cloud.nacos.enabled=false 禁止注册到 Nacos，或者调整业务进程逻辑使得默认注册到 Polaris，再逐步重启相关业务进程即可。