# polaris-wiki
**Repository Path**: polaris-paas/polaris-wiki
## Basic Information
- **Project Name**: polaris-wiki
- **Description**: ⭐⭐⭐⭐⭐
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: http://www.nepxion.com
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-05-31
- **Last Updated**: 2024-09-04
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Polaris【北极星】云原生微服务解决方案
[](https://github.com/Nepxion/Discovery/wiki) [](https://gitee.com/nepxion/Discovery/wikis/pages?sort_id=3993615&doc_id=1124387) [](https://nepxion.github.io/Discovery/docs/link-doc/discovery-ppt.html) [](https://nepxion.github.io/Discovery/) [](https://nepxion.github.io/DiscoveryPlatform) [](https://nepxion.github.io/DiscoveryDesktop) [](https://polaris-paas.github.io/polaris-wiki)
如果您觉得本框架具有一定的参考价值和借鉴意义，请帮忙在页面右上角 [**Star**]
## 简介
### 作者简介
- Nepxion开源社区创始人
- 2020年阿里巴巴中国云原生峰会出品人
- 2020年被Nacos和Spring Cloud Alibaba纳入相关开源项目
- 2021年阿里巴巴技术峰会上海站演讲嘉宾
- 2021年荣获陆奇博士主持的奇绩资本，进行风险投资的关注和调研
- 2021年入选Gitee最有价值开源项目
- 阿里巴巴官方书籍《Nacos架构与原理》作者之一
- Spring Cloud Alibaba Steering Committer、Nacos Group Member
- Spring Cloud Alibaba、Nacos、Sentinel、OpenTracing Committer & Contributor
### 商业合作
① Discovery系列
| 框架名称 | 框架版本 | 支持Spring Cloud版本 | 使用许可 |
| --- | --- | --- | --- |
| Discovery | 1.x.x ~ 6.x.x | Camden ~ Hoxton | 开源，永久免费 |
| DiscoveryX | 7.x.x + | 2020 + | 闭源，商业许可 |
② Polaris系列
Polaris为Discovery高级定制版，特色功能
- 基于Nepxion Discovery集成定制
- 多云、多活、多机房流量调配
- 跨云动态域名、跨环境适配
- DCN、DSU、SET单元化部署
- 组件灵活装配、配置对外屏蔽
- 极简低代码PaaS平台
| 框架名称 | 框架版本 | 支持Discovery版本 | 支持Spring Cloud版本 | 使用许可 |
| --- | --- | --- | --- | --- |
| Polaris | 1.x.x | 6.x.x | Finchley ~ Hoxton | 闭源，商业许可 |
| Polaris | 2.x.x | 7.x.x + | 2020 + | 闭源，商业许可 |
有商业版需求的企业和用户，请添加微信1394997，联系作者，洽谈合作事宜
### 入门资料
 Polaris【北极星】企业级云原生微服务商业解决方案
① 解决方案
- [解决方案WIKI版](http://nepxion.com/polaris)
② 框架源码
- [框架源码Github版](https://github.com/polaris-paas/polaris-sdk)
- [框架源码Gitee版](https://gitee.com/polaris-paas/polaris-sdk)
③ 指南示例源码
- [指南示例源码Github版](https://github.com/polaris-paas/polaris-guide)
- [指南示例源码Gitee版](https://gitee.com/polaris-paas/polaris-guide)
④ 指南示例说明
- Spring Cloud Finchley ~ Hoxton版本
- [指南示例](https://github.com/polaris-paas/polaris-guide/tree/1.x.x)，分支为1.x.x
- Spring Cloud 20xx版本
- [指南示例](https://github.com/polaris-paas/polaris-guide/tree/master)，分支为master
 Discovery【探索】企业级云原生微服务开源解决方案
① 快速入门
- [快速入门Github版](https://github.com/Nepxion/Discovery/wiki)
- [快速入门Gitee版](https://gitee.com/Nepxion/Discovery/wikis/pages)
② 解决方案
- [解决方案WIKI版](http://nepxion.com/discovery)
- [解决方案PPT版](https://nepxion.github.io/Discovery/docs/link-doc/discovery-ppt.html)
③ 最佳实践
- [最佳实践PPT版](https://nepxion.github.io/Discovery/docs/link-doc/discovery-ppt-1.html)
④ 平台桌面
- [平台界面WIKI版](http://nepxion.com/discovery-platform)
- [图形桌面WIKI版](http://nepxion.com/discovery-desktop)
⑤ 框架源码
- [框架源码Github版](https://github.com/Nepxion/Discovery)
- [框架源码Gitee版](https://gitee.com/Nepxion/Discovery)
⑥ 指南示例源码
- [指南示例源码Github版](https://github.com/Nepxion/DiscoveryGuide)
- [指南示例源码Gitee版](https://gitee.com/Nepxion/DiscoveryGuide)
⑦ 指南示例说明
- Spring Cloud Finchley ~ Hoxton版本
- [极简版指南示例](https://github.com/Nepxion/DiscoveryGuide/tree/6.x.x-simple)，分支为6.x.x-simple
- [极简版域网关部署指南示例](https://github.com/Nepxion/DiscoveryGuide/tree/6.x.x-simple-domain-gateway)，分支为6.x.x-simple-domain-gateway
- [极简版非域网关部署指南示例](https://github.com/Nepxion/DiscoveryGuide/tree/6.x.x-simple-non-domain-gateway)，分支为6.x.x-simple-non-domain-gateway
- [集成版指南示例](https://github.com/Nepxion/DiscoveryGuide/tree/6.x.x)，分支为6.x.x
- [高级版指南示例](https://github.com/Nepxion/DiscoveryGuide/tree/6.x.x-complex)，分支为6.x.x-complex
- Spring Cloud 20xx版本
- [极简版指南示例](https://github.com/Nepxion/DiscoveryGuide/tree/master-simple)，分支为master-simple
- [极简版本地化指南示例](https://github.com/Nepxion/DiscoveryGuide/tree/master-simple-native)，分支为master-simple-native
- [集成版指南示例](https://github.com/Nepxion/DiscoveryGuide/tree/master)，分支为master
### 架构拓扑
 Discovery【探索】和Polaris【北极星】架构体系
① Discovery【探索】和Polaris【北极星】联合架构图
② Discovery【探索】和Polaris【北极星】联合拓扑图
③ Polaris【北极星】分层架构图
### 前言开篇
① 云原生（Cloud Native）定义
英文版定义
> Cloud native technologies empower organizations to build and run scalable applications in modern, dynamic environments such as public, private, and hybrid clouds. Containers, service meshes, microservices, immutable infrastructure, and declarative APIs exemplify this approach.
> These techniques enable loosely coupled systems that are resilient, manageable, and observable. Combined with robust automation, they allow engineers to make high-impact changes frequently and predictably with minimal toil.
> The Cloud Native Computing Foundation seeks to drive adoption of this paradigm by fostering and sustaining an ecosystem of open source, vendor-neutral projects. We democratize state-of-the-art patterns to make these innovations accessible for everyone.
中文版定义
> 云原生技术有利于各组织在公有云、私有云和混合云等新型动态环境中，构建和运行可弹性扩展的应用。云原生的代表技术包括容器、服务网格、微服务、不可变基础设施和声明式API。
> 这些技术能够构建容错性好、易于管理和便于观察的松耦合系统。结合可靠的自动化手段，云原生技术使工程师能够轻松地对系统作出频繁和可预测的重大变更。
> 云原生计算基金会（CNCF）致力于培育和维护一个厂商中立的开源生态系统，来推广云原生技术。我们通过将最前沿的模式民主化，让这些创新为大众所用。
-- 摘自Github CNCF官网[CNCF Cloud Native Definition v1.0](https://github.com/cncf/toc/blob/master/DEFINITION.md)
② 云原生（Cloud Native）要素
Pivotal官网对云原生概括为4个要素，如下
| 要素 | 描述 |
| --- | --- |
| Micro Service | 微服务 |
| Container | 容器 |
| DevOps | 开发运维一体化，包含CI（Continuous Integration）持续集成 |
| CD | 持续交付（Continuous Delivery） |
③ 云原生（Cloud Native）所需能力与特征
 下文着重刻画`Micro Service`的架构，阐述`DevOps`的边界，展现`Container`的落地，但不涉及`CD`的层面
### 功能概述
Polaris【北极星】企业级云原生微服务基础架构脚手架，低代码集成平台，围绕Discovery【探索】框架打造，基于Spring Cloud Discovery服务注册发现、Ribbon负载均衡、Feign和RestTemplate调用等组件全方位增强的企业级云原生微服务开源解决方案，面向企业级生产需求精雕细琢，赋能和助力企业快速搭建基础架构的底层云原生微服务框架，有效的降低企业的落地成本。整个架构体系打造，遵循最严格的Maven对称结构和规范，最严格的命名格式，给予使用者最舒适的使用体验
支持如下中间件的集成和封装
- 支持阿里巴巴Spring Cloud Alibaba中间件生态圈
- 支持阿里巴巴Nacos、Eureka、Consul和Zookeeper四个服务注册发现中心
- 支持阿里巴巴Nacos、携程Apollo、Redis、Zookeeper、Consul和Etcd六个远程配置中心
- 支持阿里巴巴Sentinel、Hystrix和Resilience4J三个熔断限流降级权限中间件
- 支持OpenTracing和OpenTelemetry规范下的调用链中间件，Jaeger、SkyWalking和Zipkin等
- 支持Prometheus Micrometer和Spring Boot Admin两个指标中间件
- 支持Java Agent解决异步跨线程ThreadLocal上下文传递
- 支持Spring Spel解决蓝绿灰度参数的驱动逻辑
- 支持Spring Matcher解决元数据匹配的通配逻辑
- 支持Spring Cloud Gateway、Zuul网关和微服务三大模块的蓝绿灰度发布等一系列功能
- 支持Spring Cloud Gateway、Zuul网关、微服务、控制台和自动化测试五个独立的应用层
- 支持和兼容Spring Cloud Edgware版、Finchley版、Greenwich版、Hoxton版和20xx版以及更高的Spring Cloud版本。默认集成Hoxton版，如果需要，请使用者自行适配成其它版本
- 支持和兼容Java8～Java17以及更高的SDK版本
支持如下应用型的功能
- 支持蓝绿灰度发布、路由过滤、流量权重、限流、熔断、降级、隔离、监控、追踪等企业生产级功能
- 支持动态域名、双云双活和SET单元化的配置，支持跨云的服务注册和配置读取（例如，阿里云上的微服务想要注册到华为云上的Nacos注册中心，或者跨云读取Apollo配置中心的配置，通过DevOps修改相关配置驱动即可）。一套SDK体系可以同时适配和运行在不同的云上
- 支持在核心的pom.xml上实现同类型的组件的快速切换（例如，Eureka注册中心切换到Consul，Apollo配置中心切换到Nacos等），但同类型组件不可并存使用（例如，Eureka和Consul注册中心不可同时并存，Apollo和Nacos配置中心不可同时并存等）
- 支持框架层面实现每个组件对四个环境（DEV | FAT | UAT | PRO）的内置最佳配置，遵循全局公共配置和局部环境配置相结合的方式，遵循【约定大于配置】的策略，业务层面实现微量配置甚至零配置。框架集成人员可以内置定制化的配置，业务开发人员在业务层可以把内置的配置覆盖掉，达到扩展性强、灵活使用的目的
- 支持业务开发人员使用该框架的时候，对其尽最大可能屏蔽一切跟Spring Cloud和中间件有关的代码书写、配置参数、环境地址等，零Spring Cloud经验的业务开发人员也可以快速上手研发基于Spring Cloud微服务技术栈的业务服务，最大程度上减轻业务人员的压力
### 请联系我
微信、钉钉、公众号和文档
## 目录
- [简介](#简介)
- [作者简介](#作者简介)
- [商业合作](#商业合作)
- [入门资料](#入门资料)
- [架构拓扑](#架构拓扑)
- [前言开篇](#前言开篇)
- [功能概述](#功能概述)
- [请联系我](#请联系我)
- [主页链接](#主页链接)
- [源码主页](#源码主页)
- [发布主页](#发布主页)
- [指南主页](#指南主页)
- [入门主页](#入门主页)
- [文档主页](#文档主页)
- [博客主页](#博客主页)
- [工程架构](#工程架构)
- [工程清单](#工程清单)
- [架构核心](#架构核心)
- [集成步骤](#集成步骤)
- [Parent切换](#Parent切换)
- [组织命名切换](#组织命名切换)
- [版本切换](#版本切换)
- [组件切换](#组件切换)
- [注册发现组件切换](#注册发现组件切换)
- [配置组件切换](#配置组件切换)
- [调用链组件切换](#调用链组件切换)
- [指标组件切换](#指标组件切换)
- [防护组件切换](#防护组件切换)
- [注解切换](#注解切换)
- [配置切换](#配置切换)
- [域名和环境切换](#域名和环境切换)
- [域名和环境解析](#域名和环境解析)
- [域名和环境设置](#域名和环境设置)
- [使用步骤](#使用步骤)
- [应用搭建](#应用搭建)
- [引入Parent](#引入Parent)
- [引入Jar](#引入Jar)
- [添加注解](#添加注解)
- [添加配置](#添加配置)
- [应用启动](#应用启动)
- [中间件服务启动](#中间件服务启动)
- [Spring-Boot应用启动](#Spring-Boot应用启动)
- [SkyWalking-Agent启动](#SkyWalking-Agent启动)
- [Polaris-Agent启动](#Polaris-Agent启动)
- [启动参数](#启动参数)
- [Agent启动参数](#Agent启动参数)
- [Nepxion-Discovery启动参数](#Nepxion-Discovery启动参数)
- [验证结果](#验证结果)
- [Postman方式验证](#Postman方式验证)
- [自动化测试方式验证](#自动化测试方式验证)
- [新增组件](#新增组件)
- [组件创建](#组件创建)
- [组件聚合](#组件聚合)
- [Spring-Boot-2-3-x新特性](#Spring-Boot-2-3-x新特性)
- [容器化部署](#容器化部署)
- [部署Polaris框架包](#部署Polaris框架包)
- [添加Spring-Boot打包插件](#添加Spring-Boot打包插件)
- [执行Docker容器和镜像的制作和运行](#执行Docker容器和镜像的制作和运行)
- [优雅停机](#优雅停机)
## 主页链接
### 源码主页
[Discovery源码主页](https://github.com/Nepxion/Discovery)
[Polaris源码主页](https://github.com/polaris-paas/polaris-sdk)
### 发布主页
[DiscoveryAgent](https://github.com/Nepxion/DiscoveryAgent/releases)
[DiscoveryDesktop](https://github.com/Nepxion/DiscoveryUI/releases)
### 指南主页
[Discovery指南主页](https://github.com/Nepxion/DiscoveryGuide)
[Polaris指南主页](https://github.com/polaris-paas/polaris-guide)
### 入门主页
[Gitee Wiki](https://gitee.com/Nepxion/Discovery/wikis/pages)
[Github Wiki](https://github.com/Nepxion/Discovery/wiki)
### 文档主页
[文档主页](https://gitee.com/Nepxion/Discovery/tree/wiki/docs/web-doc)
### 博客主页
[博客主页](https://blog.csdn.net/u012410733/category_10633202.html?spm=1001.2014.3001.5482)
## 工程架构
### 工程清单
工程集成了众多的中间件，清单如下
① 简略清单
- 核心组件
| 核心组件名 | 组件类型 |
| --- | --- |
| 
旗标组件 | Nepxion Discovery |
| 注册发现组件 | Nacos & Eureka & Consul & Zookeeper |
| 配置组件 | Apollo & Nacos |
| 调用链组件 | SkyWalking + OpenTracing & Jaeger + OpenTracing |
| 指标组件 | Prometheus Micrometer & Spring Boot Admin |
| 防护组件 | Sentinel & Hystrix |
| 蓝绿灰度组件 | Nepxion Discovery |
| 环境组件 | Nepxion Polaris内置 |
| 控制台组件 | Nepxion Discovery |
| 自动化测试组件 | Nepxion Discovery |
- 框架分层
| 框架分层名 | 分层类型 |
| --- | --- |
| Gateway网关层 | Spring Cloud Gateway + Nepxion Discovery |
| Zuul网关层 | Spring Cloud Netfilx Zuul + Nepxion Discovery |
| 微服务层 | Spring Cloud Service + Nepxion Discovery |
| 控制台层 | Spring Cloud Service + Nepxion Discovery |
| 测试层 | Spring Boot + Nepxion Discovery |
② 详细清单
| 工程名 | 描述 |
| --- | --- |
| 
polaris-parent | Polaris Parent定义 |
| 
polaris-sdk | Polaris SDK目录 |
| polaris-component | Polaris组件目录 |
| 
polaris-component-common | Polaris通用组件 |
| polaris-component-env | Polaris环境组件，支持动态域名、双云双活和SET单元化
支持DEV、FAT、UAT、PRO四个环境配置动态读取 |
| polaris-component-banner | Polaris旗标组件目录 |
| polaris-component-banner-starter | Polaris旗标组件，启动时显示旗标和重要中间件版本号信息 |
| polaris-component-discovery | Polaris 注册发现组件目录 |
| polaris-component-discovery-starter-nacos | Polaris Nacos注册发现组件的封装 |
| polaris-component-discovery-starter-consul | Polaris Consul注册发现组件的封装 |
| polaris-component-discovery-starter-eureka | Polaris Eureka注册发现组件的封装 |
| polaris-component-discovery-starter-zookeeper | Polaris Zookeeper注册发现组件的封装 |
| polaris-component-discovery-starter | Polaris注册发现组件的聚合和组装 |
| polaris-component-config | Polaris 配置组件目录 |
| polaris-component-config-starter-apollo | Polaris Apollo配置组件的封装 |
| polaris-component-config-starter-apollo-console | Polaris控制台集成Apollo配置组件的封装 |
| polaris-component-config-starter-apollo-sentinel | Polaris Sentinel集成Apollo配置组件的封装 |
| polaris-component-config-starter-nacos | Polaris Nacos配置组件的封装 |
| polaris-component-config-starter-nacos-console | Polaris控制台集成Nacos配置组件的封装 |
| polaris-component-config-starter-nacos-sentinel | Polaris Sentinel集成Nacos配置组件的封装 |
| polaris-component-config-starter | Polaris配置组件的聚合和组装 |
| polaris-component-tracing | Polaris调用链组件目录 |
| polaris-component-tracing-starter-jaeger | Polaris Jaeger调用链组件的封装 |
| polaris-component-tracing-starter-jaeger-sentinel | Polaris Jaeger调用链组件集成Sentinel的封装 |
| polaris-component-tracing-starter-skywalking | Polaris SkyWalking调用链组件的封装 |
| polaris-component-tracing-starter-skywalking-sentinel | Polaris SkyWalking调用链组件集成Sentinel的封装 |
| polaris-component-tracing-starter | Polaris调用链组件的聚合和组装 |
| polaris-component-metrics | Polaris指标组件目录 |
| polaris-component-metrics-starter-micrometer | Polaris Micrometer指标组件的封装 |
| polaris-component-metrics-starter-micrometer-sentinel | Polaris Micrometer Sentinel指标组件的封装 |
| polaris-component-metrics-starter-spring-boot-admin | Polaris Spring Boot Admin指标组件的封装 |
| polaris-component-metrics-starter | Polaris指标组件的聚合和组装 |
| polaris-component-protector | Polaris防护组件目录 |
| polaris-component-protector-starter-sentinel-common | Polaris Sentinel防护组件通用模块 |
| polaris-component-protector-starter-sentinel-gateway | Polaris Sentinel防护组件集成Spring Cloud Gateway网关的封装 |
| polaris-component-protector-starter-sentinel-zuul | Polaris Sentinel防护组件集成Zuul网关的封装 |
| polaris-component-protector-starter-sentinel-service | Polaris Sentinel防护组件集成微服务的封装 |
| polaris-component-protector-starter-hystrix | Polaris支持Hystrix防护组件跨线程异步调用 |
| polaris-component-protector-starter-gateway | Polaris防护组件集成Spring Cloud Gateway网关的聚合和组装 |
| polaris-component-protector-starter-zuul | Polaris防护组件集成Zuul网关的聚合和组装 |
| polaris-component-protector-starter-service | Polaris防护组件集成微服务的聚合和组装 |
| polaris-component-gray | Polaris蓝绿灰度组件目录 |
| polaris-component-gray-starter-common | Polaris蓝绿灰度组件通用模块 |
| polaris-component-gray-starter-gateway | Polaris蓝绿灰度组件集成Spring Cloud Gateway网关的封装 |
| polaris-component-gray-starter-zuul | Polaris蓝绿灰度组件集成Zuul网关的封装 |
| polaris-component-gray-starter-service | Polaris蓝绿灰度组件集成微服务的封装 |
| polaris-component-console | Polaris控制台组件目录 |
| polaris-component-console-starter | Polaris控制台组件的封装 |
| polaris-component-test | Polaris测试组件目录 |
| polaris-component-test-starter-automation | Polaris自动化测试组件 |
| polaris-component-test-starter | Polaris测试组件的聚合和组装 |
| polaris-framework | Polaris框架目录 |
| polaris-framework-starter-api | Polaris框架对微服务API二方包的封装，主要是对Feign的封装 |
| polaris-framework-starter-service | Polaris框架对微服务的封装 |
| polaris-framework-starter-gateway | Polaris框架对Spring Cloud Gateway网关的封装 |
| polaris-framework-starter-zuul | Polaris框架对Zuul网关的封装 |
| polaris-framework-starter-console | Polaris框架对控制台的封装 |
| polaris-framework-starter-test | Polaris框架对测试的封装 |
### 架构核心
架构核心位于polaris-framework下，包含如下6个顶级框架层
- polaris-framework-starter-api
- polaris-framework-starter-service
- polaris-framework-starter-gateway
- polaris-framework-starter-zuul
- polaris-framework-starter-console
- polaris-framework-starter-test
以polaris-framework-starter-service为例，展现出高度对称统一的架构美感
```xml
polaris-framework-starter-service
Nepxion Polaris Framework Starter Service
jar
4.0.0
com.nepxion.polaris
polaris-framework
1.0.0
${project.groupId}
polaris-component-banner-starter
${project.version}
${project.groupId}
polaris-component-discovery-starter
${project.version}
${project.groupId}
polaris-component-config-starter
${project.version}
${project.groupId}
polaris-component-tracing-starter
${project.version}
${project.groupId}
polaris-component-metrics-starter
${project.version}
${project.groupId}
polaris-component-protector-starter-service
${project.version}
${project.groupId}
polaris-component-gray-starter-service
${project.version}
```
## 集成步骤
### Parent切换
- 框架提供Polaris Parent，定义了Spring Cloud、Spring Cloud Alibaba和Spring Boot版本号，同时在Polaris SDK上也进行了这些版本的相同定义，目的是让业务开发人员可以接入Polaris的时候可以选择Polaris Parent，也可以选择业务自己的Parent，只接入Polaris SDK
- 当接入Polaris Parent的时候，版本号以Polaris Parent定义为优先，否则以Polaris SDK定义为准
### 组织命名切换
使用者可以把Polaris改造成自己企业名义上的框架。假设，企业名称为alibaba
① 全局替换Pom GroupId和src/main/resources/META-INF/spring.factories。在根目录下，搜索全部文件，关键字
```
com.nepxion.polaris 替换成 com.alibaba.polaris
```
② 手工替换src/main/java/下的Java包目录名
```
com.nepxion.polaris 替换成 com.alibaba.polaris
```
### 版本切换
- Polaris Parent定义
参考如下pom.xml里的用法
```
polaris-sdk/polaris-parent/pom.xml
```
### 组件切换
框架默认生效的组件，如下
| 核心组件名 | 默认生效的组件 |
| --- | --- |
| 旗标核心组件 | Nepxion Discovery |
| 注册发现核心组件 | Nacos |
| 配置核心组件 | Nacos |
| 调用链核心组件 | SkyWalking |
| 指标核心组件 | 未激活 |
| 防护核心组件 | Sentinel |
| 蓝绿灰度核心组件 | Nepxion Discovery |
#### 注册发现组件切换
在polaris-component目录下，搜索全部pom.xml，关键字
```
You can select one of following polaris discovery components, such as Nacos
```
把搜索出来的若干个pom.xml换成使用者想要的组件
#### 配置组件切换
在polaris-component目录下，搜索全部pom.xml，关键字
```
You can select one of following polaris config components, such as Apollo
```
把搜索出来的若干个pom.xml换成使用者想要的组件
#### 调用链组件切换
在polaris-component目录下，搜索全部pom.xml，关键字
```
You can select one of following polaris tracing components, such as SkyWalking
```
把搜索出来的若干个pom.xml换成使用者想要的组件
#### 指标组件切换
在polaris-component目录下，搜索全部pom.xml，关键字
```
You can select one of following polaris metrics components, such as Micrometer
```
把搜索出来的若干个pom.xml换成使用者想要的组件
#### 防护组件切换
在polaris-component目录下，搜索全部pom.xml，关键字
```
You can select one of following polaris protector components, such as Sentinel
```
把搜索出来的若干个pom.xml换成使用者想要的组件
### 注解切换
当配置组件切换到Apollo的时候，需要激活Apollo注解@EnableApolloConfig；非Apollo配置组件需要注释掉该注解，否则无法编译通过。需要在如下四个注解进行切换
- `@`EnablePolarisGateway
- `@`EnablePolarisZuul
- `@`EnablePolarisService
- `@`EnablePolarisConsole
### 配置切换
当防护中心选择Sentinel，并选择Apollo和Nacos做DataSource的时候，例如，当选择Apollo的时候，需要注释掉其它所有的Nacos配置。需要在如下三个组件的sentinel-common.properties配置文件里进行切换配
- polaris-component-protector-starter-sentinel-gateway
- polaris-component-protector-starter-sentinel-zuul
- polaris-component-protector-starter-sentinel-service
### 域名和环境切换
#### 域名和环境解析
所有的组件都支持四个环境（DEV | FAT | UAT | PRO），分别对应开发环境、测试环境、准生产环境、生产环境。框架支持在环境配置文件里动态解析和创建多活、多云和SET单元化模式的域名
框架组件环境配置规范（表格中以Nacos注册为示例），如下
| 环境 | 域名或者IP地址 | 配置文件 | 示例 |
| --- | --- | --- | --- |
| DEV | 默认为127.0.0.1:port | 组件名-dev
.properties | spring.cloud.nacos.discovery.server-addr=
127.0.0.1:8848 |
| FAT | 组件名-fat-区域名.根域 | 组件名-fat
.properties | spring.cloud.nacos.discovery.server-addr=
nacos-fat`${region}`.`${domain}` |
| UAT | 组件名-uat-区域名.根域 | 组件名-uat
.properties | spring.cloud.nacos.discovery.server-addr=
nacos-uat`${region}`.`${domain}` |
| PRO | 组件名-pro-区域名.根域 | 组件名-pro
.properties | spring.cloud.nacos.discovery.server-addr=
nacos-pro`${region}`.`${domain}` |
| COMMON | 无需配置 | 组件名-common
.properties | 无需配置 |
① 环境（env）号
- 定义为用来区别不同环境的标识
- 四个环境的配置文件除了定义域名或者IP地址外，也支持根据环境不同设置不同的配置值或者开关（例如，Swagger功能需要在生产环境关闭，需要在PRO配置文件里关闭）
- 除了四个环境的配置文件外，还存在一个公共配置文件，其作用是设置全局的不会随环境改变的默认配置，共享给四个环境，避免重复冗余配置。公共配置和环境配置，其关系是全局配置和局部配置的关系，如果同一个配置在公共配置文件和环境配置文件里都存在，环境配置文件优先
- 所有配置文件的位置在各个组件的src/main/resources/META-INF目录下，其中COMMON配置文件可以缺失，其它四个环境的配置文件不可缺失
② 区域（region）名
- 定义为用来区别多活、多云和SET单元化的域名的后缀或者前缀标识
- 域名表达式为`组件名`-`环境号`-`可选的区域名`.`根域`。使用者可以改变前缀或者后缀的组装形式和顺序，前缀中的“-”可以用其它符号来代替
- 实现占位处理，占位格式为`${region}`。如果区域（region）名不设置，那么变成“组件名-环境号.根域”的简单格式
- 通过DevOps来实现环境号和区域名的指定（下文“域名和环境设置”会讲到）
- 如果使用者没有条件实现多环境的域名支持，那么采用IP地址也可以
③ 根域（domain）名
- 定义为不同环境域名的根域后缀
- 实现占位处理，占位格式为`${domain}`
 注意事项
使用者需要根据企业的实际情况，把组件的四个环境域名或者IP地址一一做更改
#### 域名和环境设置
① 通过DevOps进行环境（env）号设置
- 通过System Property或者-Denv=`环境号`，进行设置
- 通过server.properties进行设置
```
env=dev
```
- 通过System Env环境变量方式进行设置
- 上述设置都未执行，则缺省为dev
② 通过DevOps进行区域（region）名设置
- 通过System Property或者-Dregion=`区域名`，进行设置。例如，-Dregion=sh-pd，sh-pd表示双活或者多活的机房名（上海浦东机房），两者可以独立配置其中之一，也可以同时并存
- 通过server.properties进行设置
```
region=sh-pd
```
- 通过System Env环境变量方式进行设置
- 上述设置都未执行，则缺省为空，即非多活或者多云的环境
③ 通过DevOps进行根域（domain）名设置
- 通过System Property或者-Ddomain=`根域名`，进行设置
- 通过server.properties进行设置
```
domain=aliyun.com
```
- 通过System Env环境变量方式进行设置
- 上述设置都未执行，则缺省为PolarisEnvConstant类里的DOMAIN_VALUE静态变量
 注意事项
读取优先级由高到低，如下
- System.getProperty
- System.getenv
- server.properties。Windows环境下该文件路径为C:/opt/settings/server.properties，Linux环境下该文件路径为/opt/settings/server.properties。示例内容如下
```
domain=aliyun.com
region=sh-pd
env=pro
```
④ 通过PolarisEnvConstant类进行设置。请参考里面的中文注释
```java
public class PolarisEnvConstant {
// 根域名相关定义。包含三种传值方式，优先级至上而下。使用者需要把根域值改掉
// 1. 通过-Ddomain=nepxion.com或者System.setProperty("domain", "nepxion.com")方式进行传入
// 2. 通过大写的DOMAIN，其值为nepxion.com的System ENV方式进行传入
// 3. 通过DevOps在server.properties定义domain=nepxion.com方式进行传入
public static final String DOMAIN_NAME = "domain";
public static final String DOMAIN_VALUE = "nepxion.com";
// 区域名相关定义。包含三种传值方式，优先级至上而下
// 1. 通过-Dregion=sh-pd或者System.setProperty("region", "sh-pd")方式进行传入
// 2. 通过大写的REGION，其值为sh-pd的System ENV方式进行传入
// 3. 通过DevOps在server.properties定义region=sh-pd方式进行传入
// 区域名分隔符相关定义
// REGION_SEPARATE表示区域在域名中的分隔符
// REGION_SEPARATE_PREFIX表示区域在域名中的分隔符是否在前面还是后面
// 包含两种表现形式。特别注意：region占位符前后切记不要出现分隔符，因为框架会自动去适配
// 1. 例如，原始格式为nacos-fat${region}.${domain}
// 1.1 在region存在的情况下，会解析成nacos-fat-sh-pd.nepxion.com
// 1.2 在region缺失的情况下，会解析成nacos-fat.nepxion.com
// 2. 例如，原始格式为${region}fat-nacos.${domain}
// 2.1 在region存在的情况下，会解析成sh-pd-fat-nacos.nepxion.com
// 2.2 在region缺失的情况下，会解析成fat-nacos.nepxion.com
public static final String REGION_NAME = "region";
public static final String REGION_SEPARATE = "-";
public static final boolean REGION_SEPARATE_PREFIX = true;
// 环境名相关定义。包含三种传值方式，优先级至上而下。以开发环境为例
// 1. 通过-Denv=dev或者System.setProperty("env", "dev")方式进行传入
// 2. 通过大写的ENV，其值为dev的System ENV方式进行传入
// 3. 通过DevOps在server.properties定义env=dev方式进行传入
public static final String ENV_NAME = "env";
// server.properties文件的存放位置
public static final String SERVER_PROPERTIES_PATH_WINDOWS = "C:/opt/settings/server.properties";
public static final String SERVER_PROPERTIES_PATH_LINUX = "/opt/settings/server.properties";
// 日志文件的存放位置
public static final String LOG_PATH_WINDOWS = "C:/opt/logs/";
public static final String LOG_PATH_LINUX = "/opt/logs/";
public static final String META_INF_PATH = "classpath:/META-INF/";
}
```
 注意事项
region占位符前后切记不要出现分隔符
参考[Polaris环境演示视频](https://nepxion.github.io/Discovery/docs/polaris-doc/PolarisEnv.wmv)
## 使用步骤
参考[Polaris指南主页](https://github.com/polaris-paas/polaris-guide)的源码
### 应用搭建
#### 引入Parent
```xml
com.nepxion.polaris
polaris-parent
${polaris.version}
```
#### 引入Jar
① 微服务API二方包引入
```xml
com.nepxion.polaris
polaris-framework-starter-api
${polaris.version}
```
② 微服务引入
```xml
com.nepxion.polaris
polaris-framework-starter-service
${polaris.version}
```
③ Spring Cloud Gateway网关引入
```xml
com.nepxion.polaris
polaris-framework-starter-gateway
${polaris.version}
```
④ Zuul网关引入
```xml
com.nepxion.polaris
polaris-framework-starter-zuul
${polaris.version}
```
⑤ 控制台引入
```xml
com.nepxion.polaris
polaris-framework-starter-console
${polaris.version}
```
⑥ 测试端引入
```xml
com.nepxion.polaris
polaris-framework-starter-test
${polaris.version}
```
#### 添加注解
下面四个注解封装了标准Spring Boot、Spring Cloud、Apollo、服务注册发现等多个注解，可以有效的降低业务使用成本
① 微服务引入
```java
@EnablePolarisService
public class PolarisApplication {
public static void main(String[] args) {
new SpringApplicationBuilder(PolarisApplication.class).run(args);
}
}
```
② Spring Cloud Gateway网关引入
```java
@EnablePolarisGateway
public class PolarisApplication {
public static void main(String[] args) {
new SpringApplicationBuilder(PolarisApplication.class).run(args);
}
}
```
③ Zuul网关引入
```java
@EnablePolarisZuul
public class PolarisApplication {
public static void main(String[] args) {
new SpringApplicationBuilder(PolarisApplication.class).run(args);
}
}
```
④ 控制台引入
```java
@EnablePolarisConsole
public class PolarisApplication {
public static void main(String[] args) {
new SpringApplicationBuilder(PolarisApplication.class).run(args);
}
}
```
#### 添加配置
由于大量配置已经内置到框架里，除了服务名和端口号之外，业务层原则上不需要再添加Spring Cloud和中间件其它配置，当然也可以覆盖掉默认内置的配置。内置配置文件支持Spring标准占位符用法
 小贴士
为了避免引起业务层的配置无法覆盖掉默认内置的配置，请在bootstrap.properties定义想要覆盖的配置
### 应用启动
#### 中间件服务启动
 注意事项
Polaris依赖Nacos Server（必选）和SkyWalking Server（可选），请事先搭建好对应的Server
#### Spring-Boot应用启动
跟原生的Spring Boot应用程序启动方式一致
在IDE中，启动四个应用服务和两个网关服务，控制平台服务，如下
| 类名 | 微服务 | 服务端口 | 版本 | 区域 | 环境 | 可用区
| --- | --- | --- | --- | --- | -- | -- |
| PolarisServiceA1.java | A1 | 3001 | 1.0 | dev | env1 | zone1 |
| PolarisServiceA2.java | A2 | 3002 | 1.1 | qa | common | zone2 |
| PolarisServiceB1.java | B1 | 4001 | 1.0 | qa | env1 | zone1 |
| PolarisServiceB2.java | B2 | 4002 | 1.1 | dev | common | zone2 |
| PolarisGateway.java | Gateway | 5001 | 1.0 | 无 | 无 | 无 |
| PolarisZuul.java | Zuul | 5002 | 1.0 | 无 | 无 | 无 |
| PolarisConsole.java | Console | 6001 | 1.0 | 无 | 无 | 无 |
部署拓扑图
#### SkyWalking-Agent启动
获取SkyWalking Agent，放置在指定目录（例如，C:/opt/skywalking-agent/），通过-javaagent命令启动
#### Polaris-Agent启动
具体使用方式，访问[异步场景下DiscoveryAgent解决方案](https://gitee.com/Nepxion/Discovery#%e5%bc%82%e6%ad%a5%e5%9c%ba%e6%99%af%e4%b8%8bdiscoveryagent%e8%a7%a3%e5%86%b3%e6%96%b9%e6%a1%88)
 注意事项
对于Spring Cloud 20xx版，由于它采用的负载均衡Spring Cloud LoadBalancer是基于异步的WebFlux，所以必须加上DiscoveryAgent，如下
```
-javaagent:C:/opt/discovery-agent/discovery-agent-starter-${discovery.agent.version}.jar
```
### 启动参数
#### Agent启动参数
Polaris应用完整启动参数如下
- 服务
PolarisServiceA（同步服务）:
```
-javaagent:C:/opt/skywalking-agent/skywalking-agent.jar -Dskywalking.agent.service_name=polaris-service-a -Dpolaris.skywalking.agent.version=1.0.0
```
PolarisServiceA（异步服务）:
```
-javaagent:C:/opt/discovery-agent/discovery-agent-starter-${discovery.agent.version}.jar -Dthread.scan.packages=com.nepxion.polaris.guide.service
-javaagent:C:/opt/skywalking-agent/skywalking-agent.jar -Dskywalking.agent.service_name=polaris-service-a -Dpolaris.skywalking.agent.version=1.0.0
```
PolarisServiceB（同步服务）:
```
-javaagent:C:/opt/skywalking-agent/skywalking-agent.jar -Dskywalking.agent.service_name=polaris-service-b -Dpolaris.skywalking.agent.version=1.0.0
```
- 网关
PolarisZuul（同步网关）:
```
-javaagent:C:/opt/skywalking-agent/skywalking-agent.jar -Dskywalking.agent.service_name=polaris-zuul -Dpolaris.skywalking.agent.version=1.0.0
```
PolarisGateway（异步网关）:
```
-javaagent:C:/opt/skywalking-agent/skywalking-agent.jar -Dskywalking.agent.service_name=polaris-gateway -Dpolaris.skywalking.agent.version=1.0.0
```
#### Nepxion-Discovery启动参数
蓝绿灰度发布和环境隔离路由的元数据注册的启动参数如下，分别对应蓝绿灰度版本号，区域号，环境号，可用区号，最后一项是启动的时候是否显示旗标为彩色，可以忽略
```
-Dmetadata.version=20200818-001 -Dmetadata.region=region1 -Dmetadata.env=env1 -Dmetadata.zone=zone1 -Dnepxion.banner.shown.ansi.mode=true
```
### 验证结果
#### Postman方式验证
- 导入Postman的测试脚本postman.json（位于根目录下）
- 执行“Polaris网关测试用例”，观察输出结果，5002端口对应的是Zuul网关，5001端口对应的是Spring Cloud Gateway网关
- 执行“Polaris网关全链路侦测测试用例”，观察输出结果，5002端口对应的是Zuul网关，5001端口对应的是Spring Cloud Gateway网关
#### 自动化测试方式验证
- 运行PolarisTest，观察输出结果，自动化测试用例是否都通过
### 新增组件
以创建一个配置中心组件Etcd为例，请尽量严格遵守Polaris集成方式，保持风格统一
#### 组件创建
① 按照如下结构进行目录创建，并编写相应的pom.xml
- polaris-component
- polaris-component-config
- polaris-component-config-starter-etcd
② 在resource/META-INF下创建如下5个环境文件，并分别写入相应的配置。如何写入，请参照上文“域名和环境切换”章节
- etcd-config-common.properties
- etcd-config-dev.properties
- etcd-config-fat.properties
- etcd-config-pro.properties
- etcd-config-uat.properties
③ 新建com.nepxion.polaris.component.config.etcd.context.EtcdEnvProcessor类
```java
public class EtcdEnvProcessor extends PolarisEnvPostProcessor {
// 如果初始化环境的时候，如果还需要做其它处理，请继承process方法
@Override
public void process(ConfigurableEnvironment environment) throws Exception {
// DO SOMETHING
super.process(environment);
// DO SOMETHING
}
// 如果初始化环境的时候，如果还需要做每条值做特殊处理，请继承processValue方法
@Override
protected String processValue(ConfigurableEnvironment environment, String key, String value) {
// DO SOMETHING
String newValue = doSomething(key, value);
return super.processValue(environment, key, newValue);
}
// 返回环境的名称，其值对应为环境文件的前缀
@Override
public String getName() {
return "etcd-config";
}
}
```
④ 配置resource/META-INF/spring.factories
```
org.springframework.boot.env.EnvironmentPostProcessor=\
com.nepxion.polaris.component.config.etcd.context.EtcdEnvProcessor
```
#### 组件聚合
① 在polaris-component-config-starter目录下的pom.xml，把polaris-component-config-starter-etcd加入，进行组件层面聚合，Polaris自动会将该组件在框架层面聚合
② 如果该组件不希望被绑死在框架层，也可以暴露给业务层，由业务开发自行引入
## Spring-Boot-2-3-x新特性
### 容器化部署
基于Spring Boot 2.3.x新特性制作的Docker容器化部署
#### 部署Polaris框架包
 注意事项
由于`Polaris框架包`未推送到Maven中央仓库，需要使用者自行编译部署。在`Polaris源码`的polaris-parent和polaris-skd工程目录下，分别执行如下命令，把Polaris框架相关包部署到本地仓库
```
mvn clean install -U -DskipTests
```
#### 添加Spring-Boot打包插件
以`Polaris指南`的polaris-guide-service-a工程为例，下同
在polaris-guide-service-a工程目录下的pom.xml，执行如下操作
```xml
org.springframework.boot
spring-boot-maven-plugin
${spring.boot.version}
com.nepxion.polaris.guide.service.PolarisServiceA1
JAR
true
repackage
false
```
 注意事项
相对旧版本的spring-boot-maven-plugin，新版本增加了如下配置参数，用来支持镜像Layer分层，加快打包部署的速度
```xml
true
```
 兼容性问题
旧版的如下参数必须删除！否则无法创建镜像分层
```xml
true
```
#### 执行Docker容器和镜像的制作和运行
 注意事项
Windows操作系统需要注意以下事项
- 在环境变量里需要配置DOCKER_HOST=tcp://localhost:2375
- Hyper-v预留和占用端口，有三种解决方案，如下
① 通过重启winnat解决，属于临时方案
依次执行如下三个命令行
```
net stop winnat
docker start ...
net start winnat
```
第二个命令行，即退出Docker Desktop，再启动Docker Desktop
② 通过端口排除解决，属于永久方案
参考如下链接：
[https://www.cnblogs.com/wilsonsui/p/12719046.html](https://www.cnblogs.com/wilsonsui/p/12719046.html)
③ 更换动态端口，属于永久方案
参考如下链接：
[https://www.jianshu.com/p/7412ff422db6](https://www.jianshu.com/p/7412ff422db6)
Docker容器和镜像的制作和运行步骤，如下
在polaris-guide-service-a工程目录下，执行如下操作
① 执行如下命令，编译Jar包
```
mvn clean package -U -DskipTests
```
② 验证镜像Layer分层(*非必须执行的步骤)
执行如下命令，查看Layer分层
```
java -Djarmode=layertools -jar target/polaris-guide-service-a-0.0.1.jar list
```
控制台输出如下四个分层，则表示有效
```
dependencies
spring-boot-loader
snapshot-dependencies
application
```
③ 创建Dockerfile
application.jar包同级目录下，将会输出四个分层的目录和文件
制作Dockerfile放在polaris-guide-service-a工程目录下。内置解压命令，根据jar构建生成清单layers.idx解压提取每个Layer要写入镜像的内容。内容如下
```
# 指定基础镜像，这是分阶段构建的前期阶段
FROM openjdk:8-jre-alpine as builder
# 执行工作目录
WORKDIR application
# 配置参数
ARG JAR_FILE=target/*.jar
# 将编译构建得到的jar文件复制到镜像空间中
COPY ${JAR_FILE} application.jar
# 通过工具spring-boot-jarmode-layertools从application.jar中提取拆分后的构建结果
RUN java -Djarmode=layertools -jar application.jar extract
# 正式构建镜像
FROM openjdk:8-jre-alpine
WORKDIR application
# 前一阶段从jar中提取除了多个文件，这里分别执行COPY命令复制到镜像空间中，每次COPY都是一个layer
COPY --from=builder application/dependencies/ ./
COPY --from=builder application/spring-boot-loader/ ./
COPY --from=builder application/snapshot-dependencies/ ./
COPY --from=builder application/application/ ./
# -Djava.security.egd=file:/dev/./urandom 内核随机种子，防止启动很慢
ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -Djava.security.egd=file:/dev/./urandom org.springframework.boot.loader.JarLauncher"]
```
④ 创建镜像和容器
执行如下命令创建镜像和容器
```
docker build . --tag polaris-guide-service-a
```
⑤ 运行容器
执行如下命令运行容器
```
set METADATA_VERSION=my-version
set METADATA_REGION=my-region
set METADATA_ENV=my-env
set METADATA_ZONE=my-zone
docker run -i -t -e JAVA_OPTS="-Dnepxion.banner.shown.ansi.mode=true -Dmetadata.version=%METADATA_VERSION% -Dmetadata.region=%METADATA_REGION% -Dmetadata.env=%METADATA_ENV% -Dmetadata.zone=%METADATA_ZONE%" -e TZ="Asia/Shanghai" -p 3001:3001 -h polaris-guide-service-a --name polaris-guide-service-a polaris-guide-service-a:latest
```
 注意事项
在DEV（本地）环境下，配置Docker容器不能通过127.0.0.1的IP地址连接容器外中间件服务器，故需要把启动命令改成如下形式。域名方式则不需要这么做
```
set NACOS_SERVER=192.168.0.107:8848
docker run %RUN_MODE% -e JAVA_OPTS="-Dspring.cloud.nacos.discovery.server-addr=%NACOS_SERVER% -Dspring.cloud.nacos.config.server-addr=%NACOS_SERVER% -Dspring.cloud.sentinel.datasource.nacos.server-addr=%NACOS_SERVER% -Dnacos.server-addr=%NACOS_SERVER% -Dnepxion.banner.shown.ansi.mode=%SHOWN_ANSI_MODE% -Dmetadata.version=%METADATA_VERSION% -Dmetadata.region=%METADATA_REGION% -Dmetadata.env=%METADATA_ENV% -Dmetadata.zone=%METADATA_ZONE%" -e TZ="Asia/Shanghai" -p %MACHINE_PORT%:%CONTAINER_PORT% -h %IMAGE_NAME% --name %IMAGE_NAME% %IMAGE_NAME%:latest
```
上述所有的命令组装成一键启动方式的脚本：install-docker.bat和install-docker.sh，请参考polaris-guide-service-a工程目录下的相应脚本
⑥ Docker运行效果
- Docker Desktop
- Docker Windows
- Docker Linux
⑦ 官方部署Docker文档
参考[Spring Boot 2.3.x官方部署Docker文档](https://spring.io/blog/2020/01/27/creating-docker-images-with-spring-boot-2-3-0-m1)获取更多用法，但请谨慎使用，有不少错误的地方，可能是来不及更新
### 优雅停机
```
# 开启Spring Boot 2.3.x优雅停机
server.shutdown=graceful
# 优雅停机缓冲时间
spring.lifecycle.timeout-per-shutdown-phase=20s
```
