devbox
IT小白
这个屌丝很懒，什么也没留下！
关注作者
热门标签
热门文章
当前位置:   article > 正文

APOLLO配置中心_apollo 获取配置时指定集群

作者：IT小白 | 2024-04-24 08:23:11

赞

踩

apollo 获取配置时指定集群

Apollo配置中心介绍

2016年 07月 09日

1、What is Apollo

1.1 背景

随着程序功能的日益复杂，程序的配置日益增多：各种功能的开关、参数的配置、服务器的地址……

对程序配置的期望值也越来越高：配置修改后实时生效，灰度发布，分环境、分集群管理配置，完善的权限、审核机制……

在这样的大环境下，传统的通过配置文件、数据库等方式已经越来越无法满足开发人员对配置管理的需求。

Apollo配置中心应运而生！

1.2 Apollo简介

Apollo（阿波罗）是携程框架部门研发的开源配置管理中心，能够集中化管理应用不同环境、不同集群的配置，配置修改后能够实时推送到应用端，并且具备规范的权限、流程治理等特性。

Apollo支持4个维度管理Key-Value格式的配置：

  1. application (应用)
  2. environment (环境)
  3. cluster (集群)
  4. namespace (命名空间)

同时，Apollo基于开源模式开发，开源地址：https://github.com/ctripcorp/apollo

1.3 配置基本概念

既然Apollo定位于配置中心，那么在这里有必要先简单介绍一下什么是配置。

按照我们的理解，配置有以下几个属性：

  • 配置是独立于程序的只读变量
    • 配置首先是独立于程序的，同一份程序在不同的配置下会有不同的行为。
    • 其次，配置对于程序是只读的，程序通过读取配置来改变自己的行为，但是程序不应该去改变配置。
    • 常见的配置有：DB Connection Str、Thread Pool Size、Buffer Size、Request Timeout、Feature Switch、Server Urls等。
  • 配置伴随应用的整个生命周期
    • 配置贯穿于应用的整个生命周期，应用在启动时通过读取配置来初始化，在运行时根据配置调整行为。
  • 配置可以有多种加载方式
    • 配置也有很多种加载方式，常见的有程序内部hard code，配置文件，环境变量，启动参数，基于数据库等
  • 配置需要治理
    • 权限控制
      • 由于配置能改变程序的行为，不正确的配置甚至能引起灾难，所以对配置的修改必须有比较完善的权限控制
    • 不同环境、集群配置管理
      • 同一份程序在不同的环境（开发，测试，生产）、不同的集群（如不同的数据中心）经常需要有不同的配置，所以需要有完善的环境、集群配置管理
    • 框架类组件配置管理
      • 还有一类比较特殊的配置 - 框架类组件配置，比如CAT客户端的配置。
      • 虽然这类框架类组件是由其他团队开发、维护，但是运行时是在业务实际应用内的，所以本质上可以认为框架类组件也是应用的一部分。
      • 这类组件对应的配置也需要有比较完善的管理方式。

2、Why Apollo

正是基于配置的特殊性，所以Apollo从设计之初就立志于成为一个有治理能力的配置管理平台，目前提供了以下的特性：

  • 统一管理不同环境、不同集群的配置
    • Apollo提供了一个统一界面集中式管理不同环境（environment）、不同集群（cluster）、不同命名空间（namespace）的配置。
    • 同一份代码部署在不同的集群，可以有不同的配置，比如zk的地址等
    • 通过命名空间（namespace）可以很方便的支持多个不同应用共享同一份配置，同时还允许应用对共享的配置进行覆盖
  • 配置修改实时生效（热发布）
    • 用户在Apollo修改完配置并发布后，客户端能实时（1秒）接收到最新的配置，并通知到应用程序
  • 版本发布管理
    • 所有的配置发布都有版本概念，从而可以方便地支持配置的回滚
  • 灰度发布
    • 支持配置的灰度发布，比如点了发布后，只对部分应用实例生效，等观察一段时间没问题后再推给所有应用实例
  • 权限管理、发布审核、操作审计
    • 应用和配置的管理都有完善的权限管理机制，对配置的管理还分为了编辑和发布两个环节，从而减少人为的错误。
    • 所有的操作都有审计日志，可以方便的追踪问题
  • 客户端配置信息监控
    • 可以在界面上方便地看到配置在被哪些实例使用
  • 提供Java和.Net原生客户端
    • 提供了Java和.Net的原生客户端，方便应用集成
    • 支持Spring Placeholder, Annotation和Spring Boot的ConfigurationProperties，方便应用使用（需要Spring 3.1.1+）
    • 同时提供了Http接口，非Java和.Net应用也可以方便的使用
  • 提供开放平台API
    • Apollo自身提供了比较完善的统一配置管理界面，支持多环境、多数据中心配置管理、权限、流程治理等特性。
    • 不过Apollo出于通用性考虑，对配置的修改不会做过多限制，只要符合基本的格式就能够保存。
    • 在我们的调研中发现，对于有些使用方，它们的配置可能会有比较复杂的格式，而且对输入的值也需要进行校验后方可保存，如检查数据库、用户名和密码是否匹配。
    • 对于这类应用，Apollo支持应用方通过开放接口在Apollo进行配置的修改和发布，并且具备完善的授权和权限控制
  • 部署简单
    • 配置中心作为基础服务，可用性要求非常高，这就要求Apollo对外部依赖尽可能地少
    • 目前唯一的外部依赖是MySQL，所以部署非常简单，只要安装好Java和MySQL就可以让Apollo跑起来
    • Apollo还提供了打包脚本，一键就可以生成所有需要的安装包，并且支持自定义运行时参数

3、Apollo at a glance

3.1 基础模型

如下即是Apollo的基础模型：

  1. 用户在配置中心对配置进行修改并发布
  2. 配置中心通知Apollo客户端有配置更新
  3. Apollo客户端从配置中心拉取最新的配置、更新本地配置并通知到应用

basic-architecture

3.2 界面概览

 

上图是Apollo配置中心中一个项目的

配置首页

  • 在页面左上方的环境列表模块展示了所有的环境和集群，用户可以随时切换。
  • 页面中央展示了两个namespace(application和FX.apollo)的配置信息，默认按照表格模式展示、编辑。用户也可以切换到文本模式，以文件形式查看、编辑。
  • 页面上可以方便地进行发布、回滚、灰度、授权、查看更改历史和发布历史等操作

3.3 添加/修改配置项

用户可以通过配置中心界面方便的添加/修改配置项：

edit-item-1

输入配置信息：

edit-item

3.4 发布配置

通过配置中心发布配置：

publish-items-1

填写发布信息：

 

3.5 客户端获取配置（Java API样例）

配置发布后，就能在客户端获取到了，以Java API方式为例，获取配置的示例代码如下。更多客户端使用说明请参见Java客户端使用指南。

 

  1. Config config = ConfigService.getAppConfig();

  2. Integer defaultRequestTimeout = 200;

  3. Integer requestTimeout =

  4. config.getIntProperty("request.timeout",defaultRequestTimeout);

3.6 客户端监听配置变化（Java API样例）

通过上述获取配置代码，应用就能实时获取到最新的配置了。

不过在某些场景下，应用还需要在配置变化时获得通知，比如数据库连接的切换等，所以Apollo还提供了监听配置变化的功能，Java示例如下：

 

  1. Config config = ConfigService.getAppConfig();

  2. config.addChangeListener(new ConfigChangeListener() {

  3. @Override

  4. public void onChange(ConfigChangeEvent changeEvent) {

  5. for (String key : changeEvent.changedKeys()) {

  6. ConfigChange change = changeEvent.getChange(key);

  7. System.out.println(String.format(

  8. "Found change - key: %s, oldValue: %s, newValue: %s, changeType: %s",

  9. change.getPropertyName(), change.getOldValue(),

  10. change.getNewValue(), change.getChangeType()));

  11. }

  12. }

  13. });

3.7 Spring集成样例

Apollo和Spring也可以很方便地集成，只需要标注@EnableApolloConfig后就可以通过@Value获取配置信息：

 

  1. @Configuration

  2. @EnableApolloConfig

  3. public class AppConfig {}

  4.  
 

  1. @Component

  2. public class SomeBean {

  3. @Value("${request.timeout:200}")

  4. private int timeout;

  5.  

  6. @ApolloConfigChangeListener

  7. private void someChangeHandler(ConfigChangeEvent changeEvent) {

  8. if (changeEvent.isChanged("request.timeout")) {

  9. refreshTimeout();

  10. }

  11. }

  12. }

  13.  

4、Apollo in depth

通过上面的介绍，相信大家已经对Apollo有了一个初步的了解，并且相信已经覆盖到了大部分的使用场景。

接下来会主要介绍Apollo的cluster管理（集群）、namespace管理（命名空间）和对应的配置获取规则。

4.1 Core Concepts

在介绍高级特性前，我们有必要先来了解一下Apollo中的几个核心概念：

  1. application (应用)
    • 这个很好理解，就是实际使用配置的应用，Apollo客户端在运行时需要知道当前应用是谁，从而可以去获取对应的配置
    • 每个应用都需要有唯一的身份标识 - appId，我们认为应用身份是跟着代码走的，所以需要在代码中配置，具体信息请参见Java客户端使用指南。
  2. environment (环境)
    • 配置对应的环境，Apollo客户端在运行时需要知道当前应用处于哪个环境，从而可以去获取应用的配置
    • 我们认为环境和代码无关，同一份代码部署在不同的环境就应该能够获取到不同环境的配置
    • 所以环境默认是通过读取机器上的配置（server.properties中的env属性）指定的，不过为了开发方便，我们也支持运行时通过System Property等指定，具体信息请参见文章末尾。
  3. cluster (集群)
    • 一个应用下不同实例的分组，比如典型的可以按照数据中心分，把上海机房的应用实例分为一个集群，把北京机房的应用实例分为另一个集群。
    • 对不同的cluster，同一个配置可以有不一样的值，如zookeeper地址。
    • 集群默认是通过读取机器上的配置（server.properties中的idc属性）指定的，不过也支持运行时通过System Property指定，具体信息请参见Java客户端使用指南。
  4. namespace (命名空间)
    • 一个应用下不同配置的分组，可以简单地把namespace类比为文件，不同类型的配置存放在不同的文件中，如数据库配置文件，rpc配置文件，应用自身的配置文件等
    • 应用可以直接读取到公共组件的配置namespace，如DAL，RPC等
    • 应用也可以通过继承公共组件的配置namespace来对公共组件的配置做调整，如DAL的初始数据库连接数

4.2 自定义Cluster

【本节内容仅对应用需要对不同集群应用不同配置才需要，如没有相关需求，可以跳过本节】

比如我们有应用在A数据中心和B数据中心都有部署，那么如果希望两个数据中心的配置不一样的话，我们可以通过新建cluster来解决。

4.2.1 新建Cluster

新建Cluster只有项目的管理员才有权限，管理员可以在页面左侧看到“添加集群”按钮。

create-cluster

点击后就进入到集群添加页面，一般情况下可以按照数据中心来划分集群，如SHAJQ、SHAOY等。

不过也支持自定义集群，比如可以为A机房的某一台机器和B机房的某一台机创建一个集群，使用一套配置。

create-cluster-detail

4.2.2 在Cluster中添加配置并发布

集群添加成功后，就可以为该集群添加配置了，首选需要按照下图所示切换到SHAJQ集群，之后配置添加流程和3.2添加/修改配置项一样，这里就不再赘述了。

cluster-created

4.2.3 指定应用实例所属的Cluster

Apollo会默认使用应用实例所在的数据中心作为cluster，所以如果两者一致的话，不需要额外配置。

如果cluster和数据中心不一致的话，那么就需要通过System Property方式来指定运行时cluster：

  • -Dapollo.cluster=SomeCluster
  • 这里注意apollo.cluster为全小写

4.3 自定义Namespace

【本节仅对公共组件配置或需要多个应用共享配置才需要，如没有相关需求，可以跳过本节】

如果应用有公共组件（如hermes-producer，cat-client等）供其它应用使用，就需要通过自定义namespace来实现公共组件的配置。

4.3.1 新建Namespace

以hermes-producer为例，需要先新建一个namespace，新建namespace只有项目的管理员才有权限，管理员可以在页面左侧看到“添加Namespace”按钮。

create-namespace

点击后就进入namespace添加页面，Apollo会把应用所属的部门作为namespace的前缀，如FX。

create-namespace-detail

4.3.2 关联到环境和集群

Namespace创建完，需要选择在哪些环境和集群下使用

link-namespace-detail

4.3.3 在Namespace中添加配置项

接下来在这个新建的namespace下添加配置项

add-item-in-new-namespace

添加完成后就能在FX.Hermes.Producer的namespace中看到配置。

item-created-in-new-namespace

4.3.4 发布namespace的配置

publish-items-in-new-namespace

4.3.5 客户端获取Namespace配置

对自定义namespace的配置获取，稍有不同，需要程序传入namespace的名字。更多客户端使用说明请参见Java客户端使用指南。

 

  1. Config config = ConfigService.getConfig("FX.Hermes.Producer");

  2. Integer defaultSenderBatchSize = 200;

  3. Integer senderBatchSize = config.getIntProperty("sender.batchsize", defaultSenderBatchSize);

4.3.6 客户端监听Namespace配置变化

 

  1. Config config = ConfigService.getConfig("FX.Hermes.Producer");

  2. config.addChangeListener(new ConfigChangeListener() {

  3. @Override

  4. public void onChange(ConfigChangeEvent changeEvent) {

  5. System.out.println("Changes for namespace " + changeEvent.getNamespace());

  6. for (String key : changeEvent.changedKeys()) {

  7. ConfigChange change = changeEvent.getChange(key);

  8. System.out.println(String.format(

  9. "Found change - key: %s, oldValue: %s, newValue: %s, changeType: %s",

  10. change.getPropertyName(), change.getOldValue(),

  11. change.getNewValue(), change.getChangeType()));

  12. }

  13. }

  14. });

4.3.7 Spring集成样例

 

  1. @Configuration

  2. @EnableApolloConfig("FX.Hermes.Producer")

  3. public class AppConfig {}

 

  1. @Component

  2. public class SomeBean {

  3. @Value("${request.timeout:200}")

  4. private int timeout;

  5.  

  6. @ApolloConfigChangeListener("FX.Hermes.Producer")

  7. private void someChangeHandler(ConfigChangeEvent changeEvent) {

  8. if (changeEvent.isChanged("request.timeout")) {

  9. refreshTimeout();

  10. }

  11. }

  12. }

4.4 配置获取规则

【本节仅当应用自定义了集群或namespace才需要，如无相关需求，可以跳过本节】

在有了cluster概念后，配置的规则就显得重要了。

比如应用部署在A机房，但是并没有在Apollo新建cluster，这个时候Apollo的行为是怎样的？

或者在运行时指定了cluster=SomeCluster，但是并没有在Apollo新建cluster，这个时候Apollo的行为是怎样的？

接下来就来介绍一下配置获取的规则。

4.4.1 应用自身配置的获取规则

当应用使用下面的语句获取配置时，我们称之为获取应用自身的配置，也就是应用自身的application namespace的配置。

Config config = ConfigService.getAppConfig();

对这种情况的配置获取规则，简而言之如下：

  1. 首先查找运行时cluster的配置（通过apollo.cluster指定）
  2. 如果没有找到，则查找数据中心cluster的配置
  3. 如果还是没有找到，则返回默认cluster的配置

图示如下：

application-config-precedence

所以如果应用部署在A数据中心，但是用户没有在Apollo创建cluster，那么获取的配置就是默认cluster（default）的。

如果应用部署在A数据中心，同时在运行时指定了SomeCluster，但是没有在Apollo创建cluster，那么获取的配置就是A数据中心cluster的配置，如果A数据中心cluster没有配置的话，那么获取的配置就是默认cluster（default）的。

4.4.2 公共组件配置的获取规则

以FX.Hermes.Producer为例，hermes producer是hermes发布的公共组件。当使用下面的语句获取配置时，我们称之为获取公共组件的配置。

Config config = ConfigService.getConfig("FX.Hermes.Producer");

对这种情况的配置获取规则，简而言之如下：

  1. 首先获取当前应用下的FX.Hermes.Producer namespace的配置
  2. 然后获取hermes应用下FX.Hermes.Producer namespace的配置
  3. 上面两部分配置的并集就是最终使用的配置，如有key一样的部分，以当前应用优先

图示如下：

public-namespace-config-precedence

通过这种方式，就实现了对框架类组件的配置管理，框架组件提供方提供配置的默认值，应用如果有特殊需求，可以自行覆盖。

4.5 总体设计

 

 

上图简要描述了Apollo的总体设计，我们可以从下往上看：

  • Config Service提供配置的读取、推送等功能，服务对象是Apollo客户端
  • Admin Service提供配置的修改、发布等功能，服务对象是Apollo Portal（管理界面）
  • Config Service和Admin Service都是多实例、无状态部署，所以需要将自己注册到Eureka中并保持心跳
  • 在Eureka之上我们架了一层Meta Server用于封装Eureka的服务发现接口
  • Client通过域名访问Meta Server获取Config Service服务列表（IP+Port），而后直接通过IP+Port访问服务，同时在Client侧会做load balance、错误重试
  • Portal通过域名访问Meta Server获取Admin Service服务列表（IP+Port），而后直接通过IP+Port访问服务，同时在Portal侧会做load balance、错误重试
  • 为了简化部署，我们实际上会把Config Service、Eureka和Meta Server三个逻辑角色部署在同一个JVM进程中

4.5.1 Why Eureka

为什么我们采用Eureka作为服务注册中心，而不是使用传统的zk、etcd呢？我大致总结了一下，有以下几方面的原因：

  • 它提供了完整的Service Registry和Service Discovery实现
    • 首先是提供了完整的实现，并且也经受住了Netflix自己的生产环境考验，相对使用起来会比较省心。
  • 和Spring Cloud无缝集成
    • 我们的项目本身就使用了Spring Cloud和Spring Boot，同时Spring Cloud还有一套非常完善的开源代码来整合Eureka，所以使用起来非常方便。
    • 另外，Eureka还支持在我们应用自身的容器中启动，也就是说我们的应用启动完之后，既充当了Eureka的角色，同时也是服务的提供者。这样就极大的提高了服务的可用性。
    • 这一点是我们选择Eureka而不是zk、etcd等的主要原因，为了提高配置中心的可用性和降低部署复杂度，我们需要尽可能地减少外部依赖。
  • Open Source
    • 最后一点是开源，由于代码是开源的，所以非常便于我们了解它的实现原理和排查问题。

4.6 客户端设计

 

上图简要描述了Apollo客户端的实现原理：

  1. 客户端和服务端保持了一个长连接，从而能第一时间获得配置更新的推送。
  2. 客户端还会定时从Apollo配置中心服务端拉取应用的最新配置。
    • 这是一个fallback机制，为了防止推送机制失效导致配置不更新
    • 客户端定时拉取会上报本地版本，所以一般情况下，对于定时拉取的操作，服务端都会返回304 - Not Modified
    • 定时频率默认为每5分钟拉取一次，客户端也可以通过在运行时指定System Property: apollo.refreshInterval来覆盖，单位为分钟。
  3. 客户端从Apollo配置中心服务端获取到应用的最新配置后，会保存在内存中
  4. 客户端会把从服务端获取到的配置在本地文件系统缓存一份
    • 在遇到服务不可用，或网络不通的时候，依然能从本地恢复配置
  5. 应用程序可以从Apollo客户端获取最新的配置、订阅配置更新通知

4.6.1 配置更新推送实现

前面提到了Apollo客户端和服务端保持了一个长连接，从而能第一时间获得配置更新的推送。

长连接实际上我们是通过Http Long Polling实现的，具体而言：

  • 客户端发起一个Http请求到服务端
  • 服务端会保持住这个连接30秒
  • 如果在30秒内有客户端关心的配置变化，被保持住的客户端请求会立即返回，并告知客户端有配置变化的namespace信息，客户端会据此拉取对应namespace的最新配置
  • 如果在30秒内没有客户端关心的配置变化，那么会返回Http状态码304给客户端
  • 客户端在服务端请求返回后会自动重连

考虑到会有数万客户端向服务端发起长连，在服务端我们使用了async servlet(Spring DeferredResult)来服务Http Long Polling请求。

4.7 可用性考虑

配置中心作为基础服务，可用性要求非常高，下面的表格描述了不同场景下Apollo的可用性：

场景影响降级原因
某台config service下线无影响 Config service无状态，客户端重连其它config service
所有config service下线客户端无法读取最新配置，Portal无影响客户端重启时,可以读取本地缓存配置文件 
某台admin service下线无影响 Admin service无状态，Portal重连其它admin service
所有admin service下线客户端无影响，portal无法更新配置  
某台portal下线无影响 Portal域名通过slb绑定多台服务器，重试后指向可用的服务器
全部portal下线客户端无影响，portal无法更新配置  
某个数据中心下线无影响 多数据中心部署，数据完全同步，Meta Server/Portal域名通过slb自动切换到其它存活的数据中心

5、Contribute to Apollo

Apollo从开发之初就是以开源模式开发的，所以也非常欢迎有兴趣、有余力的朋友一起加入进来。

服务端开发使用的是Java，基于Spring Cloud和Spring Boot框架。客户端目前提供了Java和.Net两种实现。

Github地址：https://github.com/ctripcorp/apollo

欢迎大家发起Pull Request！


本作品由nobodyiam创作，采用知识共享署名-相同方式共享 4.0 国际许可协议进行许可。

Copyright © nobodyiam.com, hosted by Coding Pages, powered by Jekyll.

 

末尾：

Java客户端使用指南

一、准备工作

1.1 环境要求

  • Java: 1.7+
  • Guava: 15.0+
    • Apollo客户端默认会引用Guava 19，如果你的项目引用了其它版本，请确保版本号大于等于15.0

注：对于Apollo客户端，如果有需要的话，可以做少量代码修改来降级到Java 1.6，详细信息可以参考Issue 483

1.2 必选设置

Apollo客户端依赖于AppId，Environment等环境信息来工作，所以请确保阅读下面的说明并且做正确的配置：

1.2.1 AppId

AppId是应用的身份信息，是从服务端获取配置的一个重要信息。

请确保classpath:/META-INF/app.properties文件存在，并且其中内容形如：

app.id=YOUR-APP-ID

文件位置参考如下：

 

v0.7.0版本后，Apollo也支持通过System Property传入app.id信息，如

-Dapp.id=YOUR-APP-ID

注：app.id是用来标识应用身份的唯一id，格式为string。

1.2.2 Environment

Apollo支持应用在不同的环境有不同的配置，所以Environment是另一个从服务器获取配置的重要信息。

Environment可以通过以下3种方式的任意一个配置：

  1. 通过Java System Property
    • 可以通过Java的System Property env来指定环境
    • 在Java程序启动脚本中，可以指定-Denv=YOUR-ENVIRONMENT
      • 如果是运行jar文件，需要注意格式是java -Denv=YOUR-ENVIRONMENT -jar xxx.jar
    • 注意key为全小写
  2. 通过操作系统的System Environment
    • 还可以通过操作系统的System Environment ENV来指定
    • 注意key为全大写
  3. 通过配置文件
    • 最后一个推荐的方式是通过配置文件来指定env=YOUR-ENVIRONMENT
    • 对于Mac/Linux，文件位置为/opt/settings/server.properties
    • 对于Windows，文件位置为C:\opt\settings\server.properties

文件内容形如：

env=DEV

目前，env支持以下几个值（大小写不敏感）：

  • DEV
    • Development environment
  • FAT
    • Feature Acceptance Test environment
  • UAT
    • User Acceptance Test environment
  • PRO
    • Production environment

更多环境定义，可以参考Env.java

注：运行时会通过env信息匹配meta server信息，比如env是DEV的话，就会读取apollo-core.jar中apollo-env.properties中的dev_meta信息。如果希望在运行时覆盖meta server信息，有两个方法：

  1. 通过-D{env}_meta=xxx来覆盖，如-Ddev_meta=http://someIp:8080
  2. 准备一份单独的apollo-env.properties，放在程序运行的classpath中，或者放在程序运行目录下，具体可以参考apollo-env.properties的加载逻辑 - ResourceUtils和apollo-env.properties原始文件，需要注意的是在apollo-env.properties中需要用形如{env}.meta=xxx来覆盖，如dev.meta=http://someIp:8080。

1.2.3 本地缓存路径

Apollo客户端会把从服务端获取到的配置在本地文件系统缓存一份，用于在遇到服务不可用，或网络不通的时候，依然能从本地恢复配置，不影响应用正常运行。

本地缓存路径位于以下路径，所以请确保/opt/data或C:\opt\data\目录存在，且应用有读写权限。

  • Mac/Linux: /opt/data/{appId}/config-cache
  • Windows: C:\opt\data\{appId}\config-cache

本地配置文件会以下面的文件名格式放置于本地缓存路径下：

{appId}+{cluster}+{namespace}.properties

  • appId就是应用自己的appId，如100004458
  • cluster就是应用使用的集群，一般在本地模式下没有做过配置的话，就是default
  • namespace就是应用使用的配置namespace，一般是application

文件内容以properties格式存储，比如如果有两个key，一个是request.timeout，另一个是batch，那么文件内容就是如下格式：

request.timeout=2000
batch=2000

注：本地缓存路径也可用于容灾目录，如果应用在所有config service都挂掉的情况下需要扩容，那么也可以先把配置从已有机器上的缓存路径复制到新机器上的相同缓存路径

1.2.4 可选设置

Cluster（集群）

Apollo支持配置按照集群划分，也就是说对于一个appId和一个环境，对不同的集群可以有不同的配置。

如果需要使用这个功能，你可以通过以下方式来指定运行时的集群：

  1. 通过Java System Property
    • 我们可以通过Java的System Property设置apollo.cluster来指定运行时集群（注意key为全小写）
    • 例如，可以在程序启动时通过-Dapollo.cluster=SomeCluster来指定运行时的集群为SomeCluster
  2. 通过配置文件
    • 首先确保/opt/settings/server.properties（Mac/Linux）或C:\opt\settings\server.properties（Windows）在目标机器上存在
    • 在这个文件中，可以设置数据中心集群，如idc=xxx
    • 注意key为全小写

Cluster Precedence（集群顺序）

  1. 如果apollo.cluster和idc同时指定：
    • 我们会首先尝试从apollo.cluster指定的集群加载配置
    • 如果没找到任何配置，会尝试从idc指定的集群加载配置
    • 如果还是没找到，会从默认的集群（default）加载
  2. 如果只指定了apollo.cluster：
    • 我们会首先尝试从apollo.cluster指定的集群加载配置
    • 如果没找到，会从默认的集群（default）加载
  3. 如果只指定了idc：
    • 我们会首先尝试从idc指定的集群加载配置
    • 如果没找到，会从默认的集群（default）加载
  4. 如果apollo.cluster和idc都没有指定：
    • 我们会从默认的集群（default）加载配置

二、Maven Dependency

由于客户端jar包中会包含meta server信息，无法上传一个统一的jar包到中央仓库，所以请按照分布式部署指南的文档说明打包并上传到自己公司的Maven私服。应用在实际使用时只需要按照如下方式引入即可。

    <dependency>
        <groupId>com.ctrip.framework.apollo</groupId>
        <artifactId>apollo-client</artifactId>
        <version>0.10.2</version>
    </dependency>

三、客户端用法

Apollo支持API方式和Spring整合方式，该怎么选择用哪一种方式？

  • API方式灵活，功能完备，配置值实时更新（热发布），支持所有Java环境。
  • Spring方式接入简单，结合Spring有N种酷炫的玩法，如
    • Placeholder方式：
      • 代码中使用，如：@Value("${someKeyFromApollo:someDefaultValue}")
      • application.properties中使用，如：spring.datasource.url: ${someKeyFromApollo:someDefaultValue}
    • Spring boot的@ConfigurationProperties方式
    • 从v0.10.0开始的版本支持placeholder在运行时自动更新，具体参见PR #972。（v0.10.0之前的版本在配置变化后不会重新注入，需要重启才会更新，如果需要配置值实时更新，可以参考后续3.2.2 Spring Placeholder的使用的说明）
  • Spring方式也可以结合API方式使用，如注入Apollo的Config对象，就可以照常通过API方式获取配置了：
  • @ApolloConfig
private Config config; //inject config for namespace application

3.1 API使用方式

API方式是最简单、高效使用Apollo配置的方式，不依赖Spring框架即可使用。

3.1.1 获取默认namespace的配置（application）

Config config = ConfigService.getAppConfig(); //config instance is singleton for each namespace and is never null
String someKey = "someKeyFromDefaultNamespace";
String someDefaultValue = "someDefaultValueForTheKey";
String value = config.getProperty(someKey, someDefaultValue);

通过上述的config.getProperty可以获取到someKey对应的实时最新的配置值。

另外，配置值从内存中获取，所以不需要应用自己做缓存。

3.1.2 监听配置变化事件

监听配置变化事件只在应用真的关心配置变化，需要在配置变化时得到通知时使用，比如：数据库连接串变化后需要重建连接等。

如果只是希望每次都取到最新的配置的话，只需要按照上面的例子，调用config.getProperty即可。

Config config = ConfigService.getAppConfig(); //config instance is singleton for each namespace and is never null
config.addChangeListener(new ConfigChangeListener() {
    @Override
    public void onChange(ConfigChangeEvent changeEvent) {
        System.out.println("Changes for namespace " + changeEvent.getNamespace());
        for (String key : changeEvent.changedKeys()) {
            ConfigChange change = changeEvent.getChange(key);
            System.out.println(String.format("Found change - key: %s, oldValue: %s, newValue: %s, changeType: %s", change.getPropertyName(), change.getOldValue(), change.getNewValue(), change.getChangeType()));
        }
    }
});

3.1.3 获取公共Namespace的配置

String somePublicNamespace = "CAT";
Config config = ConfigService.getConfig(somePublicNamespace); //config instance is singleton for each namespace and is never null
String someKey = "someKeyFromPublicNamespace";
String someDefaultValue = "someDefaultValueForTheKey";
String value = config.getProperty(someKey, someDefaultValue);

3.2 Spring整合方式

3.2.1 配置

Apollo也支持和Spring整合（Spring 3.1.1+），只需要做一些简单的配置就可以了。

Apollo目前既支持比较传统的基于XML的配置，也支持目前比较流行的基于Java（推荐）的配置。

如果是Spring Boot环境，建议参照3.2.1.3-在spring-boot初始bootstrap阶段注入配置配置。

需要注意的是，如果之前有使用org.springframework.beans.factory.config.PropertyPlaceholderConfigurer的，请替换成org.springframework.context.support.PropertySourcesPlaceholderConfigurer。Spring 3.1以后就不建议使用PropertyPlaceholderConfigurer了，要改用PropertySourcesPlaceholderConfigurer。

如果之前有使用<context:property-placeholder>，请注意xml中引入的spring-context.xsd版本需要是3.1以上（一般只要没有指定版本会自动升级的），建议使用不带版本号的形式引入，如：http://www.springframework.org/schema/context/spring-context.xsd

3.2.1.1 基于XML的配置

注：需要把apollo相关的xml namespace加到配置文件头上，不然会报xml语法错误。

1.注入默认namespace的配置到Spring中

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:apollo="http://www.ctrip.com/schema/apollo"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
       http://www.ctrip.com/schema/apollo http://www.ctrip.com/schema/apollo.xsd">
    <!-- 这个是最简单的配置形式，一般应用用这种形式就可以了，用来指示Apollo注入application namespace的配置到Spring环境中 -->
    <apollo:config/>
    <bean class="com.ctrip.framework.apollo.spring.TestXmlBean">
        <property name="timeout" value="${timeout:100}"/>
        <property name="batch" value="${batch:200}"/>
    </bean>
</beans>

2.注入多个namespace的配置到Spring中

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:apollo="http://www.ctrip.com/schema/apollo"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
       http://www.ctrip.com/schema/apollo http://www.ctrip.com/schema/apollo.xsd">
    <!-- 这个是最简单的配置形式，一般应用用这种形式就可以了，用来指示Apollo注入application namespace的配置到Spring环境中 -->
    <apollo:config/>
    <!-- 这个是稍微复杂一些的配置形式，指示Apollo注入FX.apollo和FX.soa namespace的配置到Spring环境中 -->
    <apollo:config namespaces="FX.apollo,FX.soa"/>
    <bean class="com.ctrip.framework.apollo.spring.TestXmlBean">
        <property name="timeout" value="${timeout:100}"/>
        <property name="batch" value="${batch:200}"/>
    </bean>
</beans>

3.注入多个namespace，并且指定顺序

Spring的配置是有顺序的，如果多个property source都有同一个key，那么最终是顺序在前的配置生效。

apollo:config如果不指定order，那么默认是最低优先级。

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:apollo="http://www.ctrip.com/schema/apollo"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
       http://www.ctrip.com/schema/apollo http://www.ctrip.com/schema/apollo.xsd">
    <apollo:config order="2"/>
    <!-- 这个是最复杂的配置形式，指示Apollo注入FX.apollo和FX.soa namespace的配置到Spring环境中，并且顺序在application前面 -->
    <apollo:config namespaces="FX.apollo,FX.soa" order="1"/>
    <bean class="com.ctrip.framework.apollo.spring.TestXmlBean">
        <property name="timeout" value="${timeout:100}"/>
        <property name="batch" value="${batch:200}"/>
    </bean>
</beans>

3.2.1.2 基于Java的配置（推荐）

相对于基于XML的配置，基于Java的配置是目前比较流行的方式。

注意@EnableApolloConfig要和@Configuration一起使用，不然不会生效。

1.注入默认namespace的配置到Spring中

//这个是最简单的配置形式，一般应用用这种形式就可以了，用来指示Apollo注入application namespace的配置到Spring环境中
@Configuration
@EnableApolloConfig
public class AppConfig {
  @Bean
  public TestJavaConfigBean javaConfigBean() {
    return new TestJavaConfigBean();
  }
}

2.注入多个namespace的配置到Spring中

@Configuration
@EnableApolloConfig
public class SomeAppConfig {
  @Bean
  public TestJavaConfigBean javaConfigBean() {
    return new TestJavaConfigBean();
  }
} 
//这个是稍微复杂一些的配置形式，指示Apollo注入FX.apollo和FX.soa namespace的配置到Spring环境中
@Configuration
@EnableApolloConfig({"FX.apollo", "FX.soa"})
public class AnotherAppConfig {}

3.注入多个namespace，并且指定顺序

//这个是最复杂的配置形式，指示Apollo注入FX.apollo和FX.soa namespace的配置到Spring环境中，并且顺序在application前面
@Configuration
@EnableApolloConfig(order = 2)
public class SomeAppConfig {
  @Bean
  public TestJavaConfigBean javaConfigBean() {
    return new TestJavaConfigBean();
  }
}
@Configuration
@EnableApolloConfig(value = {"FX.apollo", "FX.soa"}, order = 1)
public class AnotherAppConfig {}

3.2.1.3 在Spring Boot初始bootstrap阶段注入配置

使用上述两种方式的配置形式后，Apollo会在Spring的postProcessBeanFactory阶段注入配置到Spring的Environment中，早于bean的初始化阶段，所以对于普通的bean注入配置场景已经能很好的满足。

不过Spring Boot有一些场景需要配置在更早的阶段注入，比如使用@ConditionalOnProperty的场景或者是有一些spring-boot-starter在启动阶段就需要读取配置做一些事情（如spring-boot-starter-dubbo)，所以对于Spring Boot环境建议通过以下方式来接入Apollo(需要0.10.0及以上版本）。

使用方式很简单，只需要在application.properties/bootstrap.properties中按照如下样例配置即可。

  1. 在bootstrap阶段注入默认application namespace的配置示例
     # will inject 'application' namespace in bootstrap phase
     apollo.bootstrap.enabled = true
  1. 在bootstrap阶段注入非默认application namespace或多个namespace的配置示例
     apollo.bootstrap.enabled = true
     # will inject 'application' and 'FX.apollo' namespaces in bootstrap phase
     apollo.bootstrap.namespaces = application,FX.apollo

3.2.2 Spring Placeholder的使用

Spring应用通常会使用Placeholder来注入配置，使用的格式形如${someKey:someDefaultValue}，如${timeout:100}。冒号前面的是key，冒号后面的是默认值。

建议在实际使用时尽量给出默认值，以免由于key没有定义导致运行时错误。

从v0.10.0开始的版本支持placeholder在运行时自动更新，具体参见PR #972。

如果需要关闭placeholder在运行时自动更新功能，可以通过以下两种方式关闭：

  1. 通过设置System Property apollo.autoUpdateInjectedSpringProperties，如启动时传入-Dapollo.autoUpdateInjectedSpringProperties=false
  2. 通过设置META-INF/app.properties中的apollo.autoUpdateInjectedSpringProperties属性，如
app.id=SampleApp
apollo.autoUpdateInjectedSpringProperties=false

对于v0.10.0之前的版本，placeholder只会在启动的时候赋值，在运行过程中即便在Apollo上修改发布了配置，placeholder的值也不会更新。如果需要运行时动态更新placeholder的值，有以下几种方式:

  1. 程序监听Apollo的ConfigChangeListener（如@ApolloConfigChangeListener），然后通过自己的代码来更新placeholder的值。
  2. 不使用placeholder方式获取配置，而是直接从config对象中获取配置。样例代码可以参考3.2.3 Spring Annotation支持的getBatch和getTimeout方法。
  3. 【推荐】使用Spring Cloud的RefreshScope

3.2.2.1 XML使用方式

假设我有一个TestXmlBean，它有两个配置项需要注入：

public class TestXmlBean {
  private int timeout;
  private int batch;
  public void setTimeout(int timeout) {
    this.timeout = timeout;
  }
  public void setBatch(int batch) {
    this.batch = batch;
  }
  public int getTimeout() {
    return timeout;
  }
  public int getBatch() {
    return batch;
  }
}

那么，我在XML中会使用如下方式来定义（假设应用默认的application namespace中有timeout和batch的配置项）：

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:apollo="http://www.ctrip.com/schema/apollo"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
       http://www.ctrip.com/schema/apollo http://www.ctrip.com/schema/apollo.xsd">
    <apollo:config/>
    <bean class="com.ctrip.framework.apollo.spring.TestXmlBean">
        <property name="timeout" value="${timeout:100}"/>
        <property name="batch" value="${batch:200}"/>
    </bean>
</beans>

3.2.2.2 Java Config使用方式

假设我有一个TestJavaConfigBean，通过Java Config的方式还可以使用@Value的方式注入：

public class TestJavaConfigBean {
  @Value("${timeout:100}")
  private int timeout;
  private int batch;
  @Value("${batch:200}")
  public void setBatch(int batch) {
    this.batch = batch;
  }
  public int getTimeout() {
    return timeout;
  }
  public int getBatch() {
    return batch;
  }
}

在Configuration类中按照下面的方式使用（假设应用默认的application namespace中有timeout和batch的配置项）：

@Configuration
@EnableApolloConfig
public class AppConfig {
  @Bean
  public TestJavaConfigBean javaConfigBean() {
    return new TestJavaConfigBean();
  }
}

3.2.2.3 ConfigurationProperties使用方式

Spring Boot提供了@ConfigurationProperties把配置注入到bean对象中。

Apollo也支持这种方式，下面的例子会把redis.cache.expireSeconds和redis.cache.commandTimeout分别注入到SampleRedisConfig的expireSeconds和commandTimeout字段中。

@ConfigurationProperties(prefix = "redis.cache")
public class SampleRedisConfig {
  private int expireSeconds;
  private int commandTimeout;
  public void setExpireSeconds(int expireSeconds) {
    this.expireSeconds = expireSeconds;
  }
  public void setCommandTimeout(int commandTimeout) {
    this.commandTimeout = commandTimeout;
  }
}

在Configuration类中按照下面的方式使用（假设应用默认的application namespace中有redis.cache.expireSeconds和redis.cache.commandTimeout的配置项）：

@Configuration
@EnableApolloConfig
public class AppConfig {
  @Bean
  public SampleRedisConfig sampleRedisConfig() {
    return new SampleRedisConfig();
  }
}

需要注意的是，@ConfigurationProperties如果需要在Apollo配置变化时自动更新注入的值，需要配合Spring Cloud的RefreshScope使用。相关代码实现，可以参考apollo-demo项目中的SampleRedisConfig.java和SpringBootApolloRefreshConfig.java

3.2.3 Spring Annotation支持

Apollo同时还增加了两个新的Annotation来简化在Spring环境中的使用。

  1. @ApolloConfig
    • 用来自动注入Config对象
  2. @ApolloConfigChangeListener
    • 用来自动注册ConfigChangeListener

使用样例如下：

public class TestApolloAnnotationBean {
  @ApolloConfig
  private Config config; //inject config for namespace application
  @ApolloConfig("application")
  private Config anotherConfig; //inject config for namespace application
  @ApolloConfig("FX.apollo")
  private Config yetAnotherConfig; //inject config for namespace FX.apollo
  @Value("${batch:100}")
  private int batch;
  //config change listener for namespace application
  @ApolloConfigChangeListener
  private void someOnChange(ConfigChangeEvent changeEvent) {
    //update injected value of batch if it is changed in Apollo
    if (changeEvent.isChanged("batch")) {
      batch = config.getIntProperty("batch", 100);
    }
  }
  //config change listener for namespace application
  @ApolloConfigChangeListener("application")
  private void anotherOnChange(ConfigChangeEvent changeEvent) {
    //do something
  }
  //config change listener for namespaces application and FX.apollo
  @ApolloConfigChangeListener({"application", "FX.apollo"})
  private void yetAnotherOnChange(ConfigChangeEvent changeEvent) {
    //do something
  }
  //example of getting config from Apollo directly
  //this will always return the latest value of timeout
  public int getTimeout() {
    return config.getIntProperty("timeout", 200);
  }
  //example of getting config from injected value
  //the program needs to update the injected value when batch is changed in Apollo using @ApolloConfigChangeListener shown above
  public int getBatch() {
    return this.batch;
  }
}

在Configuration类中按照下面的方式使用：

@Configuration
@EnableApolloConfig
public class AppConfig {
  @Bean
  public TestApolloAnnotationBean testApolloAnnotationBean() {
    return new TestApolloAnnotationBean();
  }
}

3.2.4 已有配置迁移

很多情况下，应用可能已经有不少配置了，比如Spring Boot的应用，就会有bootstrap.properties, application.properties等配置。

在应用接入Apollo之后，这些配置是可以非常方便的迁移到Apollo的，具体步骤如下：

  1. 在Apollo为应用新建项目
  2. 在应用中配置好META-INF/app.properties
  3. 把原先配置（必须是properties格式）复制一下，然后通过Apollo提供的文本编辑模式全部粘帖到应用的application namespace，发布配置
  4. 把原先的配置文件如bootstrap.properties, application.properties从项目中删除
    • 如果需要保留本地配置文件，需要注意部分配置如server.port必须确保本地文件已经删除该配置项

如：

spring.application.name = reservation-service
server.port = 8080
logging.level = ERROR
eureka.client.serviceUrl.defaultZone = http://127.0.0.1:8761/eureka/
eureka.client.healthcheck.enabled = true
eureka.client.registerWithEureka = true
eureka.client.fetchRegistry = true
eureka.client.eurekaServiceUrlPollIntervalSeconds = 60
eureka.instance.preferIpAddress = true

3.3 Demo

项目中有一个样例客户端的项目：apollo-demo，具体信息可以参考Apollo开发指南中的2.3 Java样例客户端启动部分。

更多使用案例Demo可以参考Apollo使用场景和示例代码。

四、客户端设计

 

上图简要描述了Apollo客户端的实现原理：

  1. 客户端和服务端保持了一个长连接，从而能第一时间获得配置更新的推送。（通过Http Long Polling实现）
  2. 客户端还会定时从Apollo配置中心服务端拉取应用的最新配置。
    • 这是一个fallback机制，为了防止推送机制失效导致配置不更新
    • 客户端定时拉取会上报本地版本，所以一般情况下，对于定时拉取的操作，服务端都会返回304 - Not Modified
    • 定时频率默认为每5分钟拉取一次，客户端也可以通过在运行时指定System Property: apollo.refreshInterval来覆盖，单位为分钟。
  3. 客户端从Apollo配置中心服务端获取到应用的最新配置后，会保存在内存中
  4. 客户端会把从服务端获取到的配置在本地文件系统缓存一份
    • 在遇到服务不可用，或网络不通的时候，依然能从本地恢复配置
  5. 应用程序可以从Apollo客户端获取最新的配置、订阅配置更新通知

五、本地开发模式

Apollo客户端还支持本地开发模式，这个主要用于当开发环境无法连接Apollo服务器的时候，比如在邮轮、飞机上做相关功能开发。

在本地开发模式下，Apollo只会从本地文件读取配置信息，不会从Apollo服务器读取配置。

可以通过下面的步骤开启Apollo本地开发模式。

5.1 修改环境

修改/opt/settings/server.properties（Mac/Linux）或C:\opt\settings\server.properties（Windows）文件，设置env为Local：

env=Local

更多配置环境的方式请参考1.2.2 Environment

5.2 准备本地配置文件

在本地开发模式下，Apollo客户端会从本地读取文件，所以我们需要事先准备好配置文件。

5.2.1 本地配置目录

本地配置目录位于：

  • Mac/Linux: /opt/data/{appId}/config-cache
  • Windows: C:\opt\data\{appId}\config-cache

appId就是应用的appId，如100004458。

请确保该目录存在，且应用程序对该目录有读权限。

【小技巧】 推荐的方式是先在普通模式下使用Apollo，这样Apollo会自动创建该目录并在目录下生成配置文件。

5.2.2 本地配置文件

本地配置文件需要按照一定的文件名格式放置于本地配置目录下，文件名格式如下：

{appId}+{cluster}+{namespace}.properties

  • appId就是应用自己的appId，如100004458
  • cluster就是应用使用的集群，一般在本地模式下没有做过配置的话，就是default
  • namespace就是应用使用的配置namespace，一般是application

文件内容以properties格式存储，比如如果有两个key，一个是request.timeout，另一个是batch，那么文件内容就是如下格式：

request.timeout=2000
batch=2000

5.3 修改配置

在本地开发模式下，Apollo不会实时监测文件内容是否有变化，所以如果修改了配置，需要重启应用生效。

声明：本文内容由网友自发贡献，不代表【wpsshop博客】立场，版权归原作者所有，本站不承担相应法律责任。如您发现有侵权的内容，请联系我们。转载请注明出处：https://www.wpsshop.cn/w/IT小白/article/detail/478449
推荐阅读
相关标签

Copyright © 2003-2013 www.wpsshop.cn 版权所有，并保留所有权利。

  

闽ICP备14008679号