文档

• 1: 北极星是什么
• 1.1: 简介
• 1.2: 功能特性
• 1.2.1: 服务管理
• 1.2.2: 流量管理
• 1.2.3: 熔断降级
• 1.2.4: 配置管理
• 1.3: 接入方式
• 1.3.1: 使用 SDK
• 1.3.2: 使用开发框架
• 1.3.3: 使用 Java Agent
• 1.3.4: 使用 K8s 和网格代理
• 2: 使用指南
• 2.1: 服务端安装
• 2.1.1: 单机版安装
• 2.1.2: 集群版安装
• 2.2: 控制台使用
• 2.2.1: 命名空间
• 2.2.2: 注册中心
• 2.2.2.1: 服务列表
• 2.2.2.2: 服务可见性
• 2.2.3: 服务网格
• 2.2.3.1: 动态路由
• 2.2.3.2: 就近路由
• 2.2.3.3: 访问限流
• 2.2.3.4: 熔断降级
• 2.2.4: 配置中心
• 2.2.4.1: 配置分组
• 2.2.4.2: 配置导入导出
• 2.2.4.3: 配置加密
• 2.2.4.4: 配置灰度
• 2.2.5: 权限控制
• 2.2.5.1: 概述
• 2.2.5.2: 策略
• 2.3: Java 应用开发
• 2.3.1: 使用 Java SDK
• 2.3.1.1: 注册发现
• 2.3.1.2: 动态路由
• 2.3.1.3: 负载均衡
• 2.3.1.4: 熔断降级
• 2.3.1.5: 访问限流
• 2.3.1.6: 配置管理
• 2.3.1.7: 可观测性
• 2.3.1.8: 二次寻址
• 2.3.2: 使用 Spring Cloud
• 2.3.3: 使用 Spring Boot
• 2.3.3.1: 概述
• 2.3.3.2: 服务注册
• 2.3.3.3: 服务发现
• 2.3.4: 使用 Dubbo
• 2.3.4.1: 服务注册
• 2.3.4.2: 元数据中心
• 2.3.4.3: 动态路由
• 2.3.4.4: 访问限流
• 2.3.4.5: 熔断降级
• 2.3.4.6: 配置中心
• 2.3.5: 使用 gRPC-Java
• 2.3.5.1: 服务注册
• 2.3.5.2: 服务发现
• 2.3.5.3: 动态路由
• 2.3.5.4: 访问限流
• 2.4: Go 应用开发
• 2.4.1: 使用 Go SDK
• 2.4.1.1: 注册发现
• 2.4.1.2: 动态路由
• 2.4.1.3: 负载均衡
• 2.4.1.4: 熔断降级
• 2.4.1.5: 访问限流
• 2.4.1.6: 缓存与高可用
• 2.4.1.7: 网络连接
• 2.4.1.8: 配置管理
• 2.4.1.9: 可观测性
• 2.4.1.10: 二次寻址
• 2.4.2: 使用 dubbogo
• 2.4.2.1: 服务注册
• 2.4.2.2: 服务发现
• 2.4.2.3: 动态路由
• 2.4.2.4: 访问限流
• 2.4.3: 使用 gRPC-Go
• 2.4.3.1: 服务注册
• 2.4.3.2: 服务发现
• 2.4.3.3: 动态路由
• 2.4.3.4: 负载均衡
• 2.4.3.5: 访问限流
• 2.5: C++ 应用开发
• 2.5.1: 使用 C++ SDK
• 2.5.1.1: 引入依赖
• 2.5.1.2: 注册发现
• 2.5.1.3: 动态路由
• 2.5.1.4: 负载均衡
• 2.5.1.5: 节点熔断
• 2.5.1.6: 访问限流
• 2.5.1.7: 二次寻址
• 2.5.2: 使用 L5Agent
• 2.6: K8s 和网格代理
• 2.6.1: 安装 Polaris Controller
• 2.6.2: K8s 服务同步
• 2.6.3: K8s 配置同步（Beta）
• 2.6.4: Envoy 网格接入
• 2.6.5: DNS 接入
• 2.6.6: JavaAgent 接入
• 2.7: 网关
• 2.7.1: 使用 Nginx
• 2.7.2: 使用 Envoy
• 3: 最佳实践
• 3.1: 灰度发布
• 3.1.1: 蓝绿发布
• 3.1.2: 金丝雀发布
• 3.1.3: 全链路灰度-场景1
• 3.1.4: 全链路灰度-场景2
• 3.2: 测试环境路由
• 3.2.1: 概述
• 3.2.2: 客户端染色
• 3.2.3: 网关动态染色
• 3.2.4: 网关静态染色
• 3.3: K8s 相关实践
• 3.3.1: 跨集群服务注册
• 3.4: 存量服务迁移
• 3.4.1: Eureka 迁移方案
• 3.4.2: Nacos 迁移方案
• 3.4.2.1: 协议兼容（推荐）
• 3.4.2.2: 配置迁移
• 3.4.2.3: 服务迁移
• 4: 参考文档
• 4.1: 版本信息
• 4.1.1: 版本升级指南
• 4.1.2: Release v1.18.0
• 4.1.3: Release v1.17.8
• 4.1.4: Release v1.17.2
• 4.1.5: Release v1.17.0
• 4.1.6: Release v1.16.0
• 4.1.7: Release v1.15.0
• 4.1.8: Release v1.14.0
• 4.1.9: Release v1.13.0
• 4.1.10: Release v1.12.0
• 4.1.11: Release v1.11.0
• 4.2: 接口文档
• 4.2.1: Open API
• 4.2.2: 错误码
• 4.3: 测试报告
• 4.3.1: 性能测试报告
• 4.4: 开发者文档
• 4.4.1: 插件开发
• 4.4.1.1: 开发规范
• 4.4.1.2: CMDB插件开发
• 4.4.2: 指标监控
• 4.4.2.1: 监控指标
• 4.5: 相关产品对比
• 4.5.1: 注册中心对比
• 4.5.2: 服务网格对比
• 4.6: 常见问题
• 4.6.1: 服务端相关
• 4.6.2: 客户端相关

1 - 北极星是什么

1.1 - 简介

北极星是腾讯开源的服务治理平台，致力于解决分布式和微服务架构中的服务管理、流量管理、配置管理、故障容错和可观测性问题，针对不同的技术栈和环境提供服务治理的标准方案和最佳实践。下面介绍北极星的应用场景、功能特性、系统组件和常见问题。

背景

应用架构经历了从单体到分布式服务或者微服务的演进，但是演进并不是替代，每种架构各有优劣。

单体架构

单体架构的全部代码都在一个应用里，适合小型业务系统的研发。如果应用的复杂度低，单体架构易于开发、测试、部署和伸缩。但是，随着功能模块和研发人员的增加，单体架构面临众多问题：

• 故障扩散：如果某些功能模块发生异常，可能影响其他的功能模块。

• 扩展性差：只能扩展整个应用，不能单独扩展某些热点功能，存在资源浪费。

• 迭代效率低：不同功能无法独立迭代，任何改动都影响整个应用，增加开发、测试和发布成本。

• 技术栈单一：全部功能只能采用相同的技术栈开发，引入新技术和升级新版本的难度太大。

微服务架构

对于中型以上规模的业务系统来说，更适合采用分布式服务架构，例如：微信支付这种超大型系统涉及上百个功能模块和上千名研发人员，采用单体架构简直是个灾难。因此，需要将不同的功能拆成分布式服务，每个服务由少量研发人员独立维护。

分布式服务可以解决单体架构的问题，但是用起来并不容易，需要配套的基础设施：

• 本地函数调用变成远程服务调用，需要高效的网络请求框架。

• 网络请求需要解决服务寻址、故障容错和各种应用场景中的流量调度问题。

• 应用数量大幅增加，需要 CICD 流水线和发布平台简化应用的测试和运维工作。

微服务和分布式服务没有本质的区别，微服务更强调服务的粒度要细。在落地过程中，服务的粒度其实没有绝对的标准，要从实际问题出发选择合理方案，不要盲目追求微服务。

北极星致力于打造一个支持多语言、多框架的服务治理平台，帮助用户解决分布式服务或者微服务架构中的服务管理、流量管理、配置管理、故障容错和可观测性问题。

北极星具备哪些功能

北极星具备服务管理、流量管理、故障容错、配置管理和可观测性五大功能：

• 服务管理：包含服务发现、服务注册、健康检查和元数据管理。

  • 服务发现：支持 HTTP、SDK 和 DNS 服务发现方式。
  • 服务注册：支持 HTTP、SDK、控制台操作和 K8s 服务注册方式。
  • 健康检查：支持服务实例上报心跳，通过心跳判断实例是否健康，及时剔除异常实例。
  • 元数据管理：支持在服务和实例上配置协议、版本和位置等标签，实现动态路由等功能。

• 流量管理：包含动态路由、负载均衡和访问限流。

  • 动态路由：支持自定义路由策略，将服务的部分请求路由到部分实例，用于灰度发布等应用场景。
  • 负载均衡：支持权重轮训、权重随机和权重一致性 Hash 等负载均衡算法。
  • 访问限流：支持本地和分布式两种模式，被限流的请求支持排队和自定义响应。

• 故障容错：包含服务熔断和节点熔断。

  • 服务熔断：对服务或者接口进行熔断，如果服务或者接口发生熔断，返回自定义响应。
  • 节点熔断：对服务实例进行熔断，不会将请求路由到熔断的服务实例，降低请求失败率。
  • 主动探测：服务和节点熔断除了被动探测，还支持主动探测，进一步降低请求失败率。

• 配置管理：包含配置变更、配置校验、版本管理和灰度发布等功能。

• 可观测性：提供业务流量、系统事件和操作记录等监控视图。

北极星的功能需要控制面和数据面配合实现：

• 控制面：负责服务和配置数据的管理和下发，负责流量管理和熔断降级策略的管理和下发。

• 数据面：负责全部服务发现和治理功能的客户端实现，采用插件化设计，支持按需加载和使用。

数据面功能分为三个部分：

• 服务作为被调：当一个服务被其他服务调用时，可以使用服务注册、上报心跳、访问限流和访问鉴权功能。

• 服务作为主调：当一个服务调用其他服务时，可以使用服务发现、动态路由、负载均衡和熔断降级功能。

• 公共部分：支持拉取配置数据和上报监控数据。

北极星包含哪些组件

北极星的系统组件分为控制台、控制面和数据面三个部分：

• 控制台：提供简单易用的管理页面，支持用户和权限管理。

• 控制面：包含核心组件 Polaris 和可选的功能组件，核心组件可以满足绝大部分业务需求，可选的功能组件按需部署。

• 数据面：提供多语言 SDK、开发框架、Java Agent 和网格代理四种形态的实现，满足不同的业务场景和开发模式，支持异构服务的互联互通和统一治理。

控制面组件：

• Polaris：支持各种形态的数据面接入，支持服务和配置数据的管理和下发，支持流量管理和熔断降级策略的管理和下发，可以覆盖服务注册中心、服务网格控制面和配置中心的功能。

• Polaris Controller：可选的功能组件，支持 K8s 服务同步和网格代理注入。K8s 服务同步将 K8s 服务按需同步到北极星，用户不需要在应用程序里显式地注册服务。网格代理注入按需在应用程序 Pod 里注入北极星 Sidecar，以流量代理的方式实现服务发现和治理功能。

数据面组件：

• SDK：北极星提供轻量级的多语言 SDK，使用方法和绝大部分客户端软件类似，用户在应用程序里引入北极星 SDK。这种数据面形态以无流量代理的方式实现服务发现和治理功能，没有额外的性能和资源损耗，不会增加现网运维和问题定位的成本。

• 开发框架：北极星 SDK 可以被集成到开发框架内部，如果用户使用开发框架，不需要显式地引入北极星 SDK。对于 Spring Cloud、Dubbo 和 gRPC 等开发框架，北极星提供可以无缝集成的依赖包。另外，go-micro、go-kratos、go-zero、GoFrame 和 CloudWeGo 等开发框架社区也提供北极星插件。

• Java Agent：对于 Spring Cloud 和 Dubbo 等 Java 开发框架，北极星支持 Java 生态常用的 Agent 接入模式。用户只需要在应用程序的启动命令中引入 Polaris Java Agent，即可将北极星的服务发现和治理功能引入应用程序，不需要改动任何代码和配置文件。

• 网格代理：北极星网格代理在应用程序 Pod 里注入 Polaris Sidecar 和 Proxy，前者通过劫持 DNS 解析将请求转到后者，后者通过流量代理实现服务发现和治理功能。这种数据面形态适合性能和资源损耗不敏感的业务，要求业务具备网格代理的运维能力。

常见问题

腾讯业务都在使用北极星吗？

北极星是腾讯内部协同共建的新一代服务发现和治理平台，已整合和替代 L5 等名字服务和负载均衡系统。截止2021年底，超过90%的业务部门使用北极星，接入节点数量超过千万。

北极星开源版和内部版相同吗？

开源版和内部版的主体功能和代码相同，但是部署架构不同。开源版提供单机和集群两种部署架构，集群架构支持百万级的节点接入。内部版通过插件的方式实现了更为复杂的部署架构，支持千万级的节点接入。

北极星和 TARS 是什么关系？

北极星和 TARS 都是腾讯在微服务领域的重点开源项目。曾经，腾讯内部存在多套服务开发框架、注册中心和治理组件，使用不同开发框架的服务难以互相调用和统一管理。为了解决这个问题，腾讯内部协同共建了北极星，整合了服务注册中心和治理组件，TARS 内部版的开发框架部分已接入北极星。北极星和 TARS 开源社区也会尝试更多合作。

1.2 - 功能特性

1.2.1 - 服务管理

服务注册

服务注册指的是被调方按照服务模型将自身的服务数据注册到北极星，以供主调方进行服务发现。

服务数据主要包括以下部分：

• 服务名：服务的唯一标识，区分大小写。
• 服务元数据：服务的标签信息，KV格式，可对服务进行分类，可用于过滤。
• 服务实例：提供服务的节点列表，以IP:PORT的方式提供。
• 服务实例元数据：服务实例的标签信息，KV格式，通常用于描述节点的集群、版本等，用于后续流量治理等操作。

服务注册的方式

北极星支持以下4种服务注册方式：

通过SDK注册

北极星提供了多语言SDK，服务可以通过集成SDK，调用registerInstance接口完成服务注册。

通过服务框架注册

服务框架会提供通用的服务注册接口，供应用在拉起的时候，自动往注册中心注册。

北极星对主流的服务框架（SpringCloud，Dubbo，gRPC）做了适配，用户无需修改业务逻辑代码，只需引入北极星的框架扩展库，即可实现自动注册。

通过k8s同步的方式注册

用户通过k8s部署服务，并注册为k8s的service，北极星通过controller的机制，从k8s中将service和endpoint信息同步到北极星，完成服务注册。

通过OpenAPI注册

北极星控制面提供基于Rest标准的OpenAPI，用户可通过OpenAPI完成服务注册的操作。

服务发现

服务发现指的主调方是根据服务名标识，拉取服务实例列表，以供后续进行服务调用的操作。

服务发现的方式

北极星支持以下4种方式进行服务发现：

通过SDK进行服务发现

北极星提供了多语言SDK，SDK通过ConsumerAPI提供3个接口进行服务发现：

• getAllInstances：获取服务下全量的服务实例列表，不做任何过滤。
• getHealthyInstances：获取服务下健康的服务实例列表，只包含健康实例，不包含被熔断、不健康、隔离、权重为0的实例。
• getOneInstances：针对健康的服务实例列表，进行动态路由和负载均衡，返回单个可用的服务实例。

通过服务框架进行服务发现

服务框架会提供通用的服务发现接口，应用在RPC之前，会自动进行服务发现，获取到可用的实例进行RPC调用。

北极星对主流的服务框架（SpringCloud，Dubbo，gRPC）做了适配，用户无需修改业务逻辑代码，只需引入北极星的框架扩展库，即可实现自动发现。

使用DNS进行服务发现

北极星通过polaris-sidecar提供DNS功能，用户程序可以通过DNS域名访问的方式，实现无侵入的服务发现。

使用OpenAPI服务发现

北极星控制面提供基于Rest标准的OpenAPI，用户可通过OpenAPI完成服务发现的操作。

健康检查

健康检查提供了一种机制，使得控制面可以在一定时间段内，感知服务实例出现异常，从而将异常节点剔除，并通知给所有的消费者。健康检查支持以下实现形式：

心跳上报

服务实例持续上报心跳给控制面，并与控制面约定TTL的时间段，控制面检查服务实例的心跳上报时间点，当发现当前时间相比实例最后一次上报时间已经超过3*TTL，就将实例标记为不健康，并通知给该服务的消费者。

1.2.2 - 流量管理

动态路由

通常一个服务包含多个实例。在简单场景下，每个实例是对等的，通过负载均衡组件访问任意一个即可。

但是，在绝大部分场景下，每个实例具有逻辑属性和物理属性：

• 逻辑属性：版本、协议、业务Set、特性环境等。北极星允许用户为每个实例设置自定义标签
• 物理属性：地理位置。比如实例所属的地域-城市-园区的位置信息。

对于某个服务的全部实例，可以根据逻辑和物理属性将其划分成为多个分组或者集群，如下图所示：

服务主调方/消费者发送请求，客户端根据请求和主调方节点属性，将不同节点的不同请求路由到不同实例分组或者集群。

串联式路由插件

北极星动态路由组件采用插件化、可配置的方式实现。北极星默认内置以下路由插件：

• 前置路由插件：默认在插件链的最前面执行，用于剔除隔离和权重为0的实例。
• 规则路由插件：按照控制台配置的路由规则，根据用户请求参数执行路由规则进行服务实例的过滤。
• 元数据路由插件：直接根据传入的实例元数据对服务实例进行过滤。
• 就近路由插件：根据应用自身所属的地域信息，与实例的地域信息进行匹配，筛选出就近的服务实例。
• 后置路由插件：剔除健康状态异常和故障熔断的实例。如果被剔除的节点数超过一定比例，返回前一个插件的筛选结果，防止因网络分区原因导致的误剔除。

当调用GetOneInstance接口时，会调用路由插件，执行动态路由进行实例筛选，执行流程如下图所示：

插件链中路由插件的执行顺序可以由用户自行编排，同时用户也可以定制自己的路由插件。

负载均衡

从满足本次转发要求的服务实例集中， 通过一定的均衡策略，选取一个实例返回给主调方，供主调方进行服务请求发送。

分类

负载均衡策略一般分为2类：

无状态负载均衡

无状态负载均衡策略，主要特点是每次负载均衡获取到的结果是由具体的负载均衡算法决定。目的是让负载均匀的分发到后端节点。

主要负载均衡策略包括：权重随机，权重轮询等

对于无状态的业务逻辑，为了保证后端节点能够均衡分配请求，此时应该选择权重随机负载均衡策略

有状态负载均衡

有状态负载均衡策略，除了要达到让负载均衡分散到节点的目标以外，还需要实现将同一对象的请求分发到同一个节点。例如业务场景需要将同一个用户的全部请求发送到后端同一个节点处理的情况。

主要负载均衡策略是一致性hash

算法

权重随机

权重随机负载均衡策略，利用区间算法，基于伪随机因子取模的方式选择对应服务实例。

对于有状态的业务逻辑（比如通过用户ID或者请求ID进行hash分区的），为了保证同key请求能够持续命中同一个物理节点，此时应该选择一致性hash负载均衡策略。

权重一致性hash（ringhash算法）

该负载均衡策略基于ketama环算法，每一个服务实例会按照权重分裂成若干个虚拟节点。虚拟节点通过取hash值的方式，映射到长度为2^32的hash环中。

发起查询时，北极星会基于用户传入的hashKey，计算出具体的hash值，然后到环中寻找hash值刚刚好大于传入数据hash值的虚拟节点，并返回其对应的服务实例

权重一致性hash（maglev算法）

该负载均衡策略基于maglev算法（https://static.googleusercontent.com/media/research.google.com/en//pubs/archive/44824.pdf）进行节点分配。

首先为实例集创建一个长度为质数65537的向量表，算法根据节点的权重，将向量表进行填充，直到向量表全部被节点所占满。取节点时则根据用户传值的hashValue取摸的方式，返回对应下标的节点。

算法优点：由于是直接取模寻址，因此算法性能相比ketama环要高（官方数据是在256K个插槽的情况下，性能是5X到10X的差距）。

算法缺点：当节点下线后，导致迁移的节点数量相比ketama环要多（官方数据为迁移节点数量是ketama的两倍）

权重设计

北极星的每个服务实例，都可以设置权重，请求会根据权重，按比例进行分配。权重分为静态权重和动态权重两类：

静态权重

用户可以通过界面配置或者实例注册的方式，调整服务实例的权重，由控制面推送给所有的数据面生效。

动态权重

数据面在运行过程中，定时上报负载数据给控制面，目前支持capacity&used两个指标， 被调方定时（一般2s）上报两个指标的数值到控制面，控制面根据负载信息，调整权重数据。主调方定时拉取最新的权重数据，实时更新以前的静态权重字段，复用老的weightrandom算法。

访问限流

限流能力是高并发系统中，对于服务提供方的一种保护手段。通过限流功能，我们可以通过控制QPS的方式，以避免被瞬时的流量高峰冲垮，从而保障系统的高可用性。

访问限流主要有如下两个应用场景：

• 过载保护：保护业务不被突发流量打垮
• 业务防刷：防止恶意用户发送过多流量影响其他正常用户

北极星为被调端服务提供2种类型的访问限流能力：

单机限流：针对单个被调实例的级别的限流，流量限额只针对当前被调实例生效，不共享。

分布式限流：针对服务下所有实例级别的限流，多个服务实例共享同一个全局流量限额。

两种限流模式如何选择？

• 单机限流：一般适用于保护服务自身不被打垮，按照每个服务集群单机的容量来计算配额。
• 分布式限流：一般适用于保护第三方服务或者公共服务（比如保护数据库）；或者是在网关层进行限流，对通过网关接入的后端服务进行保护。

访问鉴权

访问鉴权包含以下3部分功能：

• 认证：检验服务调用双方的身份真实性
• 加密：对服务调用通讯数据进行加密
• 鉴权：校验请求是否有访问服务接口的权限

访问鉴权可以有效地保护服务调用过程，防止中间人攻击、敏感数据泄露、数据越权访问等问题。

整体架构

Polaris支持使用mTLS来对服务调用进行认证与加密，整体架构如下所示：

• polaris-security是Polaris的安全组件，在mTLS场景下，它支持作为中间证书签发机构（Intermediate Certificate Authority）使用。
• Polaris Controller监测到用户服务启用mTLS功能后，会向Pod内自动注入所有启用mTLS功能需要的环境。
• Polaris xDS Server会给启用mTLS的服务对应的Envoy sidecar下发相应的额外配置。
• Polaris Sidecar中会额外启动mTLS agent组件，通过Unix Domain Socket通讯向Envoy提供SDS（Secret Discovery Service）能力。
• mTLS agent组件会自动生成服务使用的身份证书及私钥，并自动进行轮转（rotate）。
• 每当身份证书接近过期时，mTLS会向polaris-security发送CSR（证书签名请求）来进行更新。

证书签名及轮转原理

启动阶段

• 用户启用mTLS功能之前，需要先在k8s集群中部署两个secret
• polaris-security会读取polaris-security-secret，并为自身签发service certificate，用于在TLS握手中自证身份。
• mTLS agent会读取polaris-sidecar-secret，用于TLS握手中验证polaris-security的身份。

证书签名

• mTLS agent向polaris-security发起TLS保护的certificate signing request，polaris-security会提供自身的service certiface给mTLS agent验证。
• 成功后，polaris-security从请求的header中提取出mTLS agent的Service Account Token，并使用Token Review请求的方式发送给Kubernetes API Server进行验证。
• 验证成功后，正式进入证书签名流程，polaris-security会按CSR中的参数要求，使用CA私钥加密摘要，并将所有材料整合成已签名的证书，连同证书链一起返回给mTLS Agent。
• mTLS Agent可以使用返回的材料来提供SDS服务，已签名的证书可以用作证明workload的身份；证书链可以用作验证对端workload的身份。

证书轮转

• mTLS agent的Rotater类会负责证书轮转，它其实就是一个定时任务执行器，每隔一定时间间隔就会执行一次CSR发送任务，并根据返回结果更新SDS材料，请求失败则会自动重试。
• 轮转时间间隔默认值为30分钟，证书TTL默认值为1小时，自动重试间隔默认为1秒。
• polaris-security是一个无状态的组件，可以进行适当的水平扩展来保证高可用。

mTLS实现原理

Polaris提供三种不同的服务粒度模式供用户选择：

sidecar注入

• mTLS的开关是用户服务的metadata中的polarismesh.cn/tls-mode键对应的label。
• 服务注册回调时，Polaris Controller的injector发现上述label的值为strict或permissve时，就会渲染出额外的注入配置：挂载secret及uds路径、开启iptables入流量拦截、为polaris-bootstrap-writer设置特殊的环境变量等。
• polaris-bootstrap-writer检测到mTLS相关的环境变量被设置后，会使用一份mTLS专用的Envoy配置模版来进行渲染，这份模版中设置了sds的相关配置与特殊的node metadata，polaris控制面就是使用这个特殊的metadata来区分服务网格中的各个服务是否启用mTLS功能。

xDS

• polaris控制面在给各个Envoy sidecar下发配置时，会根据node metadata中的mTLS相关信息来决定下发哪种配置。
• 对于permissve模式，下发的listener会加入一个TLS Inspector filter配置，TLS Inspector能根据请求的头几字节自动判断这是纯文本请求或是mTLS请求，然后进行不同处理；下发的cluster会加入一个额外的Match条件，在对端endpoint拥有acceptMTLS metadata时，会使用tls transport socket，否则就使用默认的raw buffer transport socket。
• 对于strict模式，下发的listener仅接受mTLS服务调用；而下发的cluster仅会使用tls transport socket来连接对端endpoint。

1.2.3 - 熔断降级

熔断降级

故障熔断，指的是当下游因过载或者BUG等原因，出现请求错误后，为了防止故障级联扩散导致整个链路出现异常，从而对请求进行拒绝或者重试的一种机制。

熔断模型

熔断模型的设计遵循业界标准的熔断器模型设计。熔断器有3类状态：

• 关闭：所有请求皆可访问下游资源，无任何限制。
• 打开：限制访问下游资源的请求，不允许任何请求的访问。
• 半开：限制访问下游资源的请求，只允许部分请求达到下游。

熔断场景

熔断一般会发生在以下场景下：

硬件环境出现故障

服务在运营过程中，因为一些不可抗力的因素，可能会出现机器故障、机器重启、机房断电、网络中断等问题。通过熔断机制，对服务实例或者机房分组的快速熔断，可以避免业务请求持续失败。

版本上线引入BUG

版本新特性开发上线后，因为漏测等原因，某些分支触发了BUG，导致部分的业务逻辑出现故障。常见的是部分方法在遇到某些入参的时候，会出现进程报错或者高负载的问题，影响其他方法的请求处理。通过熔断机制，将故障方法进行屏蔽，可以避免其他业务请求受到影响。

服务出现过载

因为路由不均或者峰值流量的到来，导致被调服务出现了高负载，导致请求的时延增大，成功率降低。通过熔断机制，合理的拒绝一部分请求，可以降低服务负载，恢复正常的运行状态。

熔断级别

接口级熔断

应用与服务之间的调用都是针对接口进行调用，为避免调用故障接口导致业务整体时延较大，加剧后端的压力。用户可以设置熔断规则，按照整个服务或者服务下某个接口的粒度设置熔断阈值，并统计在调用过程中的错误率时延等数据，达到阈值后会进行熔断（熔断器打开）。熔断后，访问该服务或特定接口的请求都会返回失败或者走降级逻辑。

接口级熔断生效在接口调用前，主调服务访问接口前需要判断接口的熔断状态。

实例级熔断

一般用于远程服务调用（RPC）的场景，针对某个节点或者分组（具备相同标签的节点集）设置熔断阈值，实例级熔断往往按照具体的服务实例进行熔断统计，并统计在调用过程中的错误率时延等数据，达到阈值后会进行熔断。熔断后，该实例会被屏蔽，不会有请求路由进来，直到恢复。

接口级熔断生效在接口调用中，在负载均衡过程中完成对熔断状态实例的剔除。

触发熔断条件

连续错误数熔断

请求调用时，统计周期内，出现连续错误数目超过阈值之后，资源进入熔断状态。

错误率熔断

熔断器按照滑窗对请求总数及成功数进行统计，并汇总时间段内的总错误率，一旦超过阈值，资源进入熔断状态。

错误判断条件

系统需要通过错误请求的统计来判断是否需要触发熔断，请求的错误一般会表现出以下2个方面的特性：

返回的状态码

对于标准协议的请求，比如HTTP Response，常见的5XX等状态码，代表着后端出现异常（比如数据库异常）导致业务请求失败。

时延

对于交易系统等对时延比较敏感的系统，当出现后端数据库等负载过高的情况，导致部分请求可以正常处理，但是时延普遍过高，此时仍可认为这部分请求是失败请求，触发熔断处理。

熔断恢复

当资源的错误请求统计达到一定阈值后，资源会进入熔断状态，在接下来的一段时间内，该资源将会被屏蔽（不会有请求路由到该资源），渡过屏蔽期后，资源会进入半开状态，此时系统会放少部分业务请求给该资源，并记录请求的处理结果。假如请求全部处理成功，则资源恢复成功（熔断器关闭），取消屏蔽并正常处理业务请求。

但是，假如业务请求扔存在处理失败，则该资源会重新进入熔断状态，继续保持隔离。

如何使用

• 操作北极星控制台
• 使用JavaSDK接入

1.2.4 - 配置管理

配置中心

流程设计

客户端视角

应用启动时，同步从服务端拉取一次配置，获取最新的配置内容。

把第一步拉取到的所有的配置文件生成 ListVersion> 的数据 ，并向服务端发送订阅配置请求，请求内容为 ListVersion>。

当收到配置文件的推送消息时，向服务端拉取最新的配置文件。

配置服务端视角

先检查客户端 ListVersion> 的请求里是否存在 File 版本号落后，如果存在，则立马响应 File -> NewVersion 内容给客户端。

如果客户端配置文件版本号都是最新的，则在内存里维护 File -> List 的数据结构并 Hold 请求 30s。如果 30s 内有配置文件发布，则立马响应请求，返回 File -> NewVersion 给所有客户端。

发布推送配置简化流程

用户在界面点击发布按钮，服务端更新数据库里配置发布表的数据。配置发布表的核心字段：file, version, content, mtime

每个北极星服务端实例，都会定时1s扫描配置发布表，根据 mtime 捞出最近 1s 内变更过的数据

北极星服务端实例扫描到最新变更的数据之后

• 重新加载内存缓存
• 向内存里的消息发布管道里写入一条消息

推送协程从消息发布管道里获取到消息，并消费消息。通过 File -> List 信息，获取所有订阅配置文件的客户端信息，并响应客户端 Hold 的请求。

1.3 - 接入方式

1.3.1 - 使用 SDK

功能简介

北极星网格提供多语言 SDK 作为高性能接入方式：

• polaris-java
• polaris-go
• polaris-cpp
• polaris-php

以插件化和配置化的方式实现服务发现和治理功能：

• 被调方功能：服务注册、上报心跳、限流
• 主调方功能：服务发现、动态路由、负载均衡、熔断降级
• 观测性功能：服务调用、熔断降级和限流的监控统计

接口说明

被调方功能接口

Register

功能：注册服务实例
描述：将实例注册到某个服务下，实例信息包含地址和元数据

Deregister

功能：反注册服务实例
描述：将某个服务下的实例反注册

Heartbeat

功能：上报心跳
描述：如果在注册服务实例时，开启服务端健康检查功能，需要定期上报心跳到服务端，不然服务实例状态异常

GetLimitQuota

功能：获取请求处理配额
描述：如果使用限流功能，在每次处理请求之前，获取请求处理配额。若有配额，则处理请求，否则拒绝处理请求

主调方功能接口

GetAllInstances

功能：获取全部实例
描述：获取注册到某个服务下的全部实例，包含健康、异常和隔离的实例。本接口只使用服务发现功能模块

GetOneInstance

功能：获取一个可用实例
描述：在每次服务调用之前，获取一个可用实例。本接口使用服务发现、动态路由、负载均衡和熔断降级功能模块
备注：几个功能模块采用插件化设计，默认插件配置适用于基本场景，可以根据业务场景调整插件配置

UpdateServiceCallResult

功能：上报服务调用结果
描述：在每次服务调用之后，上报本次服务调用的结果。服务调用结果用于熔断降级和监控统计

接口使用说明

服务被调方

// 在应用启动阶段，注册服务实例
Register(namespace, service, instance)

// 如果使用服务端健康检查功能，在应用运行阶段，需要定期上报心跳到服务端
{
    Heartbeat(namespace, service, instance)
}

// 如果使用限流功能，在每次处理请求之前，获取请求处理配额
{
    if( GetLimitQuota(limiter) ) {
        Handle(request)
    } else {
        Refuse(request)
    }
}

// 在应用停止阶段，反注册服务实例
Deregister(namespace, service, instance)

服务主调方

// 发起一次服务调用
{
    // 获取本次服务调用的实例
    instance = GetOneInstance(namespace, service)

    // 发起服务调用
    response = ServiceCall(instance.address, request)

    // 上报本次服务调用的结果
    UpdateServiceCallResult(instance.id, response.code, response.delay)
}

快速入门示例

各语言 SDK 的快速入门示例：

Java语言

• polaris-java 示例

Go语言

• polaris-go 示例

C++语言

• polaris-cpp 示例

PHP语言

• polaris-php 示例

1.3.2 - 使用开发框架

功能简介

北极星 SDK 可以被集成到开发框架内部，如果用户使用开发框架，不需要显式地引入北极星 SDK，只需要依赖北极星相关的框架插件即可接入北极星。

当前支持以下框架的扩展接入：

• Spring Cloud
• Spring Boot
• Dubbo
• gRPC-Java
• gRPC-Go

开发框架如何集成北极星

北极星会基于服务框架原生的扩展接口之上，封装北极星的多语言SDK，接入北极星服务端实现服务发现、服务治理、配置管理等能力。

下图是SpringCloud框架集成的示意图，北极星只对原生的SpringCloud接口进行扩展，业务逻辑不感知这部分扩展，只需要通过修改POM引入相关的扩展依赖即可。

<dependencies>
  <!-- 示例：引入spring-cloud-starter-tencent-polaris-discovery插件，即可接入北极星服务注册发现功能-->
  <dependency>
     <groupId>com.tencent.cloud</groupId>
     <artifactId>spring-cloud-starter-tencent-polaris-discovery</artifactId>
  </dependency>
</dependencies>

1.3.3 - 使用 Java Agent

功能简介

对于Java应用，北极星 SDK 可以被通过字节码注入的方式，集成到开发框架内部，如果用户使用开发框架，不需要显式地引入北极星 SDK，只需要在启动时，通过-javaagent的指令加载使用JavaAgent，即可无缝接入北极星。

当前支持以下框架的JavaAgent扩展：

• Spring Cloud
• Dubbo

JavaAgent如何集成北极星

北极星会通过字节码注入的方式，将北极星的SDK，作为插件注入到服务框架原生的扩展接口之上，从而接入北极星服务端实现服务发现、服务治理、配置管理等能力。

用户无需修改POM，只需要在启动Java程序时，加入javaagent的JVM启动参数就可以。

java -javaagent:polaris-java-agent-bootstrap-${version}.jar -jar xxx.jar

1.3.4 - 使用 K8s 和网格代理

随着容器化的普及，越来越多用户使用 K8s 部署应用，北极星支持 K8s 服务注册和健康检查。另外，Linkerd 和 Istio 等服务网格通过流量劫持的方式实现大部分服务治理功能，北极星也支持这种接入方式。

K8s服务同步

架构原理

北极星提供polaris-controller，基于kubernetes的controller机制，监听service&pod事件，将K8s Namespace, Service以及Endpoint，实时同步成北极星对应的命名空间、服务、服务实例列表。

用户无需依赖任何SDK及框架，即可实现基于POD的服务实例注册、反注册和健康检查。

应用场景

北极星是一个计算与存储分离的系统，具备极强的可扩展性，一个北极星集群可以支持多个k8s集群同时接入。接入到同一个北极星的集群的多个k8s集群中的应用，可以共享同一份服务数据，实现集群间的无感知调用。

网格代理

架构原理

北极星支持Proxy网格模式，envoy数据面可以直接接入北极星控制面实现服务发现和治理。北极星支持自动注入envoy代理，用户程序无需做任何改动，即可实现自动往POD中注入envoy。

应用场景

北极星提供了多种框架的适配插件，可以支持当下比较流行的proxyless网格模式的接入。SpringCloud、Dubbo的应用可以零改造接入服务网格，共享统一的服务治理模型，与使用Envoy代理的应用无缝互通。

2 - 使用指南

2.1 - 服务端安装

2.1.1 - 单机版安装

北极星支持单机版的安装架构，适用于用户在开发测试阶段，通过本机快速拉起北极星服务进行验证。

单机版包含以下4个组件：

• polaris-console：可视化控制台，提供服务治理管控页面
• polaris-server：控制面，提供数据面组件及控制台所需的后台接口
• polaris-limiter: 分布式限流服务端，提供全局配额统计的功能
• prometheus：服务治理监控所需的指标汇聚统计组件

单机版默认占用以下端口：

服务端监听端口信息

下载软件包

单机版的安装需要依赖单机版软件包，单机版软件包的命名格式为polaris-standalone-release_*.zip：

执行所有安装之前，需要下载软件包，可以从以下2个地址下载单机版软件包，请选择最新的release版本：

• Github下载：polaris standalone releases

下载后需要进行解压，如果有需要自定义单机版相关组件的监听端口，需修改压缩包内的port.properties文件。

port.properties 文件概览

polaris_eureka_port=8761
polaris_open_api_port=8090
polaris_service_grpc_port=8091
polaris_config_grpc_port=8093
polaris_prometheus_sd_port=9000
polaris_xdsv3_port=15010
polaris_console_port=8080
prometheus_port=9090
pushgateway_port=9091
nacos_http_port=8848

使用 Linux 安装

下载Linux单机版软件包（polaris-standalone-release_$version.linux.$arch.zip），执行安装命令：

unzip polaris-standalone-release_$version.linux.$arch.zip

cd polaris-standalone-release_$version.linux.$arch

bash install.sh

使用 Window 安装

注意事项：

• 依赖powershell 5.0及以上版本（Windows 10及以上版本默认安装）
• 需要以管理员身份运行安装脚本，执行powershell需要进行授权操作
• 安装脚本可能遭到系统安全软件的误杀，请在安全软件中执行信任操作

下载Windows单机版软件包（polaris-standalone-release_$version.windows.$arch.zip），执行安装命令：

执行解压：polaris-standalone-release_$version.windows.$arch.zip

进入目录：polaris-standalone-release_$version.windows.$arch

执行脚本：install.bat

使用 Mac 安装

注意事项：

• 请在【关于本机】设置中查看Mac机器的芯片类型（Intel/Apple）
• Intel芯片请使用amd64的软件包，Apple芯片请使用arm64的软件包

下载Mac单机版软件包（polaris-standalone-release_$version.darwin.$arch.zip），执行安装命令：

unzip polaris-standalone-release_$version.darwin.$arch.zip

cd polaris-standalone-release_$version.darwin.$arch

bash install.sh

使用 Docker 安装

查看当前镜像需要暴露的端口信息

docker image ls -a | grep "polarismesh/polaris-standalone" | awk '{print $3}' | xargs docker inspect --format='{{range $key, $value := .Config.ExposedPorts}}{{ $key }}{{end}}'| awk '{ gsub(/\/tcp/, " "); print $0 }'

执行以下命令启动

# Publish a container's port(s) to the host
docker run -d --privileged=true \
-p 15010:15010 \
-p 8101:8101 \
-p 8100:8100 \
-p 8080:8080 \
-p 8090:8090 \
-p 8091:8091 \
-p 8093:8093 \
-p 8761:8761 \
-p 8848:8848 \
-p 9848:9848 \
-p 9090:9090 \
-p 9091:9091 polarismesh/polaris-standalone:latest

使用 Docker Compose 安装

下载 Docker Compose 安装包: polaris-standalone-release_$version.docker-compose.zip

创建mysql、redis 存储卷，方便数据持久化

docker volume create --name=vlm_data_mysql
docker volume create --name=vlm_data_redis

启动服务

执行解压：polaris-standalone-release_$version.docker-compose.zip

进入目录：polaris-standalone-release_$version.docker-compose

执行命令：docker-compose up

安装验证

打开控制台

在浏览器里输入北极星控制台地址（127.0.0.1:8080），非容器化场景127.0.0.1可替换成安装北极星的机器host。

• 登录控制台的默认登录账户信息

用户：polaris
密码：polaris

新建服务

进入服务列表页面，点击【新建】按钮，确认是否可以新建服务。新建服务成功表示安装成功

2.1.2 - 集群版安装

北极星支持高可用的集群安装架构模型，支持多级的容灾架构，适用于用户在生产环境上使用北极星。

集群版控制面无状态化，通过DB以及Redis存储资源信息以及相关状态数据。

服务端监听端口信息

下载软件包

可以从以下2个地址下载北极星软件包，请选择最新的release版本：

• Github下载：
  • polaris releases
  • polaris-console releases
  • polaris-limiter releases

安装数据库

安装MySQL

北极星可以与应用程序共用一个数据库，如果有现成MySQL则可以跳过这一步。

MySQL版本支持

• 开源MySQL版本支持：当前仅支持 >= 5.7，低版本暂未支持。
• 云厂商MySQL支持
  • 腾讯云：支持 Tencent MySQL版，暂不支持 TDSQL-C MySQL兼容
  • 阿里云：支持云数据库RDS MySQL 版

安装开源版本MySQL的步骤可参考：MySQL安装

安装完MySQL后，需要执行数据导入，解压源码包并执行导入：

第一次安装北极星

unzip polaris-$version.zip
cd polaris-$version
mysql -u $db_user -p $db_pwd -h $db_host < store/sqldb/scripts/polaris_server.sql

已有在运行的北极星，执行升级store/sqldb/scripts/delta中的升级脚本

unzip polaris-$version.zip
cd polaris-$version
mysql -u $db_user -p $db_pwd -h $db_host < store/sqldb/scripts/delta/v160-v170.sql

安装Redis

北极星可以与应用程序共用一个Redis，如果有现成Redis则可跳过这一步。

安装开源版本Redis的步骤可参考：Redis安装

安装后，需要设置Redis允许远程主机访问。可以修改redis.conf配置文件：

bind 0.0.0.0
protected-mode no

修改后重启Redis生效。

使用 Linux 安装

安装服务端

安装控制面

下载软件包：下载polaris-server-release_$version.linux.$arch.zip，解压后进入polaris-server-release_$version.linux.$arch目录

配置数据库参数：修改polaris-server.yaml里面的store配置，去掉boltdbStore相关配置，并放开defaultStore相关配置。

# 存储配置
store:
# 数据库存储插件
  name: defaultStore
  option:
    master:
      dbType: mysql
      dbName: polaris_server
      dbAddr: ##数据库地址，格式为ip:port##
      dbUser: ##数据库用户名##
      dbPwd: ##数据库密码##

开启自动注册：修改polaris-server.yaml里面的服务自注册配置，将enable_register改成true，并填入probe_address：

bootstrap:
  polaris_service:
    # 设置为true代表启用自动注册
    enable_register: true
    # 填入数据库地址，用于获取当前节点ip信息
    probe_address: ##数据库地址##

假如北极星集群管理的注册实例数小于 1w 时，可以选择集群部署去 Redis 方案：修改 conf/polaris-server.yaml 里面的 healthcheck 配置，去掉 heartbeatMemory 相关配置，并放开 heartbeatLeader 相关配置。

主从模式

healthcheck:
  checkers:
  - name: heartbeatLeader
    option:
      soltNum:   # 心跳数据存储分片 map 的分片数
      streamNum: # 用于同步心跳数据的 gRPC stream 客户端数，默认为 runtime.GOMAXPROCS(0)

假如北极星集群管理的注册实例数超过 1w 时，推荐集群部署使用 Redis 方案：修改 02-polaris-server-config.yaml 里面的 healthchec 配置，去掉 heartbeatMemory 相关配置，并放开 heartbeatRedis 相关配置。

单节点，主从模式

healthcheck:
  checkers:
  - name: heartbeatRedis
    option:
	    #填入redis的IP以及端口
      kvAddr: ##REDIS_ADDR##
	    #填入redis的密码
      kvPasswd: ##REDIS_PWD##
      maxIdle: 200
      idleTimeout: 120s
      connectTimeout: 200ms
      msgTimeout: 200ms
      concurrency: 200  

集群模式

healthcheck:
  checkers:
  - name: heartbeatRedis
    option:
      deployMode: cluster
      addrs:
        - "127.0.0.1:7001"
        - "127.0.0.1:7002"
        - "127.0.0.1:7003"
      kvPasswd: "polaris"
      poolSize: 233
      minIdleConns: 30
      idleTimeout: 120s
      connectTimeout: 200ms
      msgTimeout: 200ms
      concurrency: 200
      withTLS: false

哨兵模式

healthcheck:
  checkers:
  - name: heartbeatRedis
    option:
      deployMode: sentinel
      addrs:
        - "127.0.0.1:26379"
        - "127.0.0.2:26379"
        - "127.0.0.3:26379"
      masterName: "my-sentinel-master-name"
      sentinelUsername: "sentinel-polaris" # sentinel 客户端的用户名
      sentinelPassword: "sentinel-polaris-password" # sentinel 客户端的密码
      kvPasswd: "polaris" # redis 客户端的密码
      poolSize: 233
      minIdleConns: 30
      idleTimeout: 120s
      connectTimeout: 200ms
      msgTimeout: 200ms
      concurrency: 200
      withTLS: false

启动polaris-server：

bash ./tool/start.sh

安装控制台

下载软件包：下载polaris-console-release_$version.linux.$arch.zip，解压后进入polaris-console-release_$version.linux.$arch目录

修改配置：打开polaris-console.yaml文件，修改polarisServer的地址，将原来的127.0.0.1:8090替换成polarisServer的监听地址

polarisServer:
  address: "${polaris-server的IP地址}:8090"

启动polaris-console：

bash ./tool/start.sh

安装可选功能

安装监控组件

下载软件包：点击下载链接，下载prometheus版本，解压后进入prometheus-2.28.0.linux-amd64目录中。

修改prometheus配置：打开 prometheus.yml文件，修改prometheus的job配置，增加http_sd_configs，其作用是告知prometheus需要从北极星获取应用的监控上报的地址。

  - job_name: 'prometheus'
    static_configs:
    - targets: ['localhost:9090']

    http_sd_configs:
      - url: http://${polaris的IP地址}:8090/prometheus/v1/clients

    honor_labels: true     

启动prometheus：

nohup ./prometheus --web.enable-lifecycle --web.enable-admin-api >> prometheus.out 2>&1 &

修改控制台配置：进入polaris-console的安装目录，打开polaris-console.yaml文件，修改monitorServer的地址，将原来的127.0.0.1:9090替换成prometheus的监听地址。

monitorServer:
  address: "${prometheus的IP地址}:9090"

重启控制台：进入polaris-console的安装目录，执行以下语句重启。

bash ./tool/stop.sh
bash ./tool/start.sh

  - job_name: 'pushgateway'
    static_configs:
    - targets: ['${pushgateway 服务端IP}:9091']

安装分布式限流组件

下载软件包：下载polaris-limiter-release_$version.linux.$arch.zip，解压后进入polaris-limiter-release_$version.linux.$arch目录。

修改配置：打开polaris-limiter.yaml文件，修改polaris-server-address的值为北极星服务端地址。

polaris-limiter多节点需要通过myid保证顺序，关于myid的设置：

• 如果是安装单节点的 polaris-limiter，myid 设置为 1 即可；
• 如果是安装多节点的 polaris-limiter，每个节点的 myid 必须保证唯一。

registry:
  enable: true
  polaris-server-address: { 北极星服务端 grpc 协议地址 }
  name: polaris.limiter
  namespace: Polaris
  health-check-enable: true
api-servers:
  - name: http
    option:
      ip: 0.0.0.0
      port: 8100
  - name: grpc
    option:
      ip: 0.0.0.0
      port: 8101
limit:
  myid: { 服务端节点唯一标识信息，int 类型}

启动polaris-limiter：

bash ./tool/start.sh
bash ./tool/p.sh

使用 K8s 安装

安装服务端

下载软件包：下载polaris-cluster-release_$version.kubernetes.zip，解压后进入polaris-cluster-release_$version.kubernetes目录。

配置数据库参数：修改02-polaris-server-config.yaml里面的store配置，去掉boltdbStore相关配置，并放开defaultStore相关配置。

# 存储配置
store:
# 数据库存储插件
  name: defaultStore
  option:
    master:
      dbType: mysql
      dbName: polaris_server
      dbAddr: ##数据库地址，格式为ip:port##
      dbUser: ##数据库用户名##
      dbPwd: ##数据库密码##

开启自动注册：修改02-polaris-server-config.yaml里面的服务自注册配置，将enable_register改成true，并填入probe_address：

bootstrap:
  polaris_service:
    # 设置为true代表启用自动注册
    enable_register: true
    # 填入数据库地址，用于获取当前节点ip信息
    probe_address: ##数据库地址##

假如北极星集群管理的注册实例数小于 1w 时，可以选择集群部署去 Redis 方案：修改 02-polaris-server-config.yaml 里面的 healthcheck 配置，去掉 heartbeatMemory 相关配置，并放开 heartbeatLeader 相关配置。

主从模式

healthcheck:
  checkers:
  - name: heartbeatLeader
    option:
      soltNum:   # 心跳数据存储分片 map 的分片数
      streamNum: # 用于同步心跳数据的 gRPC stream 客户端数，默认为 runtime.GOMAXPROCS(0)

假如北极星集群管理的注册实例数超过 1w 时，推荐集群部署使用 Redis 方案：修改 02-polaris-server-config.yaml 里面的 healthchec 配置，去掉 heartbeatMemory 相关配置，并放开 heartbeatRedis 相关配置。

单节点，主从模式

healthcheck:
  checkers:
  - name: heartbeatRedis
    option:
	    #填入redis的IP以及端口
      kvAddr: ##REDIS_ADDR##
	    #填入redis的密码
      kvPasswd: ##REDIS_PWD##
      maxIdle: 200
      idleTimeout: 120s
      connectTimeout: 200ms
      msgTimeout: 200ms
      concurrency: 200
      # redis 库，非必选，默认为 0
      db: 0

集群模式

healthcheck:
  checkers:
  - name: heartbeatRedis
    option:
      deployMode: cluster
      addrs:
        - "127.0.0.1:7001"
        - "127.0.0.1:7002"
        - "127.0.0.1:7003"
      kvPasswd: "polaris"
      poolSize: 233
      minIdleConns: 30
      idleTimeout: 120s
      connectTimeout: 200ms
      msgTimeout: 200ms
      concurrency: 200
      withTLS: false
      # redis 库，非必选，默认为 0
      db: 0

哨兵模式

healthcheck:
  checkers:
  - name: heartbeatRedis
    option:
      deployMode: sentinel
      addrs:
        - "127.0.0.1:26379"
        - "127.0.0.2:26379"
        - "127.0.0.3:26379"
      masterName: "my-sentinel-master-name"
      sentinelUsername: "sentinel-polaris" # sentinel 客户端的用户名
      sentinelPassword: "sentinel-polaris-password" # sentinel 客户端的密码
      kvPasswd: "polaris" # redis 客户端的密码
      poolSize: 233
      minIdleConns: 30
      idleTimeout: 120s
      connectTimeout: 200ms
      msgTimeout: 200ms
      concurrency: 200
      withTLS: false
      # redis 库，非必选，默认为 0
      db: 0

执行安装

kubectl create -f 00-polaris-namespace-config.yaml 
kubectl create -f 01-polaris-console-config.yaml  
kubectl create -f 02-polaris-server-config.yaml  
kubectl create -f 03-polaris-server.yaml

安装可选功能

安装监控组件

kubectl create -f 04-prometheus.yaml

修改polaris-console-config的ConfigMap，修改monitorServer的地址，将原来的127.0.0.1:9090替换成prometheus的K8S服务域名。

monitorServer:
  address: "${prometheus的服务域名}:9090"

  - job_name: 'pushgateway'
    static_configs:
    - targets: ['${pushgateway 服务端IP}:9091']

安装分布式限流组件

kubectl create -f 05-polaris-limiter-config.yaml
kubectl create -f 06-polaris-limiter.yaml

使用 Helm 安装

下载软件包：下载 polaris-helm-release_$version.kubernetes.zip，解压后进入 polaris-helm-release_$version.kubernetes.zip 目录。

安装服务端

您需要修改 values.yaml ，将 global.mode 设置为 cluster ，同时设置 polaris.storage.db 和 polaris.storaate.redis 的地址信息。 确保您的 mysql 已经使用下面的命令初始化了。

mysql -u $db_user -p $db_pwd -h $db_host < store/sqldb/polaris_server.sql

设置好后，使用下面的命令安装 chart：

$ cd deploy/helm
$ helm install ${release_name} . 

  - job_name: 'pushgateway'
    static_configs:
    - targets: ['${pushgateway 服务端IP}:9091']

检查安装

部署后可以通过以下命令观察到 pod 正常运行：

$ kubectl get po -n polaris-system
NAME                                  READY   STATUS    RESTARTS   AGE
polaris-0                             2/2     Running   0          2m44s
polaris-prometheus-6cd7cd5fc6-gqtcz   2/2     Running   0          2m44s

如果您在 values.yaml 中配置了 service.type 为 LoadBalancer 则可以使用 polaris 的 service 的 EXTERNAL-IP:webPort 访问到北极星的页面。 如果您的k8s 集群不支持 LoadBalancer ，可以将 service.type 为 NodePort ，通过 nodeip:nodeport 访问。

配置项说明

安装后验证

登录控制台的默认登录账户信息。

用户：polaris
密码：polaris

访问http://{控制台IP}:8080，可以看到登录页面，登录后可以成功看到北极星服务治理控制台内容。

执行以下命令，查看 polaris.limiter 服务下的实例信息，是否包含限流服务。

curl --location --request POST '127.0.0.1:8090/v1/Discover' \
--header 'Content-Type: application/json' \
--data-raw '{
    "type": 1,
    "service": {
        "name": "polaris.limiter",
        "namespace": "Polaris"
    }
}'

可选 开启二次寻址

在大规模集群（百万级别服务）场景下，可对对北极星按照功能模块进行集群拆分，注册发现、健康检查、控制台操作划分为不同集群来进行处理，各集群相互独立，可按照请求量独立扩展。客户端通过埋点集群的二次寻址机制，为接口寻址到目标集群进行功能接口的调用。

服务端配置

注册发现集群的 polaris-server.yaml 配置文件修改

开启服务端自动注册 polaris.discover 服务

bootstrap:
  polaris_service:
    probe_address: ##数据库地址，格式为ip:port##
    enable_register: true
    isolated: false
    services:
      - name: polaris.discover
        protocols:
          - service-grpc

关闭健康检查客户端接口

apiservers:
  - name: service-grpc
    option:
      listenIP: "0.0.0.0"
      listenPort: 8091
      connLimit:
        openConnLimit: false
        maxConnPerHost: 128
        maxConnLimit: 5120
      enableCacheProto: true
      sizeCacheProto: 128
      tls:
        certFile: ""
        keyFile: ""
        trustedCAFile: ""
    api:
      client:
        enable: true
        include: [discover, register]

健康检查集群的 polaris-server.yaml 配置文件修改

开启服务端自动注册 polaris.healthcheck 服务

bootstrap:
  polaris_service:
    probe_address: ##数据库地址，格式为ip:port##
    enable_register: true
    isolated: false
    services:
      - name: polaris.healthcheck
        protocols:
          - service-grpc
      - name: polaris.checker
        protocols:
          - service-grpc

只开放健康检查客户端接口

apiservers:
  - name: service-grpc
    option:
      listenIP: "0.0.0.0"
      listenPort: 8091
      connLimit:
        openConnLimit: false
        maxConnPerHost: 128
        maxConnLimit: 5120
      enableCacheProto: true
      sizeCacheProto: 128
      tls:
        certFile: ""
        keyFile: ""
        trustedCAFile: ""
    api:
      client:
        enable: true
        include: [healthcheck]

修改完 polaris-server.yaml 配置之后，重启服务端节点即可

客户端配置

• Polaris Java 客户端启用二次寻址
• Polaris Go 客户端启用二次寻址
• Polaris C++ 客户端启用二次寻址

2.2 - 控制台使用

2.2.1 - 命名空间

命名空间列表

通过浏览器输入http://127.0.0.1:8080（127.0.0.1可换成服务端实际安装的IP地址），打开Polaris控制台。

在侧边栏点击命名空间，进入命名空间列表页：

创建命名空间

点击新建按钮，在弹出对话框中填入命名空间全局唯一名称，即可完成命名空间的创建。

创建命名空间字段说明：

2.2.2 - 注册中心

2.2.2.1 - 服务列表

服务

服务列表

在侧边栏点击服务，进入服务列表页，列表各字段含义如下：

创建服务

点击新建按钮，在弹出来的对话框填入命名空间和服务名（同一命名空间下需唯一）等必填信息，即可完成服务的创建。

创建服务字段说明：

服务实例

服务实例列表

在控制台点击具体服务名，进入服务实例列表页。

创建实例

点击新建按钮，在弹出来的对话框填入实例IP和端口（同一服务下IP和端口组合需唯一），即可完成服务实例的创建。

创建服务实例字段说明：

2.2.2.2 - 服务可见性

为了解决 spring cloud 等一些微服务调用框架不支持跨命名空间调用的场景，北极星提供了服务可见性的配置。

• 命名空间设置服务可见性：该命名空间下的服务，可以被别的命名空间下的服务所发现
• 服务设置可见性：该服务除了可以被自己所在命名空间下的其他服务发现外，还可以被别的命名空间下的服务所发现

2.2.3 - 服务网格

2.2.3.1 - 动态路由

自定义路由

路由规则分类

规则路由是一种根据一段DSL（路由规则）来控制消息分流的机制。

路由规则分为被调规则和主调规则2部分：

• 被调规则代表的是当服务作为被调方时，控制所有主调方进行流量转发的规则。

• 主调规则代表的是当服务作为主调方时，控制所有被调方进行流量转发的规则。

服务上可以配置主调规则和被调规则，如下图所示：

• 主调规则

• 被调规则

配置被调规则

被调规则在服务作为被调方时候生效，配置界面如下：

图上的规则的含义是：当echo-server（服务名）作为被调方时，对于所有主调方过来的，带有user-type:1的标签的请求，都路由给自身服务版本号为1.0.0的实例分组。

配置主调规则

主调规则在服务作为主调方时候生效，配置界面如下：

图上的规则的含义是：当echo-server（服务名）作为主调方时，对于发出去的请求，带有user-type:1的标签的请求，都路由给目标服务版本号为1.0.0的实例分组。

路由规则的匹配流程

请求匹配规则

可选，指定限流规则的请求参数匹配条件，不填代表不过滤，支持以下四种参数类型：

• 自定义参数：自定义KEY和VALUE，具体的请求参数值可通过SDK进行传入。

• 请求头（HEADER）：针对协议消息头（http header/grpc header）进行过滤。

• 请求参数（QUERY）：针对协议请求参数（http query）进行过滤。

• 请求COOKIE（COOKIE）：针对协议 cookie 参数（http cookie）进行过滤。

• 方法（METHOD)：针对协议的METHOD（http method/grpc method）进行过滤。

• 主调IP（CALLER_IP）：针对主调方机器的IP地址进行过滤。

• 路径（PATH）：针对协议请求路径进行过滤

每种类型参数值支持以下几种值匹配模式：

• 全匹配：全值匹配，传入的值与配置的值相同才匹配通过。

• 正则表达式：用户配置正则表达式，通过正则表达式对传入的值进行匹配，正则表达式支持Google RE2标准。

• 不等于：取反匹配，传入的值与所配置的值不相等才算匹配成功。

• 包含：多字符串取OR匹配，传入的值只要匹配到其中一个字符串，就算匹配成功。字符串之间使用逗号进行分割。值格式为’value1,value2,value3‘，匹配到其中一个就算成功。

• 不包含：多字符串取反匹配，传入的值必须都没有出现在所配置的字符串列表中，才算匹配通过。值格式为’value1,value2,value3‘，全部不等于才算成功。

边界条件

• 通过请求标签进行匹配，没有匹配到一个路由规则，则本次请求路由失败，返回空实例列表。
• 通过请求标签进行匹配，匹配到了路由规则，但是路由规则所对应的destination不存在服务实例，则本次请求获取到的服务实例为空。
• 通过请求标签进行匹配，匹配到了路由规则，路由规则对应的2个同优先级的destination，请求会在这2个destination中按照权重比例随机路由，假如其中一个destination不存在服务实例，则路由到该destination的请求获取到的服务实例为空。

自定义路由实践

按版本号灰度实践

场景描述

请求通过网关接入，路由到后端服务。后端服务上线了新版本，新版本只对打了标签的用户请求开放，未打标签的请求继续路由到老版本。

使用方式

• 配置路由规则

  由于新版本上线的行为发生在被调方，主调方并不感知被调是否上线了新版本服务，因此路由规则需要配置在被调方。配置一个被调规则，指定只有gray=true的请求，才流入版本号为2.0.0的实例分组，其他请求则流入版本号为1.0.0的实例分组。

  (1) 配置兜底规则：将请求导入到1.0.0版本的分组。

(2) 配置灰度规则：将gray=true的请求导入到2.0.0版本的分组，不存在2.0.0分组时，请求导入到1.0.0的分组。

(3) 规则列表：将按顺序进行匹配执行规则。

• 执行服务路由

  可以执行各个语言SDK的版本号路由样例进行服务路由功能的执行，执行完可以通过调用结果可以看到灰度的请求都流向了版本号2.0.0的分组。

多环境隔离实践

场景描述

使用微服务架构时，一个业务数据流通常需要跨多个微服务才能完成。而在业务开发过程中，通常会有以下诉求：

• 为了提升开发效率，不同特性开发人员，需要使用特性环境进行并发开发测试联调，特性环境之间需要进行隔离；
• 同时为了降低部署成本，开发测试时，只需要部署特性变更所涉及的服务，链路其他未更改的服务，统一使用基线环境的服务。

使用方式

• 配置路由规则

本次场景，存在2个特性并行开发，特性（dev1）涉及修改的微服务为Svr1和Srv4，特性（dev2）涉及修改的微服务为Svr2。其他不涉及修改的微服务，在开发联调过程中，统一使用基线环境的服务。 为了防止混乱，每个特性开发人员只允许针对自己涉及修改的微服务添加针对当前特性的规则，不涉及修改的微服务不允许添加规则。

（1）所有的服务默认配置一个兜底规则，将请求导入到基线环境。

（2）Srv1服务添加一个主调规则，将来源dev1请求路由到dev1的Svr2。

（3）Svr4服务添加一个被调规则，将来源dev1请求路由到dev1的Svr4。

（4）Svr2服务添加一个被调规则，将来源dev2请求路由到dev2的Svr2。

• 执行服务路由

  可以执行各个语言SDK的多环境路由样例进行服务路由功能的执行，执行完可以通过调用结果可以看到不同特性环境的请求都流向了对应特性环境的分组。

2.2.3.2 - 就近路由

功能描述

北极星提供基于 地域(region) - 城市(zone) - 园区(campus) 这3元组组成的地域信息进行就近路由的能力，能够根据主调的地域信息，结合被调实例的地域信息，进行匹配。实例本身的地域信息来源于有以下几个途径

服务端的 CMDB 插件

• 参考 cmdb 插件开发

客户端的 Location 插件

• 提供 Location 插件，用户可以根据 polaris客户端 中对于 Location 插件的定义，根据客户端所在环境的特性来实现不同的本地地址位置信息获取插件
  • env: 将地理位置信息注入至客户端所在机器的环境中，客户端就可以基于系统环境变量自动获取地理位置信息

配置设计

polaris-go 客户端使用

SDK配置属于客户端全局配置，基于该SDK实例所发起的服务发现，都遵循该就近路由策略。 由于就近路由能力通过SDK服务路由模块的插件进行提供，因此就近路由相关配置，也作为插件的特有配置来进行提供。

global:
  # 地址提供插件，用于获取当前SDK所在的地域信息
  location:
    providers:
      - type: local
        region: ${REGION}  # 从环境变量 REGION 中读取
        zone: ${ZONE}      # 从环境变量 ZONE 中读取
        campus: ${CAMPUS}  # 从环境变量 CAMPUS 中读取
consumer:
  serviceRouter:
    # 服务路由链
    chain:
      - nearbyBasedRouter
    # 插件特定配置
    plugin:
     nearbyBasedRouter:
        # 默认就近区域：默认城市
        matchLevel: zone
        # 最大就近区域，默认为空（全匹配）
        maxMatchLevel: zone

polaris-java 客户端使用

SDK配置属于客户端全局配置，基于该SDK实例所发起的服务发现，都遵循该就近路由策略。 由于就近路由能力通过SDK服务路由模块的插件进行提供，因此就近路由相关配置，也作为插件的特有配置来进行提供。

global:
  location:
    providers:
      - type: local
        options:
          region: ${REGION:}  # 从环境变量 REGION 中读取
          zone: ${ZONE:}      # 从环境变量 ZONE 中读取
          campus: ${CAMPUS:}  # 从环境变量 CAMPUS 中读取
  serviceRouter:
    chain:
      # 就近路由
      - nearbyBasedRouter
    plugin:
      nearbyBasedRouter:
        #描述: 就近路由的最小匹配级别。region(大区)、zone(区域)、campus(园区)
        matchLevel: zone
        #描述: 最大匹配级别
        maxMatchLevel: all

服务配置

• 在控制台上通过可视化的方式操作开关就近路由。
  • 

就近流程

初始化

• 用户调用NewConsumerAPI或者NewProviderAPI后
• SDK 会使用客户端节点的 IP，往 Polaris 服务端查询该 IP 对应的 CMDB 信息，查询后的结果后返回给客户端
• 如果查询的结果中，没有携带地址信息，则客户端会走自己本地的 CMDB 插件查询客户端的地理位置信息

地域匹配

服务调用过程中，使用拉取的客户端地域信息，进行全词匹配。匹配规则如下：

• 优先按照 matchLevel 进行匹配，匹配不成功（实例不存在或者可用实例比例少于阈值），则进行降级
• 就近降级按照 degrade 所配置的策略进行降级，会进行逐级的降级匹配，直到 lowestMatchLevel

降级策略

被调信息异常策略

跨机房容灾场景

背景

服务端有广州云、深圳、南京云设备。客户端在深圳。 那么深圳客户端访问这个服务端时，返回实例列表由深圳、广州、南京实例组成，同时设置优先级，让深圳客户端优先访问深圳；然后是广州(同可用区)；最后是南京

解决方案

假设存在服务A，服务A下面节点存在分别属于深圳、广州、南京的实例，CMDB信息如下：

• 华南/ap-guangzho/ap-guangzhou-3
• 华南/ap-shenzhen/ap-shenzhen-2
• 华东/ap-nanjing/ap-nanjing-4

客户端配置：

consumer:
  serviceRouter:
    plugin:
      nearbyBasedRouter:
        # 默认按zone进行就近
        matchLevel: zone

就近逻辑

客户端配置 matchLevel: zone，默认只访问同 zone(深圳) 的实例，当深圳可用区无实例后，降级访问 region(华南) 的 实例（可访问广州的实例），当华南地区实例也达到降级条件后，降级访问全部 region(包含华东-南京) 的实例

2.2.3.3 - 访问限流

限流规则说明

北极星支持在界面配置单机限流规则，通过以下路径可以打开限流规则的编辑页面：控制台->服务列表->具体服务->限流规则->新建，打开后，规则各配置项说明如下：

限流类型

• 单机限流：单机限流是一种通过统计单机QPS指标，当达到规则指定阈值时对流量进行限制，保障服务实例不被瞬时流量给冲垮。

• 分布式限流：分布式限流是一种通过统计全局QPS指标，当达到规则指定阈值时对流量进行限制，保障服务实例不被瞬时流量给冲垮。

接口名称

可选，指定限流规则的接口过滤参数，接口名可对应方法名、http url等信息，不填代表不过滤。

• 接口：规则生效所对应的接口名，用于匹配客户端传入的method参数，默认为空(全部)
• 匹配方式：接口字段的匹配方式，支持全匹配、不等于、包含、不包含、正则表达式四种匹配模式

请求匹配规则

可选，指定限流规则的请求参数匹配条件，不填代表不过滤，支持以下四种参数类型：

• 自定义参数：自定义KEY和VALUE，具体的请求参数值可通过SDK进行传入。

• 请求头（HEADER）：针对协议消息头（http header/grpc header）进行过滤。

• 请求参数（QUERY）：针对协议请求参数（http query）进行过滤。

• 方法（METHOD)：针对协议的METHOD（http method/grpc method）进行过滤。

• 主调服务：针对微服务调用场景下，主调方的服务名进行过滤。

• 主调IP：针对主调方机器的IP地址进行过滤。

每种类型参数值支持以下几种值匹配模式：

• 全匹配：全值匹配，传入的值与配置的值相同才匹配通过。

• 正则表达式：用户配置正则表达式，通过正则表达式对传入的值进行匹配，正则表达式支持Google RE2标准。

• 不等于：取反匹配，传入的值与所配置的值不相等才算匹配成功。

• 包含：多字符串取OR匹配，传入的值只要匹配到其中一个字符串，就算匹配成功。字符串之间使用逗号进行分割。值格式为’value1,value2,value3‘，匹配到其中一个就算成功。

• 不包含：多字符串取反匹配，传入的值必须都没有出现在所配置的字符串列表中，才算匹配通过。值格式为’value1,value2,value3‘，全部不等于才算成功。

限流阈值

指定统计周期内的统计阈值，达到阈值则进行限流。可以配置多个限流阈值，多个限流阈值可同时生效，任意触发了一个就进行限流。

• 统计时长：限流阈值的统计时长，单位秒，默认为1秒
• 请求数：达到限流条件的请求数阈值。默认为1

限流效果

限流阈值被触发后，如何进行对流量进行限制，目前支持2种模式（默认为直接拒绝）：

• 直接拒绝：当统计时长内请求数达到阈值，后续新的请求会被拒绝，直到下个统计周期到来才恢复。
• 匀速排队：基于漏桶算法，将请求数平均分配到统计时长内（细分的最小度量单位为1ms），从而控制请求以均匀的速度通过。

失败退化策略

分布式限流需要依赖token server，如果出现token server不可访问，则客户端可以根据配置的规则进行降级，保证用户请求最大限度不受影响。

• 退化成单机限流：默认策略。直接退化成单机计算配额的方式进行限流，单机配额=(全局配额/节点数)。
• 直接通过：不执行限流，所有请求都直接放通。

使用场景

针对服务进行限流

在RateLimitServiceJava服务下新建限流规则，指定QPS为10，限流效果选择直接拒绝。

针对接口+标签进行细粒度限流

在 RateLimitServiceJava 服务下新建限流规则，指定QPS为10，方法名为/echo，针对 http 请求中的 header user=foo 进行限流，限流效果选择直接拒绝。

针对接口+标签进行热点参数限流

在 RateLimitServiceJava 服务下新建限流规则，指定QPS为10，方法名为/echo，针对 http 请求中的 header user的每一个参数值进行单独限流，限流效果选择直接拒绝。

热点参数限流规则配置需要满足2个条件，否则无法生效：

• 存在非全匹配规则。”接口名称“、”请求匹配规则“配置中至少存在一条规则是非全匹配规则，比如”不等于“；如果全是全匹配规则，那该限流只是普通限流。
• 不启用”合并计算阈值“。

热点参数限流是一种针对高并发请求中某些热点参数的限流策略；如上述规则的限流效果图如下：

使用匀速排队

在RateLimitServiceJava服务下新建限流规则，指定QPS为10，限流效果选择匀速排队。

2.2.3.4 - 熔断降级

熔断规则说明

北极星支持在界面配置熔断规则，通过打开北极星控制台，在左侧边栏选择”熔断降级“，可打开熔断降级规则列表，分为3个子TAB，分别配置服务级熔断规则、实例级熔断规则、主动探测规则。

服务级熔断规则

点击新建熔断规则，可以新建服务级熔断规则。服务级熔断规则用于针对特定服务或者服务下的接口进行熔断。

界面各字段含义如下：

基础信息

• 规则名称：规则名，需全局唯一。
• 描述：规则的描述信息，用于补充规则的说明。

匹配条件

匹配条件主要用于决定熔断规则的适用范围，客户端根据匹配条件来过滤本地调用所适用的熔断规则。

• 主调服务：配置作为主调方的服务名和命名空间，可选。不配置则默认对所有的主调生效。
• 被调服务：配置被调的服务名和命名空间，可选。不配置则默认对所有的被调生效。
• 被调接口：配置被调的接口名，表明该熔断规则只对调用某个接口的请求生效，可选。接口名支持多种匹配条件，具体匹配条件可参考：字符串匹配方式

另外，熔断规则中所填的服务名，可为任意服务名，不一定需要存在于北极星注册中心。

熔断配置

• 错误判断条件：可配置多个判断条件，满足任意一个条件的请求会被标识为错误请求。支持返回码和时延2种判断方式。
• 熔断触发条件：可配置多个触发条件，满足任意一个条件即会触发熔断，资源会进入熔断状态。支持连续错误数和错误率2种触发条件。
  • 连续错误数：统计调用该服务/接口的请求连续错误数，达到阈值即触发熔断。
  • 错误率：统计在周期内调用该服务/接口的请求的错误率，达到阈值即触发熔断。同时为避免少流量下的放大效应，可配置错误率统计的起始请求阈值，请求数超过阈值才进行熔断判断。
• 熔断粒度：指定熔断的资源粒度，支持接口（按单个接口进行统计并熔断，只熔断单个接口），以及服务（按服务维度来统计并熔断，熔断整个服务）。
• 熔断恢复：资源触发熔断后，会熔断请求调度到该资源一段时间。随后系统会对资源进行恢复尝试，当满足一定次数的连续成功请求数后，资源会恢复正常状态。用户可配置资源熔断时长（单位秒），以及连续成功请求数。

主动探测

可选择开启主动探测。开启后，主调方会根据被调服务/接口所关联的探测规则，向被调方发起探测，探测结果会与业务调用合并，作为熔断触发或恢复的依据之一。

熔断后降级

可选择开启降级。开启后，当服务/接口被熔断后，访问该服务/接口的请求，会以自定义响应的方式访问给主调方。

• 返回码：自定义响应的返回码。
• Headers：自定义响应的消息头，可添加多个。
• Body：自定义响应的消息体。

是否开启

选择是否开启该规则。

实例级熔断规则

点击新建熔断规则，可以新建实例级熔断规则。实例级熔断规则用于针对特定分组下多个服务实例或者单个服务实例进行熔断。

界面各字段含义如下：

基础信息

• 规则名称：规则名，需全局唯一。
• 描述：规则的描述信息，用于补充规则的说明。

匹配条件

匹配条件主要用于决定熔断规则的适用范围，客户端根据匹配条件来过滤本地调用所适用的熔断规则。

• 主调服务：配置作为主调方的服务名和命名空间，可选。不配置则默认对所有的主调生效。
• 被调服务：配置被调的服务名和命名空间，可选。不配置则默认对所有的被调生效。
• 被调接口：配置被调的接口名，表明该熔断规则只对调用某个接口的请求生效，可选。接口名支持多种匹配条件，具体匹配条件可参考：字符串匹配方式

另外，熔断规则中所填的服务名，可为任意服务名，不一定需要存在于北极星注册中心。

熔断配置

• 错误判断条件：可配置多个判断条件，满足任意一个条件的请求会被标识为错误请求。支持返回码和时延2种判断方式。
• 熔断触发条件：可配置多个触发条件，满足任意一个条件即会触发熔断，资源会进入熔断状态。支持连续错误数和错误率2种触发条件。
  • 连续错误数：统计调用该实例的请求连续错误数，达到阈值即触发熔断。
  • 错误率：统计在周期内调用该v的请求的错误率，达到阈值即触发熔断。同时为避免少流量下的放大效应，可配置错误率统计的起始请求阈值，请求数超过阈值才进行熔断判断。
• 熔断粒度：指定熔断的资源粒度，支持实例（按单个实例进行统计并熔断）。
• 熔断恢复：资源触发熔断后，会熔断请求调度到该资源一段时间。随后系统会对资源进行恢复尝试，当满足一定次数的连续成功请求数后，资源会恢复正常状态。用户可配置资源熔断时长（单位秒），以及连续成功请求数。

主动探测

可选择开启主动探测。开启后，主调方会根据被调服务/接口所关联的探测规则，向被调方发起探测，探测结果会与业务调用合并，作为熔断触发或恢复的依据之一。

是否开启

选择是否开启该规则。

主动探测规则

用户可配置主动探测规则，指定被调服务通过什么方式进行探测，探测结果将作为被调资源熔断及恢复的依据。

界面各字段含义如下：

• 规则名称：必选。规则名，需全局唯一。
• 描述：可选。规则的描述信息，用于补充规则的说明。
• 命名空间：必选。被调服务的命名空间。
• 服务名称：必选。被调服务的名称。
• 接口名称：可选。被调接口的名称，支持多种匹配条件，具体匹配条件可参考：字符串匹配方式。
• 周期：可选。探测周期，多久执行一次探测，默认30秒。
• 超时时间：可选，探测最大超时时间，超时未响应则以最大超时时间作为熔断依据。默认60秒。
• 端口：可选，探测端口，默认为服务实例端口。
• 协议：使用什么协议进行探测，会影响接下来的配置，支持HTTP, TCP, UDP 3种协议。
• HTTP协议配置：
  • 方法：HTTP方法，默认Get。
  • Url：探测Url，默认/。
  • Headers：发送探测包所需的消息头，默认空。
  • Body：发送探测包所需的消息体，默认空。
• TCP协议配置：TCP默认会采用tcp connect的方式进行探测，用户也可以配置基于报文的探测手段。
  • Send：配置所需发送的TCP二进制报文，格式为0x开头的十六进制字符串，如：0x12ab。
  • Receive：配置所接收的TCP二进制报文，可配置多个，不配置则不校验应答。
• UDP协议配置：UDP没有连接检测的方式，只能通过基于报文的探测手段。
  • Send：配置所需发送的UDP二进制报文，格式为0x开头的十六进制字符串，如：0x12ab。
  • Receive：配置所接收的UDP二进制报文，可配置多个。

北极星客户端具体使用哪种协议进行探测，与被探测实例的端口协议有关，主要获取的是实例的protocol属性，对应关系如下：

客户端接入

• 使用JavaSDK接入

附录

字符串匹配方式

熔断规则使用公共的字符串匹配对话框，对话框支持多种匹配模式：

• 全匹配：实际请求字段与文本框所填内容全匹配，区分大小写。
• 正则表达式：文本框所填内容为正则表达式，实际请求字段需匹配所填的正则表达式，遵循Google Re2标准。
• 不等于：实际请求字段不等于文本框所填内容，区分大小写。
• 包含：文本框所填内容为多段的文本，以逗号来进行分割。实际请求字段内容必须全匹配其中某一段文本。
• 不包含：文本框所填内容为多段的文本，以逗号来进行分割。实际请求字段内容必须全不等于其中任何一段文本。

2.2.4 - 配置中心

2.2.4.1 - 配置分组

名词解释

• 命名空间（Namespace）
  • 通过 Namespace 可以逻辑隔离环境、集群
• 配置分组（FileGroup）
  • 一组配置文件的集合
• 配置文件（File）
  • 配置编辑、发布的最小单元。例如一份 properties 、yaml 格式的配置文件。
• 配置文件三元组
  • 通过 Namespace + FileGroup + File 可以唯一定位一份配置文件。

新增并发布配置文件

创建命名空间

如果已存在命名空间，可以跳过此步骤。

创建配置文件分组

配置文件分组是一组配置文件的集合，通常建议一个应用或者一个微服务对应一个配置分组，例如订单服务 order-service等。如果是客户端 jar 包使用的配置文件，也可以以 jar 包命名，例如 dubbo-rpc。

创建配置文件

这里需要特别指出的是配置文件名可以通过 / 来组织配置文件目录树。因为一个应用往往具有多个模块，每个模块都有自身的配置文件。当配置文件多了之后，如果没有目录结构组织，配置将变的难以管理。北极星配置中心通过配置文件名按 / 分割来组织树状结构。例如上图中 common/bootstrap.properties 效果如下：

再新建一个 common/application.yaml 文件和一个 web/controller/web.properties 效果如下：

可以看到通过树状结构可以清晰的管理自己的配置文件。 需要注意的是只有叶子节点是配置文件，目录不可以是配置文件，跟 Zookeeper 有些区别。例如有一个配置文件名为：common/bootstrap.properties，就不能再建一个 common 的配置文件，因为 common 已经作为 common/bootstrap.properties 的上级目录。

编辑配置文件

选中配置文件 -> 点击编辑 -> 输入配置文件内容 -> 点击保存。

发布配置文件

编辑保存之后，点击发布即可发布配置文件。

查看发布历史

通过详情页“查看发布历史”或者侧边栏“发布历史”入口可以跳转到发布历史页面查看配置文件发布历史记录。

2.2.4.2 - 配置导入导出

导出配置文件

导航到配置分组，点击上方导出按钮弹出配置导出对话框。

选择要导出的配置文件所在命名空间。

提供两种导出形式：

1. 全部导出：将命名空间中的配置分组全部导出

2. 导出选中的配置分组：选择命名空间中的配置分组导出

选择完成后，点击提交按钮导出配置，配置文件会已config.zip文件的形式下载到本地。

导出的配置文件config.zip压缩包中文件组织结构为：

├── META                  // 导出配置的元数据文件
├── group                 // 配置分组为一级目录
│   ├── filename          // 配置文件
│   └── dir               // 配置文件子目录
│       ├── otherfile      
├── othergroup

如下图示例所示：

META文件记录配置文件的tag信息和comment信息，如下图示例所示：

导入配置文件

导航到配置分组，点击上方导入按钮。

弹出配置导入对话框，选择要导入的命名空间，从本地上传要导入的配置文件。

配置文件需要组织成ZIP压缩包，其文件组织结构需要跟导出的配置文件类似：

├── META                  // 导入配置的元数据文件
├── group                 // 配置分组为一级目录
│   ├── filename          // 配置文件
│   └── dir               // 配置文件子目录
│       ├── otherfile      
├── othergroup

导入配置文件时META文件是可选的，如果需要导入配置文件的tag信息和comment信息，则需要提供META文件，否则可以不提供。

如果导入的配置文件与命名空间中已有的配置文件冲突，可以选择跳过或覆盖冲突文件。

导入成功后会显示导入文件详情。

2.2.4.3 - 配置加密

设计

客户端：

• 客户端本地生成一对公钥和私钥，请求配置文件时携带公钥参数，服务端使用客户端发来的公钥作为KEK（密钥加密密钥）对配置文件的DEK进行加密，然后返回客户端配置密文和DEK密文，客户端收到后用私钥解密DEK密文得到DEK明文，再用DEK解密配置密文。
• 客户端解密流程
  • 

控制台：

• 创建加密配置: 创建配置接口增加是否加密参数，如果需要加密，服务端生成数据加密密钥DEK，加密配置文件，保存配置文件密文到配置文件表，保存DEK和配置创建人配置文件的标签表。

• 查看加密配置: 用户在有读权限的前提下，请求获取配置文件，如果配置文件是加密的，服务端额外校验请求人是否为创建人，如果是则使用DEK解密配置文件后返回；如果不是则只返回配置文件密文。

• 控制台创建读取流程

  • 

如何启用配置加密

• 在新增配置文件中，点击配置加密的开关按钮

• 确认开启配置加密后，选择期望的配置加密算法

• 正常填写配置内容并发布

• 客户端接口获取到的文件内容是加密的

当前支持的客户端版本

• Polaris Java 客户端开启配置加密
• Polaris Go 客户端开启配置加密

2.2.4.4 - 配置灰度

功能描述

在使用配置中心对业务集群配置进行集中管理时，如果对某个配置项进行了修改，配置中心会将新的配置下发到所有监听该配置文件的业务进程中。业务进程接受到新的配置后会将新的配置覆盖当前的旧配置从而完成配置生效。由于配置是下发到所有客户端，一旦配置值修改不符合预期，将影响整个业务集群。

因此，在需要对配置进行编辑后下发到业务机器时，推荐先进行灰度发布。灰度发布是指在修改配置需要发布时，根据一定的规则选择一小部份机器，将修改后的配置先下发到这些机器中进行小范围验证。待业务确认无问题时，再将配置进行全量下发。如果在灰度发布期间发现问题，可以立即停止灰度发布。

如何使用

• 编辑完配置文件后，点击灰度发布

  

• 在弹出的框中，填写客户端灰度标签信息

  

• 点击下一步，完成提交，便可看到处于灰度发布中的配置

  

2.2.5 - 权限控制

2.2.5.1 - 概述

• Polarismesh(北极星) 的鉴权功能，您可以清晰地管理资源与用户的访问权限。北极星基于命名空间和服务资源维度实现权限管控。

• Polarismesh(北极星) 引入策略的概念，将资源的访问权限与不同的用户角色联系到一起。例如下图，

  

• Polarismesh(北极星) 默认账户

  name: polaris
  password: polaris
  

鉴权模型

主账号

也可称为主用户，是所有北极星资源的拥有者，对所有北极星资源有操作权限。

• 主账户可以直接修改子账户的密码
• 主账户可以创建、删除用户
• 主账户可以创建、删除用户组
• 主账户可以为用户组添加、移除用户
• 主账户可以禁用用户、用户组token
• 主账户可以编辑鉴权策略

子账号

由主账户创建的协作账户，默认只能操作没有关联任何鉴权策的北极星资源。

• 子账户能够查看北极星的账户列表，但是只能查看自己的账户信息
• 子账户只能查看自身的token信息
• 子账户只能查看自己所在的用户组列表
• 子账户只能查看自己所在的用户组的token

用户组

北极星的用户组概念，是一组具有相同权限的用户。主账号可以通过创建用户组批量对用户进行授权与管理。

• 用户组只能由主账号创建和授权
• 用户组不能进行控制台登录

授权

主用户可以管理所有子用户以及用户分组的写权限。子用户可将自己拥有写权限的资源权限分配给其他子用户或者用户组。

• 如果用户UserA被加入用户组GroupA，那么UserA可以操作授权给GroupA的资源，但是GroupA无法操作UserA的资源。
• 如果用户UserA从用户组GroupA中被移除，那么UserA将无法操作授权给GroupA的资源。
• 默认策略只能编辑资源信息

资源操作凭据 Token

资源权限将通过token进行控制和管理，用户与用户组均可生成。

• 若用户UserA的token被禁用，则只能读取北极星的资源，但是无法创建、修改北极星的资源。
• 若用户组GroupA的token被禁用，则GroupA只能读取北极星的资源，但是无法创建、修改北极星的资源。

资源鉴权设计

未开启鉴权

• 命名空间、服务、配置分组的读写操作不受限制，任何人都可以对资源进行修改。

开启鉴权

• 开启鉴权前创建的资源，默认没有绑定鉴权策略，任何人都可以对资源进行修改。
• 鉴权行为仅针对有绑定策略的资源生效。
• 命名空间、服务、配置分组，创建之后默认仅能被管理员以及当前创建者进行读写操作。

命名空间

• 任何用户均可以创建命名空间
• 如果用户对该命名空间有写权限，则可以在该命名空间下创建服务以及配置分组。
• 用户可以在创建命名空间时，指定可以操作该命名空间的其他用户，或者用户组。

服务

• 用户可以在创建服务时，指定可以操作该服务的其他用户，或者用户组
• 如果用户对该服务有写权限，则可以对该服务的信息、实例进行操作。
• 如果用户对该服务有写权限，但是没有对应命名空间的写权限，也可以对该服务的信息、实例进行操作。

配置分组

• 如果用户对该配置分组有写权限，则可以对该配置分组的信息、配置文件进行操作。
• 如果用户对该配置分组有写权限，但是没有对应命名空间的写权限，也可以对该配置分组的信息、配置文件进行操作。

2.2.5.2 - 策略

服务端开启鉴权

• 修改服务端配置文件polaris-server.yaml

auth:
  # 鉴权插件
  name: defaultAuth
  option:
    # token 加密的 salt，鉴权解析 token 时需要依靠这个 salt 去解密 token 的信息
    # salt 的长度需要满足以下任意一个：len(salt) in [16, 24, 32]
    # 如有自定义需求，需要在首次部署时指定
    salt: polarismesh@2021
    # 控制台鉴权能力开关，默认开启
    consoleOpen: true
    # 客户端鉴权能力开关, 默认关闭
    clientOpen: false
    # 是否启用鉴权的严格模式，即对于没有任何鉴权策略的资源，也必须带上正确的用户/用户组 token 才能操作, 默认开启
    # 该配置项在 v1.17.2 版本开始舍弃，如果设置 strict == true, 则相当于 consoleStrict = true & clientStrict = false
    strict: false
    # 是否启用鉴权的严格模式，即对于没有任何鉴权策略的资源，也必须带上正确的用户/用户组 token 才能操作, 默认开启
    # 该配置项在 v1.17.2 版本开始启用
    consoleStrict: true
    # 是否启用鉴权的严格模式，即对于没有任何鉴权策略的资源，也必须带上正确的用户/用户组 token 才能操作, 默认关闭
    # 该配置项在 v1.17.2 版本开始启用
    clientStrict: false

• 若为VM部署，修改每个polaris部署节点中的polaris-server.yaml文件，修改完后执行以下命令进行重启polaris

  • Linux/MacOS
  • Windows

  bash tool/stop.sh
  bash tool/start.sh
  

  bash tool/stop.cmd
  bash tool/start.cmd
  

• 若为容器化部署，则先修改名称为polaris-server-config的configmap，修改完之后，执行以下命令触发polaris的滚动重启

  kubectl rollout restart statefulset polaris
  

• 如果有修改 salt 的需要，则需要按照以下步骤执行

  • 确定最终的 salt 值并将其修改至polaris-server.yaml中
  • 执行auth/defaultauth/token_test.go中的Test_CustomDesignSalt函数，生成新的token
  • 执行下列SQL

    INSERT INTO
        `user` (
            `id`,
            `name`,
            `password`,
            `source`,
            `token`,
            `token_enable`,
            `user_type`,
            `comment`,
            `owner`
        )
    VALUES
        (
            '65e4789a6d5b49669adf1e9e8387549c',
            'polaris',
            '$2a$10$5XMjs.oqo4PnpbTGy9dQqewL4eb4yoA7b/6ZKL33IPhFyIxzj4lRy',
            'Polaris',
            '${新的token}',
            1,
            20,
            'default polaris admin account',
            ''
        );
    

  • 这样就完成了主账户的token变更

如何创建鉴权策略

• 单击新建策略。填写策略基本信息，在角色栏可以选择需要授权用户或用户组，单击下一步选择授权的资源。

• 在资源栏可选择北极星的资源类型，包括命名空间、服务等资源，主账号可对所有资源进行操作。

• 单击下一步，进入预览界面，详细展示该策略涉及的用户、用户组以及资源。确认信息无误后，单击完成。

• 主账号可在权限策略列表查阅现有的权限策略，可单击编辑进行授权或删除等操作。

新建资源如何选择可操作用户

创建命名空间

在命名空间页面中，点击新建，在弹出页面中，点击高级选择可以操作本资源的用户或者用户组。

创建服务

在服务列表页面中，点击新建，在弹出页面中，点击高级选择可以操作本资源的用户或者用户组。

2.3 - Java 应用开发

2.3.1 - 使用 Java SDK

2.3.1.1 - 注册发现

引入依赖

修改应用根目录下的pom.xml，为 polaris-java 添加 dependencyManagement：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.tencent.polaris</groupId>
            <artifactId>polaris-dependencies</artifactId>
            <version>${version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

然后只需要在 标签中在添加 polaris-all 即可

<dependencies>
    <dependency>
        <groupId>com.tencent.polaris</groupId>
        <artifactId>polaris-all</artifactId>
    </dependency>
</dependencies>

初始化 polaris.yml

你需要在项目的 main/resources 下创建一个 polaris.yml 文件用于初始化 polaris-java SDK。polaris.yml 配置详细

服务注册

SDK实例构建

当初始化好 polaris.yml 文件之后，你可以直接 import com.tencent.polaris.factory.api.DiscoveryAPIFactory, 使用 DiscoveryAPIFactory 中的方法进行构造一个 ProviderAPI SDK 实例

import com.tencent.polaris.factory.api.DiscoveryAPIFactory;


public static void main(String[] args) throws Exception {
    ProviderAPI providerAPI = DiscoveryAPIFactory.createProviderAPI();
}

注册请求体

InstanceRegisterRequest request = new InstanceRegisterRequest();
// 设置实例所属服务信息
request.setService(service);
// 设置实例所属服务的命名空间信息
request.setNamespace(namespace);
// 设置实例的 host 信息
request.setHost(host);
// 设置实例的端口信息
request.setPort(port);
// 可选，资源访问Token，即用户/用户组访问凭据，仅当服务端开启客户端鉴权时才需配置
request.setToken(token);
// 设置实例版本
request.setVersion(version);
// 设置实例的协议
request.setProtocol(protocol);
// 设置实例权重
request.setWeight(weight);
// 设置实例的标签
request.setMetadata(metadata);
// 设置实例地理位置 zone 信息
request.setZone(zone);
// 设置实例地理位置 region 信息
request.setRegion(region);
// 设置实例地理位置 campus 信息
request.setCampus(campus);
// 设置心跳健康检查ttl，单位为s，不填默认为5s，TTL的取值范围为 (0s, 60s]
// 开启了心跳健康检查，客户端必须以TTL间隔上报心跳
// 健康检查服务器3个TTL未受到心跳则将实例置为不健康
request.setTtl(ttl);

发起注册请求

你在初始化完 InstanceRegisterRequest 结构体后，只需要调用 ProviderAPI.RegisterInstance 方法即可完成实例注册，并且 RegisterInstance 方法内部会自动维护实例的心跳上报。

InstanceRegisterResponse registerResp = providerAPI.registerInstance(registerRequest)

服务发现

SDK实例构建

当初始化好 polaris.yml 文件之后，你可以直接 import com.tencent.polaris.factory.api.DiscoveryAPIFactory, 使用 DiscoveryAPIFactory 中的方法进行构造一个 ConsumerAPI SDK 实例

import com.tencent.polaris.factory.api.DiscoveryAPIFactory;


public static void main(String[] args) throws Exception {
    ConsumerAPI consumerAPI = DiscoveryAPIFactory.createConsumerAPI();
}

发现服务实例

GetAllInstances

直接返回目标服务下的所有实例，包括不健康、隔离、权重为0、被熔断的实例，也会在返回的实例列表中。

GetAllInstancesRequest request = new GetAllInstancesRequest();
// 设置服务命名空间
request.setNamespace(String namespace);
// 设置服务名称
request.setService(String service);
// 设置超时时间
request.setTimeoutMs(long timeoutMs);

// 调用 ConsumerAPI 执行该请求
consumerAPI.getAllInstance(request);

GetHealthyInstances

每次获取一批可用服务提供者实例。

该方法默认会过滤掉不健康、隔离、权重为0、被熔断的实例。

GetInstancesRequest request = new GetInstancesRequest();
// 设置服务命名空间
request.setNamespace(String namespace);
// 设置服务名称
request.setService(String service);

// 可选，设置主调服务信息，只用于路由规则匹配
SourceService serviceInfo = new SourceService();
// 设置主调服务命名空间
serviceInfo.setNamespace(String namespace);
// 设置主调服务名称
serviceInfo.setService(String service);
// 设置主调方的请求标签信息
serviceInfo.setArguments(Set<RouteArgument> arguments);
request.setServiceInfo(serviceInfo);

// 设置超时时间
request.setTimeoutMs(long timeoutMs);

// 调用 ConsumerAPI 执行该请求
consumerAPI.getInstances(request);

GetOneInstances

每次仅获取一个可用服务提供者实例，该方法会依次执行路由、负载均衡流程。

该方法默认会过滤掉不健康、隔离、权重为0、被熔断的实例。

public class Criteria {
    /**
     * 指定负载均衡策略
     */
    private String lbPolicy;
    /**
     * 一致性hash的key
     */
    private String hashKey;
}

GetOneInstanceRequest request = new GetOneInstanceRequest();
// 设置服务命名空间
request.setNamespace(String namespace);
// 设置服务名称
request.setService(String service);
// 可选，元数据信息，仅用于dstMetadata路由插件的过滤
request.setMetadata(Map<String, String> metadata);
// 可选，设置元数据路由兜底措施
// 当前支持的元数据路由兜底措施如下
// - 默认不降级: METADATAFAILOVERNONE("metadataFailoverNone")
// - 降级返回所有节点: METADATAFAILOVERALL("metadataFailoverAll")
// - 返回不包含元数据路由key的节点: METADATAFAILOVERNOTKEY("metadataFailoverNoKey")
request.setMetadataFailoverType();
// 可选，对应自定义路由规则中请求标签中的方法(Method)
request.setMethod(String method);

// 如果需要走 Hash 负载均衡的话，需要设置
Criteria criteria = new Criteria();
request.setCriteria(criteria);

// 可选，设置主调服务信息，只用于路由规则匹配
SourceService serviceInfo = new SourceService();
// 设置主调服务命名空间
serviceInfo.setNamespace(String namespace);
// 设置主调服务名称
serviceInfo.setService(String service);
// 设置主调方的请求标签信息
serviceInfo.setArguments(Set<RouteArgument> arguments);
request.setServiceInfo(serviceInfo);

// 设置超时时间
request.setTimeoutMs(long timeoutMs);

// 调用 ConsumerAPI 执行该请求
consumerAPI.getOneInstance(request);

如何基于 polaris-java 客户端完成一个服务发现的程序

• 示例工程项目

2.3.1.2 - 动态路由

引入依赖

修改应用根目录下的pom.xml，为 polaris-java 添加 dependencyManagement：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.tencent.polaris</groupId>
            <artifactId>polaris-dependencies</artifactId>
            <version>${version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

然后只需要在 标签中在添加 polaris-all 即可

<dependencies>
    <dependency>
        <groupId>com.tencent.polaris</groupId>
        <artifactId>polaris-all</artifactId>
    </dependency>
</dependencies>

初始化 polaris.yml

你需要在项目的 main/resources 下创建一个 polaris.yml 文件用于初始化 polaris-java SDK。polaris.yml 配置详细

服务注册

SDK实例构建

当初始化好 polaris.yml 文件之后，你可以直接 import com.tencent.polaris.factory.api.RouterAPIFactory, 使用 RouterAPIFactory 中的方法进行构造一个 RouterAPI SDK 实例

import com.tencent.polaris.factory.api.RouterAPIFactory;

public static void main(String[] args) throws Exception {
    RouterAPI routerAPI = RouterAPIFactory.createRouterAPI();
}

注册请求体

ProcessRoutersRequest request = new ProcessRoutersRequest();/
// 被调服务命名空间
request.setNamespace();
// 被调服务名称
request.setService();
// 可选，对应自定义路由规则中请求标签中的方法(Method)
request.setMethod();
// 可选，设置主调服务信息，只用于路由规则匹配
SourceService serviceInfo = new SourceService();
// 设置主调服务命名空间
serviceInfo.setNamespace(String namespace);
// 设置主调服务名称
serviceInfo.setService(String service);
// 设置主调方的请求标签信息
serviceInfo.setArguments(Set<RouteArgument> arguments);
request.setSourceService(serviceInfo);
// 设置待参与路由的目标实例
request.setDstInstances();

ProcessRoutersRequest.RouterNamesGroup group = new ProcessRoutersRequest.RouterNamesGroup();
// 设置前置路由
group.setBeforeRouters();
// 设置业务路由
group.setCoreRouters();
// 设置后置路由
group.setAfterRouters();
// 可选，设置路由插件执行链
// 当前支持的路由插件类型如下
// - 就近路由: nearByRoute
// - 自定义路由: ruleRouter
// - 元数据路由: metadataRoute
request.setRouters();

执行服务路由

你在初始化完 ProcessRoutersRequest 结构体后，只需要调用 RouterAPI.processRouters 方法即可完成服务路由

ProcessRoutersResponse resp = routerAPI.processRouters(registerRequest)

如何基于 polaris-java 客户端完成一个服务路由的程序

• 示例工程项目

2.3.1.3 - 负载均衡

引入依赖

修改应用根目录下的pom.xml，为 polaris-java 添加 dependencyManagement：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.tencent.polaris</groupId>
            <artifactId>polaris-dependencies</artifactId>
            <version>${version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

然后只需要在 标签中在添加 polaris-all 即可

<dependencies>
    <dependency>
        <groupId>com.tencent.polaris</groupId>
        <artifactId>polaris-all</artifactId>
    </dependency>
</dependencies>

初始化 polaris.yml

你需要在项目的 main/resources 下创建一个 polaris.yml 文件用于初始化 polaris-java SDK。polaris.yml 配置详细

服务注册

SDK实例构建

当初始化好 polaris.yml 文件之后，你可以直接 import com.tencent.polaris.factory.api.RouterAPIFactory, 使用 RouterAPIFactory 中的方法进行构造一个 RouterAPI SDK 实例

import com.tencent.polaris.factory.api.RouterAPIFactory;

public static void main(String[] args) throws Exception {
    RouterAPI routerAPI = RouterAPIFactory.createRouterAPI();
}

负载均衡

public class Criteria {
    // 一致性hash的key
    private String hashKey;
}

ProcessLoadBalanceRequest request = new ProcessLoadBalanceRequest();
// 设置需要参与负载均衡的服务实例
request.setDstInstances(ServiceInstances dstInstances);
// 设置负载均衡策略
// 当前支持的负载均衡策略如下
// - 权重随机负载均衡: weightedRandom
// - 权重一致性负载均衡: ringHash
request.setLbPolicy(String lbPolicy);

// 如果需要走 Hash 负载均衡的话，需要设置
Criteria criteria = new Criteria();
request.setCriteria(criteria);

执行服务负载均衡

你在使用 ConsumerAPI.getAllInstances 或者 ConsumerAPI.getInstances 获取到服务实例列表后，完成 ProcessLoadBalanceRequest 初始化，只需要调用 RouterAPI.processLoadBalance 方法即可完成负载均衡

ProcessLoadBalanceResponse resp = routerAPI.processLoadBalance(request)

如何基于 polaris-java 客户端完成一个服务负载均衡的程序

• 示例工程项目

2.3.1.4 - 熔断降级

熔断整个服务

配置熔断规则

配置服务熔断规则，针对default命名空间下所有的服务，对于时延大于500毫秒，或者返回码为500的请求，标识为错误请求，一旦一分钟内错误率30%及以上或连续错误数在5个以上，则对服务进行熔断。

使用SDK进行熔断判断

方法说明

北极星Java SDK提供以下熔断相关的方法，所有的方法都在com.tencent.polaris.circuitbreak.api.CircuitBreakAPI接口中提供。

• check：检查资源是否可被调用，并对资源获取调用申请。对于半开的资源，如果半开的调用配额申请成功，返回true，否则返回false。
• report：该方法供用户在资源调用完成后，上报调用的结果，包括返回码、时延等信息，供熔断逻辑判断。
• makeFunctionalDecorator：创建一个函数调用装饰器FunctionalDecorator，装饰器可以对Java的函数接口进行装饰。装饰后的逻辑，会在函数逻辑调用前，先通过check方法检查资源是否可被调用，如果不能被调用，会抛出资源熔断异常（CallAbortedException）。调用完成后，会通过report接口上报本次调用结果。FunctionalDecorator包含以下方法：
  • decorateSupplier：对函数接口Supplier进行封装。
  • decorateConsumer：对函数接口Consumer进行封装。
  • decorateFunction：对函数Function进行封装。
  • decoratePredicate：对函数接口Predicate进行封装。

使用示例

// 创建CircuitBreakAPI实例
CircuitBreakAPI circuitBreakAPI = CircuitBreakAPIFactory.createCircuitBreakAPI();

// 通过传入服务名(testService1)和命名空间(default)，创建FunctionalDecorator
FunctionalDecoratorRequest makeDecoratorRequest = new FunctionalDecoratorRequest();
        makeDecoratorRequest.setService(new ServiceKey("default", "testService1"));
FunctionalDecorator decorator = circuitBreakAPI.makeFunctionalDecorator(makeDecoratorRequest);

// 封装函数接口
Consumer<Integer> integerConsumer = decorator.decorateConsumer(new Consumer<Integer>() {
    @Override
    public void accept(Integer object) {
      // 执行服务调用...
    }
});

// 通过执行函数接口，进行服务调用
// 在调用过程中，如果出现熔断，会抛出CallAbortedException异常
for (int i = 0; i < 500; i++) {
    try {
       integerConsumer.accept(i);
    } catch(CallAbortedException e) {
       e.printStackTrace();
    }
}

样例地址

Github地址

熔断单个接口

配置熔断规则

配置接口熔断规则，针对default命名空间所有服务的foo接口，对于时延大于500毫秒，或者返回码为500的请求，标识为错误请求，一旦一分钟内错误率30%及以上或连续错误数在5个以上，则对接口进行熔断。

使用SDK进行熔断判断

熔断所使用的SDK接口及方法与服务级熔断相同，这里不再重复介绍。

使用示例

// 创建CircuitBreakAPI实例
CircuitBreakAPI circuitBreakAPI = CircuitBreakAPIFactory.createCircuitBreakAPI();

// 通过传入服务名(testService1)、命名空间(default)和方法名(foo)，创建FunctionalDecorator
FunctionalDecoratorRequest makeDecoratorRequest = new FunctionalDecoratorRequest();
makeDecoratorRequest.setService(new ServiceKey("default", "testService1"));
makeDecoratorRequest.setMethod("foo");
FunctionalDecorator decorator = circuitBreakAPI.makeFunctionalDecorator(makeDecoratorRequest);

// 封装函数接口
Consumer<Integer> integerConsumer = decorator.decorateConsumer(new Consumer<Integer>() {
    @Override
    public void accept(Integer object) {
      // 执行服务接口调用...
    }
});

// 通过执行函数接口，进行服务调用
// 在调用过程中，如果出现熔断，会抛出CallAbortedException异常
for (int i = 0; i < 500; i++) {
    try {
       integerConsumer.accept(i);
    } catch(CallAbortedException e) {
       e.printStackTrace();
    }
}

样例地址

Github地址

熔断单个实例

配置熔断规则

配置实例熔断规则，针对default命名空间下所有的服务实例，对于时延大于500毫秒，或者返回码为500的请求，标识为错误请求，每个实例的错误率是单独统计的，一旦一分钟内错误率30%及以上或连续错误数在5个以上，则对被调实例（IP:PORT）进行熔断。

使用SDK进行熔断判断

当实例被熔断时，该实例会暂时不接收请求，原本路由到该实例的请求会路由到其他实例。这个过程在服务路由过程中自动完成，用户无需进行额外的熔断状态判断等操作。

引入依赖

修改应用根目录下的pom.xml，为 polaris-java 添加 dependencyManagement：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.tencent.polaris</groupId>
            <artifactId>polaris-dependencies</artifactId>
            <version>${version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

然后只需要在 标签中在添加 polaris-all 即可

<dependencies>
    <dependency>
        <groupId>com.tencent.polaris</groupId>
        <artifactId>polaris-all</artifactId>
    </dependency>
</dependencies>

配置北极星服务端地址

用户需要在项目的 main/resources 下创建一个 polaris.yml 文件用于初始化 polaris-java SDK。

global:
  serverConnector:
    # 北极星服务端地址，端口为8091
    addresses:
      - 127.0.0.1:8091

执行服务路由

import com.tencent.polaris.factory.api.DiscoveryAPIFactory;


public static void main(String[] args) throws Exception {
    CircuitBreakAPI circuitBreakAPI = CircuitBreakAPIFactory.createCircuitBreakAPI();
    ConsumerAPI consumerAPI = DiscoveryAPIFactory.createConsumerAPI();
    // 执行服务路由，筛选出单个实例，在这个过程中，会自动剔除熔断的实例
    GetOneInstanceRequest getOneInstanceRequest = new GetOneInstanceRequest();
    getOneInstanceRequest.setNamespace("default");
    getOneInstanceRequest.setService("testService1");
    InstancesResponse oneInstance = consumerAPI.getOneInstance(getOneInstanceRequest);
    Instance targetInstance = oneInstance.getInstances()[0];
    // 执行服务调用 --- 伪代码
    httpResult, delay = rpc(targetInstance.host, targetInstance.port, body);

    // invoke rpc call with targetInstance
    InstanceResource instanceResource = new InstanceResource(new ServiceKey(namespace, service),
            targetInstance.getHost(), targetInstance.getPort(), sourceService.getServiceKey());
    circuitBreakAPI.report(new ResourceStat(instanceResource, httpResult.code, delay));
}

样例地址

Github地址

启用主动探测

业务往往会存在高峰期和低峰期，低峰期流量比较少，不足以触发熔断，会出现当部分实例出现数据不可达的问题时，没法及时发现，导致高峰期到来时出现故障。

主动探测可以解决这个问题，启用主动探测后，主调方会定时根据探测规则，对被调实例进行探测，探测结果可作为熔断的判断依据，可实现对故障资源的快速熔断。

配置主动探测规则

配置一个主动探测规则，对服务（名为testService1，命名空间为default）进行探测。探测使用的协议是HTTP协议，由于服务开启了鉴权，因此探测时需要传入鉴权头。

注意：主动探测的规则，服务名可以选择全部服务，则规则针对全部服务生效。如果需要针对只接口进行探测，则可以在接口字段中填入对应的接口名。

在熔断规则中开启主动探测

需要在熔断规则中开启探测，这样才可以把探测结果用于熔断。

2.3.1.5 - 访问限流

引入依赖

修改应用根目录下的pom.xml，为 polaris-java 添加 dependencyManagement：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.tencent.polaris</groupId>
            <artifactId>polaris-dependencies</artifactId>
            <version>${version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

然后只需要在 标签中在添加 polaris-all 即可

<dependencies>
    <dependency>
        <groupId>com.tencent.polaris</groupId>
        <artifactId>polaris-all</artifactId>
    </dependency>
</dependencies>

初始化 polaris.yml

你需要在项目的 main/resources 下创建一个 polaris.yml 文件用于初始化 polaris-java SDK。polaris.yml 配置详细

SDK实例构建

当初始化好 polaris.yml 文件之后，你可以直接 import com.tencent.polaris.ratelimit.factory, 使用 LimitAPIFactory 中的方法进行构造一个 ProviderAPI SDK 实例

import com.tencent.polaris.ratelimit.factory.LimitAPIFactory;


public static void main(String[] args) throws Exception {
    LimitAPI limitAPI = LimitAPIFactory.createLimitAPI();
}

请求配额

QuotaRequest quotaRequest = new QuotaRequest();
// 设置需要进行限流的服务信息：设置命名空间信息
quotaRequest.setNamespace(String namespace);
// 设置需要进行限流的服务信息：设置服务名称信息
quotaRequest.setService(String service);
// 设置本次被调用的方法信息
quotaRequest.setMethod(String method);
// 设置本次的请求标签
quotaRequest.setArguments(Set<Argument> arguments)
// 设置需要申请的请求配额数量
quotaRequest.setCount(1);

发起配额申请请求

你在初始化完 QuotaRequest 结构体后，只需要调用 LimitAPI.getQuota 方法即可完成服务限流

QuotaResponse resp = limitAPI.getQuota(registerRequest)

分布式限流使用

如果要使用分布式限流，请先确保已经部署了北极星分布式限流 server

• VM 机器部署限流服务
• Kubernetes 机器部署限流服务

部署完后确认北极星控制台存在服务 命名空间: Polaris, 服务名: polaris.limiter。

确认完毕后，调整 polaris.yml 配置文件，在控制台配置分布式限流规则，SDK 仍然使用 QuotaResponse resp = limitAPI.getQuota(registerRequest) 即可。

provider:
  rateLimit:
    enable: true
	limiterNamespace: Polaris
	limiterService: polaris.limiter

如何基于 polaris-java 客户端完成一个服务限流的程序

• 示例工程项目

2.3.1.6 - 配置管理

引入依赖

修改应用根目录下的pom.xml，为 polaris-java 添加 dependencyManagement：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.tencent.polaris</groupId>
            <artifactId>polaris-dependencies</artifactId>
            <version>${version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

然后只需要在 标签中在添加 polaris-all 即可

<dependencies>
    <dependency>
        <groupId>com.tencent.polaris</groupId>
        <artifactId>polaris-all</artifactId>
    </dependency>
</dependencies>

初始化 polaris.yml

你需要在项目的 main/resources 下创建一个 polaris.yml 文件用于初始化 polaris-java SDK。polaris.yml 配置详细

SDK实例构建

当初始化好 polaris.yml 文件之后，你可以直接 import com.tencent.polaris.configuration.factory, 使用 ConfigFileServiceFactory 中的方法进行构造一个 ConfigFileService SDK 实例

import com.tencent.polaris.configuration.factory.ConfigFileServiceFactory;

public static void main(String[] args) throws Exception {
    ConfigFileService configFileService = ConfigFileServiceFactory.createConfigFileService();
}

配置文件读取操作

// 获取特定远程的配置文件
ConfigFile configFile = configFileService.getConfigFile(String namespace, String fileGroup, String fileName);
System.out.println(configFile.getContent());

对配置文件发起监听

//获取配置文件
ConfigFile configFile = configFileService.getConfigFile(namespace, fileGroup, fileName);
//添加变更监听器
configFile.addChangeListener(new ConfigFileChangeListener() {
	@Override
	public void onChange(ConfigFileChangeEvent event) {
	}
});

查询加密配置

需要更新 polaris-java 的版本至 v1.13.0 +

// 获取特定远程的配置文件
ConfigFile getConfigFile(String namespace, String fileGroup, String fileName);

// 获取特定远程的配置文件
ConfigFile getConfigFile(ConfigFileMetadata configFileMetadata);

调整 polaris.yml 配置文件

# 配置中心默认配置
config:
  # 配置过滤器
  configFilter:
    enable: true
    chain:
      # 启用配置解密插件
      - crypto
    plugin:
      crypto:
        # 配置解密插件的算法插件类型
        type: AES

监听配置分组下的已发布文件列表变化

需要更新 polaris-java 的版本至 v1.14.0 及以上版本, 获取到目标配置分组后, 调用配置分组的 addChangeListener 方法监听改配置分组下已发布配置文件列表的变化

ConfigFileGroup configFileGroup = configFileService.getConfigFileGroup(namespace, fileGroup);
if (configFileGroup != null) {
    configFileGroup.addChangeListener(new ConfigFileGroupChangeListener() {
        @Override
        public void onChange(ConfigFileGroupChangedEvent event) {
            Utils.print(event.toString());
        }
    });
}

ConfigFileGroupChangedEvent 结构体的具体信息

public class ConfigFileGroupChangedEvent {
    // 配置分组自身元数据信息
    private final ConfigFileGroupMetadata configFileGroupMetadata;
    // 当前配置分组下的最新已发布的配置文件列表
    private final List<ConfigFileMetadata> configFileMetadataList;

    public ConfigFileGroupChangedEvent(ConfigFileGroupMetadata configFileGroupMetadata, List<ConfigFileMetadata> configFileMetadataList) {
        this.configFileGroupMetadata = configFileGroupMetadata;
        this.configFileMetadataList = configFileMetadataList;
    }

    public ConfigFileGroupMetadata getConfigFileGroupMetadata() {
        return configFileGroupMetadata;
    }

    public List<ConfigFileMetadata> getConfigFileMetadataList() {
        return configFileMetadataList;
    }

    @Override
    public String toString() {
        return "ConfigFileGroupChangedEvent{" +
                "configFileGroupMetadata=" + configFileGroupMetadata +
                ", configFileMetadataList=" + configFileMetadataList +
                '}';
    }
}

配置文件修改操作

使用 ConfigFileServicePublishFactory 中的方法进行构造一个 ConfigFilePublishService SDK 实例

import com.tencent.polaris.configuration.factory.ConfigFileServicePublishFactory;

public static void main(String[] args) throws Exception {
    ConfigFilePublishService configFilePublishService = ConfigFileServicePublishFactory.createConfigFilePublishService();
}

操作配置文件的方法

// 创建配置文件
void createConfigFile(String namespace, String fileGroup, String fileName, String content);

// 创建配置文件
void createConfigFile(ConfigFileMetadata configFileMetadata, String content);

// 修改配置文件
void updateConfigFile(String namespace, String fileGroup, String fileName, String content);

// 修改配置文件
void updateConfigFile(ConfigFileMetadata configFileMetadata, String content);

// 发布配置文件
void releaseConfigFile(String namespace, String fileGroup, String fileName);

// 发布配置文件
void releaseConfigFile(ConfigFileMetadata configFileMetadata);

相关示例工程代码

• 如何基于 polaris-java 客户端完成一个配置拉取
• 如何基于 polaris-java 客户端完成配置创建、发布
• 如何基于 polaris-java 客户端完成一个配置分组下发布文件列表的拉取

2.3.1.7 - 可观测性

引入依赖

修改应用根目录下的pom.xml，为 polaris-java 添加 dependencyManagement：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.tencent.polaris</groupId>
            <artifactId>polaris-dependencies</artifactId>
            <version>${version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

然后只需要在 标签中在添加 polaris-all 即可

<dependencies>
    <dependency>
        <groupId>com.tencent.polaris</groupId>
        <artifactId>polaris-all</artifactId>
    </dependency>
</dependencies>

通过配置文件 polaris.yml 开启监控上报

你需要在项目的 main/resources 下创建一个 polaris.yml 文件用于初始化 polaris-java SDK。polaris.yml 配置详细

通过 prometheus pull 模式上报监控数据

global:
  #描述: 监控及日志数据上报相关配置
  statReporter:
    #描述: 是否启用上报
    enable: true
    plugin:
      prometheus:
        type: pull
        #描述: 设置 prometheus http-server 的监听端口
        #类型:int
        #默认值: 28080
        #如果设置为负数，则不会开启默认的http-server，如果设置为0，则随机选择一个可用端口进行启动 http-server
        port: 28080
        #描述: 设置 prometheus http-server 的拉取path
        #类型:string
        #默认值: /metric
        path: /metric

通过 pushgateway push 模式上报监控数据

global:
  #描述: 监控及日志数据上报相关配置
  statReporter:
    #描述: 是否启用上报
    enable: true
    plugin:
      prometheus:
        type: push
        #描述: 设置 pushgateway 的地址, 仅 type == push 时生效
        #类型:string
        address: 127.0.0.1:9091
        #描述:设置metric数据推送到pushgateway的执行周期, 仅 type == push 时生效
        #类型:string
        #格式:^\d+(s|m|h)$
        #范围:[1s:...]
        #默认值:10s
        pushInterval: 10s