最佳实践

• 1: 灰度发布
• 1.1: 蓝绿发布
• 1.2: 金丝雀发布
• 1.3: 全链路灰度-场景1
• 1.4: 全链路灰度-场景2
• 2: 测试环境路由
• 2.1: 概述
• 2.2: 客户端染色
• 2.3: 网关动态染色
• 2.4: 网关静态染色
• 3: K8s 相关实践
• 3.1: 跨集群服务注册
• 4: 存量服务迁移
• 4.1: Eureka 迁移方案
• 4.2: Nacos 迁移方案
• 4.2.1: 协议兼容（推荐）
• 4.2.2: 配置迁移
• 4.2.3: 服务迁移

1 - 灰度发布

1.1 - 蓝绿发布

什么是蓝绿发布

蓝绿部署是一种应用发布模式，可将用户流量从先前版本的应用或微服务全量转移到新版本中（两者均保持在生产环境中运行）。

旧版本可以称为蓝色环境，而新版本则可称为绿色环境。一旦生产流量从蓝色完全转移到绿色，蓝色就可以在回滚或退出生产的情况下保持待机，也可以更新成为下次更新的模板。

蓝绿发布的适用场景

• 机器资源有富余或者可以按需分配
• 单体应用、调用复杂度不高的业务系统
• 对用户体验具备一定的容忍度

北极星如何支持蓝绿发布

蓝绿发布需要依赖几个关键的技术点：

• 流量入口侧需要支持按百分比进行流量切换，并对灰度流量进行染色（打上灰度标签）。
• 微服务框架需要支持灰度标签的透传。
• 服务治理中心支持灰度流量只路由到灰度版本的服务中，非灰度流量只路由到原版本服务中 。

北极星提供以下功能，支持蓝绿发布：

• 网关直通微服务：北极星支持直接打通网关到微服务的链路（支持主流网关Envoy/Kong/Nginx/Spring Cloud Gateway），网关侧可以直接将流量打通到微服务的节点/POD，无需通过ClusterIP来中转。
• 提供自定义路由能力，支持流量按标签（版本等）进行路由。
• 微服务框架SpringCloudTencent，以及流量代理Envoy支持流量标签透传能力。

北极星支持Spring Cloud Tencent以及服务网格（Envoy）的方式接入使用蓝绿发布的能力。

前置条件

部署polaris

如果已经部署好了polaris，可忽略这一步。

polaris支持在kubernetes环境中进行部署，注意必须保证暴露HTTP端口为8090，gRPC端口为8091。具体部署方案请参考：

• 单机版部署指南
• 集群版部署指南

阶段一：实例打标

Spring Cloud Tencent 接入

打标实例版本号

Spring Cloud Tencent支持通过以下2种方式进行实例的版本号打标：

• 方式一：配置文件

在服务实例的配置文件中添加配置，如在 bootstrap.yml 添加如下所示即可：

spring:
  cloud:
    tencent:
      metadata:
        content:
          version: 2.0.0

• 方式二：环境变量

在服务实例所在的操作系统中添加环境变量也可进行打标，例如：SCT_METADATA_CONTENT_version=2.0.0 。

打标灰度标签透传

由于Spring Cloud默认不会对所有的请求标签进行透传，因此需要增加Spring Cloud透传标识，可以通过添加环境变量SCT_PROTOCOL_CONTENT_TRANSITIVE_HEADER=gray的方式，进行灰度标识gray:true的透传。

Envoy Proxy 接入

应用需要基于K8S进行部署，才可以使用Envoy Proxy的接入模式。

实例的版本标签需要通过POD标签的方式打入，然后在部署过程中，北极星的controller会自动把POD标签同步到北极星。

可以在K8S的部署配置中，在template配置中，添加labels的方式完成版本打标。可参考这里的部署配置：微服务部署配置

spec:
  template:
    metadata:
      labels:
        app: user
        version: 2.0.0

阶段二：部署应用

Spring Cloud Tencent 接入

支持虚拟机、Docker Composer、K8S等多种部署模式，注意需要保证业务进程与北极星服务的网络连通性。

Envoy Proxy 接入

只支持K8S的部署模式，同时，为了实现POD标签的自动同步，以及Envoy Proxy的自动注入，需要预先部署K8s Controller组件。具体部署方案请参考：

• k8s-controller部署指南

阶段三：网关路由&染色

网关作为流量入口，配置网关路由的目标主要是为了可以将流量按比例进行切分到不同版本的微服务中去，同时通过流量打标的方式，将路由到新版本的请求，在Header上打入gray:true的标签，便于后续微服务按照标签进行路由。

用户可以使用任意对接了北极星服务发现的网关进行操作（Envoy, Nginx, Kong等），这里给出Envoy的VirtualHost路由配置，便于大家理解，具体配置可以参考LDS配置

virtual_hosts:
- name: local_service
domains:
- "*"
routes:              
- match:
	prefix: "/"
  route:
	weighted_clusters:
	  total_weight: 100
	  clusters:
	  - name: user
		weight: 80
		metadata_match:
		  filter_metadata:
			envoy.lb:
			  version: 1.0.0
	  - name: user
		weight: 20
		request_headers_to_add:
		- header:
			key: gray
			value: "true"
		metadata_match:
		  filter_metadata:
			envoy.lb:
			  version: 2.0.0   

阶段四：微服务路由

通过配置微服务路由，目标是使得对于灰度流量的调用，都只在新版本的服务分组中进行。

打开北极星控制台，通过点击侧边栏：动态路由->自定义规则页面，配置自定义路由规则，规则可配置对命名空间下全部服务生效。

• 配置灰度规则，使得header中带有gray:true灰度标签的流量都只流向version=2.0.0的分组：

• 配置兜底规则，使得不带灰度标签的流量都只流向version=1.0.0的分组：

阶段五：观察监控并查看流量的灰度过程

通过北极星的可观测性能力，可以准确看到不同分组的流量切换的过程，以及服务调用成功率，等到所有流量都切换到新版本分组以及没有失败请求，代表灰度完成。

阶段六：灰度完成的收尾动作

灰度完成后，需要做以下事情：

• 对老版本分组的实例进行缩容下线
• 删除网关的路由规则
• 在北极星控制台删除自定义路由规则

一键部署体验

北极星提供了一键部署demo，可以通过一键部署demo快速体验蓝绿发布。详细请参考：

• Spring Cloud Tencent
• Envoy Proxy

1.2 - 金丝雀发布

什么是金丝雀发布

金丝雀发布是已经将新版本应用部署到生产环境了，然后根据一定的特征，一般是用户ID、用户地域、用户类型等不同维度，允许部分用户使用部署到生产环境上的新版本应用。这个过程中，通过观察新版本的表现（比如成功率、时延、负载等），以判断新版本是否符合预期。

金丝雀发布的适用场景

• 用户体验不能中断的业务
• 微服务业务的独立服务的特性变更

北极星如何支持金丝雀发布

金丝雀发布需要依赖几个关键的技术点：

• 微服务框架需要支持灰度标签的透传。
• 服务治理中心支持将灰度用户的流量只路由到灰度版本的服务中，其他流量只路由到原版本服务中 。

北极星提供以下功能，支持金丝雀发布：

• 提供自定义路由能力，支持流量按标签（版本等）进行路由。
• 微服务框架SpringCloudTencent，以及流量代理Envoy支持流量标签透传能力。

北极星支持Spring Cloud Tencent以及服务网格（Envoy）的方式接入使用金丝雀发布的能力。

前置条件

部署polaris

如果已经部署好了polaris，可忽略这一步。

polaris支持在kubernetes环境中进行部署，注意必须保证暴露HTTP端口为8090，gRPC端口为8091。具体部署方案请参考：

• 单机版部署指南
• 集群版部署指南

阶段一：实例打标

Spring Cloud Tencent 接入

打标实例版本号

Spring Cloud Tencent支持通过以下2种方式进行实例的版本号打标：

• 方式一：配置文件

在服务实例的配置文件中添加配置，如在 bootstrap.yml 添加如下所示即可：

spring:
  cloud:
    tencent:
      metadata:
        content:
          version: 2.0.0

• 方式二：环境变量

在服务实例所在的操作系统中添加环境变量也可进行打标，例如：SCT_METADATA_CONTENT_version=2.0.0 。

打标灰度标签透传

由于Spring Cloud默认不会对所有的请求标签进行透传，因此需要增加Spring Cloud透传标识，可以通过添加环境变量SCT_PROTOCOL_CONTENT_TRANSITIVE_HEADER=gray的方式，进行灰度标识gray:true的透传。

Envoy Proxy 接入

应用需要基于K8S进行部署，才可以使用Envoy Proxy的接入模式。

实例的版本标签需要通过POD标签的方式打入，然后在部署过程中，北极星的controller会自动把POD标签同步到北极星。

可以在K8S的部署配置中，在template配置中，添加labels的方式完成版本打标。可参考这里的部署配置：微服务部署配置

spec:
  template:
    metadata:
      labels:
        app: user
        version: 2.0.0

阶段二：部署应用

Spring Cloud Tencent 接入

支持虚拟机、Docker Composer、K8S等多种部署模式，注意需要保证业务进程与北极星服务的网络连通性。

Envoy Proxy 接入

只支持K8S的部署模式，同时，为了实现POD标签的自动同步，以及Envoy Proxy的自动注入，需要预先部署北极星的Controller组件（polaris-controller）。具体部署方案请参考：

• polaris-controller部署指南

阶段三：微服务路由

通过配置微服务路由，目标是使得对于灰度流量的调用，都只在新版本的服务分组中进行。

打开北极星控制台，通过点击侧边栏：动态路由->自定义规则页面，配置自定义路由规则，规则只对credit服务生效。

• 配置灰度规则，使得header中带有gray:true灰度标签的流量都只流向version=2.0.0的分组：

• 配置兜底规则，使得不带灰度标签的流量都流向其他版本分组：

阶段四：观察监控并查看流量的灰度过程

通过北极星的可观测性能力，可以准确看到不同分组的流量切换的过程，以及服务调用成功率，等到灰度分组相关指标没有问题，代表灰度验证完成。

阶段五：灰度完成的收尾动作

灰度验证完成后，需要做以下事情：

• 对老版本分组的实例进行滚动升级到新版本
• 在北极星控制台删除自定义路由规则

一键部署体验

北极星提供了一键部署demo，可以通过一键部署demo快速体验蓝绿发布。详细请参考：

• Spring Cloud Tencent
• Envoy Proxy

1.3 - 全链路灰度-场景1

什么是全链路灰度

微服务架构下，有些开发需求，微服务调用链路上的多个微服务同时发生了改动，通常每个微服务都会有灰度环境或分组来接收灰度流量。此时希望通过进入上游灰度环境的流量，也能进入下游灰度的环境中，确保1个请求始终在灰度环境中传递。

全链路灰度适用场景

• 用户体验不能中断的业务。
• 微服务业务的存在关联关系的多个微服务的特性变更。

全链路灰度的实现方案

可以基于域名分离的方式实现全链路灰度，通过不同的域名区分灰度环境和稳定环境。用户的请求通过灰度域名访问到灰度版本的服务，通过稳定域名访问到稳定版本的服务。

灰度请求通过灰度域名接入到网关，网关通过域名识别到灰度请求后，将请求优先路由到灰度版本的服务，并通过请求头的方式进行灰度染色。后续微服务之间，服务框架通过请求头识别到灰度请求，会优先将请求路由到灰度版本服务，如果寻址不到灰度版本，则路由到稳定版本服务。

前置条件

部署polaris

如果已经部署好了polaris，可忽略这一步。

polaris支持在kubernetes环境中进行部署，注意必须保证暴露HTTP端口为8090，gRPC端口为8091。具体部署方案请参考：

• 单机版部署指南
• 集群版部署指南

阶段一：实例打标

Spring Cloud Tencent 接入

打标实例版本号

Spring Cloud Tencent支持通过以下2种方式进行实例的版本号打标：

• 方式一：配置文件

在服务实例的配置文件中添加配置，如在 bootstrap.yml 添加如下所示即可：

spring:
  cloud:
    tencent:
      metadata:
        content:
          version: 2.0.0

• 方式二：环境变量

在服务实例所在的操作系统中添加环境变量也可进行打标，例如：SCT_METADATA_CONTENT_version=2.0.0 。

打标灰度标签透传

由于Spring Cloud默认不会对所有的请求标签进行透传，因此需要增加Spring Cloud透传标识，可以通过添加环境变量SCT_TRAFFIC_CONTENT_RAW_TRANSHEADERS=gray的方式，进行灰度标识gray:true的透传。

Envoy Proxy 接入

应用需要基于K8S进行部署，才可以使用Envoy Proxy的接入模式。

实例的版本标签需要通过POD标签的方式打入，然后在部署过程中，北极星的controller会自动把POD标签同步到北极星。

可以在K8S的部署配置中，在template配置中，添加labels的方式完成版本打标。可参考这里的部署配置：微服务部署配置

spec:
  template:
    metadata:
      labels:
        app: user
        version: 2.0.0

阶段二：部署应用

Spring Cloud Tencent 接入

支持虚拟机、Docker Composer、K8S等多种部署模式，注意需要保证业务进程与北极星服务的网络连通性。

Envoy Proxy 接入

只支持K8S的部署模式，同时，为了实现POD标签的自动同步，以及Envoy Proxy的自动注入，需要预先部署北极星的Controller组件（polaris-controller）。具体部署方案请参考：

• polaris-controller部署指南

阶段三：网关路由&染色

网关作为流量入口，配置网关路由的目标主要是为了可以将通过灰度域名接入的流量，导入到灰度版本的下游微服务上，同时通过流量打标的方式，将路由到灰度版本的请求，在Header上打入gray:true的标签，便于后续微服务按照标签进行路由。

配置域名切流量的规则

用户可以使用任意对接了北极星服务发现的网关进行操作（Envoy, Nginx, Kong等），这里给出Envoy的VirtualHost路由配置，便于大家理解，具体配置可以参考LDS配置

virtual_hosts:
- name: local_service
  domains:
  - "*"
  routes:              
  - match:
	  prefix: "/"
    route:
	  weighted_clusters:
	    total_weight: 100
	    clusters:
	    - name: user
		  weight: 80
		  metadata_match:
		    filter_metadata:
			  envoy.lb:
			    version: 1.0.0
	    - name: user
		  weight: 20
		  request_headers_to_add:
		  - header:
			  key: gray
			  value: "true"
		  metadata_match:
		    filter_metadata:
			  envoy.lb:
			    version: 2.0.0

阶段四：微服务路由

通过配置微服务路由，目标是使得对于灰度流量的调用，都只在新版本的服务分组中进行。

打开北极星控制台，通过点击侧边栏：动态路由->自定义规则页面，配置自定义路由规则，规则可配置对命名空间下全部服务生效。

• 配置灰度规则，使得header中带有gray:true灰度标签的流量都只流向version=2.0.0的分组：

• 配置兜底规则，使得不带灰度标签的流量都只流向version=1.0.0的分组：

阶段五：观察监控并查看流量的灰度过程

通过北极星的可观测性能力，可以准确看到不同分组的流量切换的过程，以及服务调用成功率，等到所有流量都切换到新版本分组以及没有失败请求，代表灰度完成。

阶段六：灰度完成的收尾动作

灰度完成后，需要做以下事情：

• 对老版本分组的实例进行缩容下线
• 删除网关的路由规则
• 在北极星控制台删除自定义路由规则

一键部署体验

北极星提供了一键部署demo，可以通过一键部署demo快速体验蓝绿发布。详细请参考：

• Spring Cloud Tencent
• Envoy Proxy

1.4 - 全链路灰度-场景2

什么是全链路灰度

微服务架构下，有些开发需求，微服务调用链路上的多个微服务同时发生了改动，通常每个微服务都会有灰度环境或分组来接收灰度流量。此时希望通过进入上游灰度环境的流量，也能进入下游灰度的环境中，确保1个请求始终在灰度环境中传递。

全链路灰度适用场景

• 用户体验不能中断的业务。
• 微服务业务的存在关联关系的多个微服务的特性变更。

全链路灰度的实现方案

灰度环境和稳定环境对外只暴露一个域名，系统基于特定的请求标识（UID等）识别到灰度请求，并将灰度请求优化路由到灰度环境。

针对UID=2000的请求进行灰度，灰度请求接入到网关后，网关通过特定UID识别到灰度请求后，将请求优先路由到灰度版本的服务，并将UID透传到下一跳服务中。后续微服务之间，服务框架通过UID识别到灰度请求，会优先将请求路由到灰度版本服务，如果寻址不到灰度版本，则路由到稳定版本服务，UID的请求头会随着微服务调用每一级进行透传。

前置条件

部署polaris

如果已经部署好了polaris，可忽略这一步。

polaris支持在kubernetes环境中进行部署，注意必须保证暴露HTTP端口为8090，gRPC端口为8091。具体部署方案请参考：

• 单机版部署指南
• 集群版部署指南

阶段一：实例打标

Spring Cloud Tencent 接入

打标实例版本号

Spring Cloud Tencent支持通过以下2种方式进行实例的版本号打标：

• 方式一：配置文件

在服务实例的配置文件中添加配置，如在 bootstrap.yml 添加如下所示即可：

spring:
  cloud:
    tencent:
      metadata:
        content:
          version: 2.0.0

• 方式二：环境变量

在服务实例所在的操作系统中添加环境变量也可进行打标，例如：SCT_METADATA_CONTENT_version=2.0.0 。

打标灰度标签透传

由于Spring Cloud默认不会对所有的请求标签进行透传，因此需要增加Spring Cloud透传标识，可以通过添加环境变量SCT_TRAFFIC_CONTENT_RAW_TRANSHEADERS=uid的方式，进行灰度标识uid:200的透传。

Envoy Proxy 接入

应用需要基于K8S进行部署，才可以使用Envoy Proxy的接入模式。

实例的版本标签需要通过POD标签的方式打入，然后在部署过程中，北极星的controller会自动把POD标签同步到北极星。

可以在K8S的部署配置中，在template配置中，添加labels的方式完成版本打标。可参考这里的部署配置：微服务部署配置

spec:
  template:
    metadata:
      labels:
        app: user
        version: 2.0.0

阶段二：部署应用

Spring Cloud Tencent 接入

支持虚拟机、Docker Composer、K8S等多种部署模式，注意需要保证业务进程与北极星服务的网络连通性。

Envoy Proxy 接入

只支持K8S的部署模式，同时，为了实现POD标签的自动同步，以及Envoy Proxy的自动注入，需要预先部署北极星的Controller组件（polaris-controller）。具体部署方案请参考：

• polaris-controller部署指南

阶段三：网关路由&染色

网关作为流量入口，配置网关路由的目标主要是为了可以将灰度用户的请求，路由灰度版本的微服务中去。

按标签切流量

用户可以使用任意对接了北极星服务发现的网关进行操作（Envoy, Nginx, Kong等），这里给出Envoy的VirtualHost路由配置，便于大家理解，具体配置可以参考LDS配置

virtual_hosts:
- name: gray_service
  domains:
	- base.service.com
  routes:
	- match:
		prefix: /
		headers:
		  - name: uid
			exact_match: '200'
	  route:
		cluster: user
		metadata_match:
		  filter_metadata:
			envoy.lb:
			  version: v2.0.0
	  request_headers_to_add:
		- header:
			key: gray
			value: 'true'
	- match:
		prefix: /
	  route:
		cluster: user
		metadata_match:
		  filter_metadata:
			envoy.lb:
			  version: v1.0.0     

阶段四：微服务路由

通过配置微服务路由，目标是使得对于灰度流量的调用，都只在新版本的服务分组中进行。

打开北极星控制台，通过点击侧边栏：动态路由->自定义规则页面，配置自定义路由规则，规则可配置对命名空间下全部服务生效。

• 配置灰度规则，使得header中带有uid:200灰度标签的流量都只流向version=2.0.0的分组：

• 配置兜底规则，使得不带灰度标签的流量都只流向version=1.0.0的分组：

阶段五：观察监控并查看流量的灰度过程

通过北极星的可观测性能力，可以准确看到不同分组的流量切换的过程，以及服务调用成功率，等到所有流量都切换到新版本分组以及没有失败请求，代表灰度完成。

阶段六：灰度完成的收尾动作

灰度完成后，需要做以下事情：

• 对老版本分组的实例进行缩容下线
• 删除网关的路由规则
• 在北极星控制台删除自定义路由规则

一键部署体验

北极星提供了一键部署demo，可以通过一键部署demo快速体验蓝绿发布。详细请参考：

• Spring Cloud Tencent
• Envoy Proxy

2 - 测试环境路由

2.1 - 概述

背景介绍

在实际的开发过程中，一个微服务架构系统下的不同微服务可能是由多个团队进行开发与维护的，每个团队只需关注所属的一个或多个微服务，而各个团队维护的微服务之间可能存在相互调用关系。如果一个团队在开发其所属的微服务，调试的时候需要验证完整的微服务调用链路。此时需要依赖其他团队的微服务，如何部署开发联调环境就会遇到以下问题：

1. 如果所有团队都使用同一套开发联调环境，那么一个团队的测试微服务实例无法正常运行时，会影响其他依赖该微服务的应用也无法正常运行。
2. 如果每个团队有单独的一套开发联调环境，那么每个团队不仅需要维护自己环境的微服务应用，还需要维护其他团队环境的自身所属微服务应用，效率大大降低。同时，每个团队都需要部署完整的一套微服务架构应用，成本也随着团队数的增加而大大上升。

此时可以使用测试环境路由的架构来帮助部署一套运维简单且成本较低开发联调环境。

什么是测试环境路由

测试环境路由是一种基于服务路由的环境治理策略，核心是维护一个稳定的基线环境作为基础环境，测试环境仅需要部署需要变更的微服务以构成特性环境。部署完成多测试环境后，开发者可以通过一定的路由规则方式，将测试请求打到不同的测试环境，如果测试环境没有相应的微服务处理链路上的请求，那么会降级到基线环境处理。因此，开发者需要将开发新测试的微服务部署到对应的测试环境，而不需要更新或不属于开发者管理的微服务则复用基线环境的服务，完成对应测试环境的测试。

由此可见，多测试环境有两个基础概念，即基线环境和特性环境。

基础概念

基线环境

基线环境（Baseline Environment）是完整稳定的基础环境，是作为同类型下其他环境流量通路的一个兜底可用环境，用户应该尽量保证基线环境的完整性、稳定性。

测试环境

测试环境（Feature Environment）是一种临时环境，仅可能为开发/测试环境类型，测试环境不需要部署全链路完整的服务，而是仅部署本次有变更的服务，其他服务通过服务路由的方式复用基线环境服务资源。

实现原理

方案总览

测试环境路由的样例实现以下图为例，一共有两个测试环境以及一个基线环境。流量从端到端会依次经过以下组件：App -> 网关 -> 用户中心 -> 积分中心 -> 活动中心。

为了达到测试环境路由的能力，开发工作需要做三件事情：

1. 服务实例染色（标识实例属于哪个测试环境）
2. 流量染色（标识请求应该被转发到哪个测试环境）
3. 服务路由 a. 网关根据请求的目标测试环境标签转发到对应的目标测试环境的用户中心. b. 服务调用时，优先转发到同测试环境下的目标服务实例，如果同测试环境下没有服务实例则转发到基线环境.

以下三小节，将会详细介绍这三部分的原理。

服务实例染色

在多测试环境的场景中，需要对每个测试环境部署的实例进行区分，因此需要在实例上打类似于“featureenv=测试环境名”的标签，例如以下几种实践场景：

1. 应用实例的配置文件中表明其环境信息。
2. 把实例标签放到机器上的某一个配置文件里，例如 /etc/metadata。
3. 应用启动时，调用公司的 CMDB 接口获取元信息。

流量染色

流量染色即为每个请求打上目标测试环境标签，路由转发时根据请求标签匹配请求。而流量染色可以分为以下几种方式：

• 静态染色

静态染色所有经过当前实例的请求都带上当前实例的标签信息。例如经过 env=f1 的实例的请求都携带 env=f1 的标签信息。

• 动态染色

静态染色是把服务实例的某些标签作为请求标签，服务实例标签相对静态，应用启动后初始化一次之后就不再变更。但是在实际的应用场景下，不同的请求往往需要设置不同的标签信息。此时则需要通过动态染色的能力。因此需要按照一定的规则或逻辑，为每个请求动态生成标签信息。

元数据路由

北极星提供了非常完善的服务治理能力，上层的服务框架基于北极星原生 SDK 就能快速实现强大的服务治理能力。在多测试环境场景下主要用到了元数据路由插件，此插件核心能力是根据请求的标签完全匹配服务实例的标签。

操作指引

具体操作指引按照染色的方式，分为以下三种，可以跳转到对应的文档详细查看：

• 客户端染色
• 网关动态染色
• 网关静态染色

2.2 - 客户端染色

流程简介

如概述所言，测试环境路由的开发工作分为三个阶段：

• 阶段一：实例打标。在多测试环境的场景中，需要对每个测试环境部署的实例进行区分，因此需要在实例上打类似标识实例测试环境类别的标签。
• 阶段二：部署应用。
• 阶段三：流量染色。流量染色即为每个请求打上目标测试环境标签，路由转发时根据请求标签匹配请求。

如下图所示，开发者给每个环境的应用实例进行打标（如 featureenv=f1 ），标明其所在的环境类型。阶段二部署业务应用。阶段三中，开发者在请求头添加相应的流量标签，即可完成测试环境路由。

操作指引

阶段一

微服务框架服务注册场景

Spring Cloud Tencent 框架接入

Spring Cloud Tencent 中的 spring-cloud-tencent-featureenv-plugin 模块闭环了测试环境路由全部能力，所有服务只需要添加该依赖即可引入测试环境路由能力。spring-cloud-tencent-featureenv-plugin 默认以 featureenv 标签作为匹配标签，用户也可以通过系统内置的 system-feature-env-router-label=custom_feature_env_key 标签来指定测试环境路由使用的标签键。以下三种方式以默认的 featureenv 作为示例。设置方式详情参考Spring Cloud Tencent 元数据使用说明。

• 方式一：配置文件

在服务实例的配置文件中添加配置，如在 bootstrap.yml 添加如下所示即可：

spring:
  cloud:
    tencent:
      metadata:
        content:
          featureenv: f1  # f1 替换为测试环境名称

• 方式二：环境变量

在服务实例所在的操作系统中添加环境变量也可进行打标，例如：SCT_METADATA_CONTENT_featureenv=f1 。

• 方式三：SPI 方式 自定义实现 InstanceMetadataProvider#getMetadata() 方法的返回值里里包含 featureenv 即可。

注意：基线环境部署的服务实例不需要设置 featureenv 标签，表明其不属于任何测试环境，才可在请求没有匹配到对应测试环境的时候，匹配到基线环境。

kubernetes服务注册场景

北极星提供了polaris-controller，支持直接将pod labels同步为北极星上面的实例标签。

• 在集群中安装polaris-controller，安装方式可参考：安装指南
• 创建deployment的时候，通过template配置，指定pod的标签信息，详细参考：标签指定

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

做完上面2步后，polaris-controller默认会对集群中的服务数据进行全量同步，而pod中的labels也会同步为北极星的实例标签。

阶段二

在 VM 或者容器中部署业务应用，需要保证业务应用与北极星服务治理中心的网络连通性。

阶段三

开发者在客户端发出的 HTTP 请求里，新增 X-Polaris-Metadata-Transitive-featureenv=f1 请求头即可实现流量染色。

请求头 X-Polaris-Metadata-Transitive-featureenv=f1 是按照北极星定义的请求头格式设置的，其中 X-Polaris-Metadata-Transitive- 是北极星需要读取请求头的前缀，例子中的 featureenv 为实际的键值对的key，f1 为实际的键值对的value。

原理解析

• 标签筛选：用户传入的env=f1，spring cloud tencent会基于从北极星发现的实例数据，筛选出匹配env=f1的实例，并进行服务调用。

• 标签透传：在微服务的调用链路中，spring cloud tencent框架会将用户的请求标签逐级往下透传，使得每一层调用都可以优先调度都env=f1的实例上。

2.3 - 网关动态染色

流程简介

如概述所言，测试环境路由的开发工作分为三个阶段：

• 阶段一：实例打标。在多测试环境的场景中，需要对每个测试环境部署的实例进行区分，因此需要在实例上打类似标识实例测试环境类别的标签。
• 阶段二：部署应用。
• 阶段三：流量染色。流量染色即为每个请求打上目标测试环境标签，路由转发时根据请求标签匹配请求。

如下图所示，开发者给每个环境的应用实例进行打标（如 featureenv=f1 ），标明其所在的环境类型。阶段二部署业务应用。阶段三中，开发者在网关添加动态流量染色规则来给每个请求添加相应的流量标签，即可完成测试环境路由。

操作指引

阶段一

微服务框架服务注册场景

Spring Cloud Tencent 框架接入

Spring Cloud Tencent 中的 spring-cloud-tencent-featureenv-plugin 模块闭环了测试环境路由全部能力，所有服务只需要添加该依赖即可引入测试环境路由能力。spring-cloud-tencent-featureenv-plugin 默认以 featureenv 标签作为匹配标签，用户也可以通过系统内置的 system-feature-env-router-label=custom_feature_env_key 标签来指定测试环境路由使用的标签键。以下三种方式以默认的 featureenv 作为示例。设置方式详情参考Spring Cloud Tencent 元数据使用说明。

• 方式一：配置文件

在服务实例的配置文件中添加配置，如在 bootstrap.yml 添加如下所示即可：

spring:
  cloud:
    tencent:
      metadata:
        content:
          featureenv: f1  # f1 替换为测试环境名称

• 方式二：环境变量

在服务实例所在的操作系统中添加环境变量也可进行打标，例如：SCT_METADATA_CONTENT_featureenv=f1 。

• 方式三：SPI 方式 自定义实现 InstanceMetadataProvider#getMetadata() 方法的返回值里里包含 featureenv 即可。

注意：基线环境部署的服务实例不需要设置 featureenv 标签，表明其不属于任何测试环境，才可在请求没有匹配到对应测试环境的时候，匹配到基线环境。

kubernetes服务注册场景

北极星提供了polaris-controller，支持直接将pod labels同步为北极星上面的实例标签。

• 在集群中安装polaris-controller，安装方式可参考：安装指南
• 创建deployment的时候，通过template配置，指定pod的标签信息，详细参考：标签指定

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

做完上面2步后，polaris-controller默认会对集群中的服务数据进行全量同步，而pod中的labels也会同步为北极星的实例标签。

阶段二

在 VM 或者容器中部署业务应用，需要保证业务应用与北极星服务治理中心的网络连通性。

阶段三

网关动态染色是开发者配置一定的染色规则，让流量经过网关时自动染色。例如上图红框内所示，把 uid=1 用户的请求都转发到 f1 环境，把 uid=0 用户的请求都转发到 f2 环境。具体的流程是开发者在北极星的页面上添加类似如下图所示的染色规则，然后网关根据染色规则在 HTTP 请求里，新增 X-Polaris-Metadata-Transitive-featureenv=f1 请求头即可实现流量染色。

请求头 X-Polaris-Metadata-Transitive-featureenv=f1 是按照北极星定义的请求头格式设置的，其中 X-Polaris-Metadata-Transitive- 是北极星需要读取请求头的前缀，例子中的 featureenv 为实际的键值对的key，f1 为实际的键值对的value。

操作步骤：

1. 创建配置文件 rule/staining.json。

2. 编辑 rule/staining.json 并应用SCG染色模板(SCG染色模版将在1.11.0版本提供，目前仅支持自定义编写)。

3. 保存并发布，该规则配置将下发到对应的SCG应用，后续 HTTP 请求将按照规则进行染色，并根据染色标签路由到不同的测试环境，以实现测试环境路由。

模版里的样例配置的含义是，在 HTTP 请求的参数中拿到 uid 字段，如果等于（EQUAL） 10001，那么就在经过的 HTTP 请求的头部自动打上 X-Polaris-Metadata-Transitive-featureenv=feature1 的数据标签。更加详细的规则配置说明如下所示：

Spring Cloud Tencent 实现方式

Spring Cloud Tencent 通过实现 Spring Cloud Gateway 的 GlobalFilter 来实现流量染色插件，开发者只需要添加 spring-cloud-tencent-gateway-plugin 依赖，并在配置文件打开如下所示的染色插件开关即可引入流量染色能力。spring-cloud-tencent-gateway-plugin 插件会默认读取北极星配置中心内的 rule/staining.json 配置作为动态染色规则。

spring-cloud-tencent-gateway-plugin 配置列表：

2.4 - 网关静态染色

流程简介

如概述所言，测试环境路由的开发工作分为三个阶段：

• 阶段一：实例打标。在多测试环境的场景中，需要对每个测试环境部署的实例进行区分，因此需要在实例上打类似标识实例测试环境类别的标签。
• 阶段二：部署应用。
• 阶段三：流量染色。流量染色即为每个请求打上目标测试环境标签，路由转发时根据请求标签匹配请求。

如下图所示，开发者给每个环境的应用实例进行打标（如 featureenv=f1 ），标明其所在的环境类型。阶段二部署业务应用。阶段三中，开发者在各个环境的网关添加向请求头插入流量标签的插件，即可完成测试环境路由。

操作指引

阶段一

微服务框架服务注册场景

Spring Cloud Tencent 框架接入

Spring Cloud Tencent 中的 spring-cloud-tencent-featureenv-plugin 模块闭环了测试环境路由全部能力，所有服务只需要添加该依赖即可引入测试环境路由能力。spring-cloud-tencent-featureenv-plugin 默认以 featureenv 标签作为匹配标签，用户也可以通过系统内置的 system-feature-env-router-label=custom_feature_env_key 标签来指定测试环境路由使用的标签键。以下三种方式以默认的 featureenv 作为示例。设置方式详情参考Spring Cloud Tencent 元数据使用说明。

• 方式一：配置文件

在服务实例的配置文件中添加配置，如在 bootstrap.yml 添加如下所示即可：

spring:
  cloud:
    tencent:
      metadata:
        content:
          featureenv: f1  # f1 替换为测试环境名称

• 方式二：环境变量

在服务实例所在的操作系统中添加环境变量也可进行打标，例如：SCT_METADATA_CONTENT_featureenv=f1 。

• 方式三：SPI 方式 自定义实现 InstanceMetadataProvider#getMetadata() 方法的返回值里里包含 featureenv 即可。

注意：基线环境部署的服务实例不需要设置 featureenv 标签，表明其不属于任何测试环境，才可在请求没有匹配到对应测试环境的时候，匹配到基线环境。

kubernetes服务注册场景

北极星提供了polaris-controller，支持直接将pod labels同步为北极星上面的实例标签。

• 在集群中安装polaris-controller，安装方式可参考：安装指南
• 创建deployment的时候，通过template配置，指定pod的标签信息，详细参考：标签指定

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

做完上面2步后，polaris-controller默认会对集群中的服务数据进行全量同步，而pod中的labels也会同步为北极星的实例标签。

阶段二

在 VM 或者容器中部署业务应用，需要保证业务应用与北极星服务治理中心的网络连通性。

阶段三

往请求中加入固定的 Header 是网关最常见的插件，如上图所示。可以在每个环境部署一个网关，所有经过网关的请求都增加 X-Polaris-Metadata-Transitive-featureenv=f1 请求头（其中，f1替换为对应的测试环境标签）即可。

请求头 X-Polaris-Metadata-Transitive-featureenv=f1 是按照北极星定义的请求头格式设置的，其中 X-Polaris-Metadata-Transitive- 是北极星需要读取请求头的前缀，例子中的 featureenv 为实际的键值对的key，f1 为实际的键值对的value。

Spring Cloud Tencent 静态染色

在 Spring Cloud 项目中，可以利用 Spring Cloud Gateway 提供的一些方式来帮助实现流量的静态染色，如下所示。所有经过该网关的流量，都在经过的 HTTP 请求的头部自动打上 X-Polaris-Metadata-Transitive-featureenv=f1 的数据标签。

1. 配置文件方式添加 HTTP 请求头部

开发者可以在配置文件中，为每一个需要进行流量染色的服务，添加 Spring Cloud Gateway 提供的内置 filter 规则来实现流量染色的 HTTP 请求头部的添加。

spring:
  cloud:
    gateway:
      routes:
      - id: add_request_header_route
        uri: lb://NAME_OF_SERVICE
        filters:
        - AddRequestHeader=X-Polaris-Metadata-Transitive-featureenv, f1

具体文档参考：The AddRequestHeader GatewayFilter Factory。

2. 代码方式添加 HTTP 请求头部

开发者也可以实现 Spring Cloud Gateway 提供的 GlobalFilter 接口，直接为所有经过网关应用的请求添加流量染色的 HTTP 请求头部。

@Component
public class CustomGlobalFilter implements GlobalFilter {
	@Override
	public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
		// get request builder
		ServerHttpRequest.Builder builder = exchange.getRequest().mutate();

		try {
			builder.header("X-Polaris-Metadata-Transitive-featureenv", URLEncoder.encode("f1", UTF_8));
		}
		catch (UnsupportedEncodingException e) {
			builder.header("X-Polaris-Metadata-Transitive-featureenv", "f1");
		}

		return chain.filter(exchange.mutate().request(builder.build()).build());
	}
}

3 - K8s 相关实践

3.1 - 跨集群服务注册

背景及架构

北极星支持对接多k8s集群，不同集群的服务注册同一个北极星服务端，可以实现多集群之间的直通POD负载均衡，可以解决使用K8S的CLUSTER IP负载均衡模式下会出现的长连接负载不均等问题。

北极星服务端只部署一套，不同的k8s集群中的POD，通过集群内的k8s controller，将POD信息同步到北极星，同时将集群名作为服务实例的标签注册上去，便于用户进行查找以及按集群就近路由。

部署k8s controller

k8s controller需要部署到k8s的集群中，可以参考以下文档进行部署：k8s controller部署指南

配置集群名

k8s controller默认会以default集群名进行部署，我们需要修改成实际的集群名。

• 修改配置文件集群名

打开polaris-controller的安装包（非源码包），找到configmap.yaml这个文件，并且在文件中，将clusterName的值修改成实际的集群名称

    # k8s集群名，需要修改成实际的集群名称
    clusterName: "default" 

修改完毕后，通过kubectl apply -f configmap.yaml，将配置重新发布。

• 重启controller

找到polaris-controller的部署路径，一般在polaris-system命名空间下，将controller的POD重启

• 观察北极星控制台

打开北极星控制台，找到对应通过的服务名，进入实例列表，确认POD IP是否已经带入clusterName的标签信息。

4 - 存量服务迁移

4.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下面进行配置：

*** 往北极星服务端添加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的标签。

4.2 - Nacos 迁移方案

4.2.1 - 协议兼容（推荐）

概述

如果你希望使用 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-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-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

4.2.2 - 配置迁移

概述

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

准备Polaris服务端

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

准备 polaris-sync

需要下载 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 配置参数解析

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

启动 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。

4.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 的最新 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 配置参数解析

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

启动 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 的最新 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，再逐步重启相关业务进程即可。