一、准备工作

1.1 环境要求

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

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

1.2 必选设置

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

1.2.1 AppId

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

有以下几种方式设置，按照优先级从高到低分别为：

  1. System Property

Apollo 0.7.0+支持通过System Property传入app.id信息，如

  1. -Dapp.id=YOUR-APP-ID
  1. 操作系统的System Environment

Apollo 1.4.0+支持通过操作系统的System Environment APP_ID来传入app.id信息，如

  1. APP_ID=YOUR-APP-ID
  1. Spring Boot application.properties

Apollo 1.0.0+支持通过Spring Boot的application.properties文件配置，如

  1. app.id=YOUR-APP-ID

该配置方式不适用于多个war包部署在同一个tomcat的使用场景

  1. app.properties

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

app.id=YOUR-APP-ID

文件位置参考如下：

app-id-location

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

1.2.2 Apollo Meta Server

Apollo支持应用在不同的环境有不同的配置，所以需要在运行提供给Apollo客户端当前环境的Apollo Meta Server信息。默认情况下，meta server和config service是部署在同一个JVM进程，所以meta server的地址就是config service的地址。

为了实现meta server的高可用，推荐通过SLB（Software Load Balancer）做动态负载均衡。Meta server地址也可以填入IP，如http://1.1.1.1:8080,http://2.2.2.2:8080，不过生产环境还是建议使用域名（走slb），因为机器扩容、缩容等都可能导致IP列表的变化。

1.0.0版本开始支持以下方式配置apollo meta server信息，按照优先级从高到低分别为：

  1. 通过Java System Property apollo.meta
    • 可以通过Java的System Property apollo.meta来指定
    • 在Java程序启动脚本中，可以指定-Dapollo.meta=http://config-service-url
      • 如果是运行jar文件，需要注意格式是java -Dapollo.meta=http://config-service-url -jar xxx.jar
    • 也可以通过程序指定，如System.setProperty("apollo.meta", "http://config-service-url");
  2. 通过Spring Boot的配置文件
    • 可以在Spring Boot的application.properties或bootstrap.properties中指定apollo.meta=http://config-service-url

该配置方式不适用于多个war包部署在同一个tomcat的使用场景

  1. 通过操作系统的System EnvironmentAPOLLO_META
    • 可以通过操作系统的System Environment APOLLO_META来指定
    • 注意key为全大写，且中间是_分隔
  2. 通过server.properties配置文件
    • 可以在server.properties配置文件中指定apollo.meta=http://config-service-url
    • 对于Mac/Linux，文件位置为/opt/settings/server.properties
    • 对于Windows，文件位置为C:\opt\settings\server.properties
  3. 通过app.properties配置文件
    • 可以在classpath:/META-INF/app.properties指定apollo.meta=http://config-service-url
  4. 通过Java system property ${env}_meta
    • 如果当前env是dev，那么用户可以配置-Ddev_meta=http://config-service-url
    • 使用该配置方式，那么就必须要正确配置Environment，详见1.2.4.1 Environment
  5. 通过操作系统的System Environment ${ENV}_META (1.2.0版本开始支持)
    • 如果当前env是dev，那么用户可以配置操作系统的System Environment DEV_META=http://config-service-url
    • 注意key为全大写
    • 使用该配置方式，那么就必须要正确配置Environment，详见1.2.4.1 Environment
  6. 通过apollo-env.properties文件
    • 用户也可以创建一个apollo-env.properties，放在程序的classpath下，或者放在spring boot应用的config目录下
    • 使用该配置方式，那么就必须要正确配置Environment，详见1.2.4.1 Environment
    • 文件内容形如：
  1. dev.meta=http://1.1.1.1:8080
  2. fat.meta=http://apollo.fat.xxx.com
  3. uat.meta=http://apollo.uat.xxx.com
  4. pro.meta=http://apollo.xxx.com

如果通过以上各种手段都无法获取到Meta Server地址，Apollo最终会fallback到http://apollo.meta作为Meta Server地址

1.2.2.1 自定义Apollo Meta Server地址定位逻辑

在1.0.0版本中，Apollo提供了MetaServerProvider SPI，用户可以注入自己的MetaServerProvider来自定义Meta Server地址定位逻辑。

由于我们使用典型的Java Service Loader模式，所以实现起来还是比较简单的。

有一点需要注意的是，apollo会在运行时按照顺序遍历所有的MetaServerProvider，直到某一个MetaServerProvider提供了一个非空的Meta Server地址，因此用户需要格外注意自定义MetaServerProvider的Order。规则是较小的Order具有较高的优先级，因此Order=0的MetaServerProvider会排在Order=1的MetaServerProvider的前面。

如果你的公司有很多应用需要接入Apollo，建议封装一个jar包，然后提供自定义的Apollo Meta Server定位逻辑，从而可以让接入Apollo的应用零配置使用。比如自己写一个xx-company-apollo-client，该jar包依赖apollo-client，在该jar包中通过spi方式定义自定义的MetaServerProvider实现，然后应用直接依赖xx-company-apollo-client即可。

MetaServerProvider的实现可以参考LegacyMetaServerProvider和DefaultMetaServerProvider。

1.2.2.2 跳过Apollo Meta Server服务发现

适用于apollo-client 0.11.0及以上版本

一般情况下都建议使用Apollo的Meta Server机制来实现Config Service的服务发现，从而可以实现Config Service的高可用。不过apollo-client也支持跳过Meta Server服务发现，主要用于以下场景：

  1. Config Service部署在公有云上，注册到Meta Server的是内网地址，本地开发环境无法直接连接
    • 如果通过公网 SLB 对外暴露 Config Service的话，记得要设置 IP 白名单，避免数据泄露
  2. Config Service部署在docker环境中，注册到Meta Server的是docker内网地址，本地开发环境无法直接连接
  3. Config Service部署在kubernetes中，希望使用kubernetes自带的服务发现能力（Service）

针对以上场景，可以通过直接指定Config Service地址的方式来跳过Meta Server服务发现，按照优先级从高到低分别为：

  1. 通过Java System Property apollo.configService
    • 可以通过Java的System Property apollo.configService来指定
    • 在Java程序启动脚本中，可以指定-Dapollo.configService=http://config-service-url:port
      • 如果是运行jar文件，需要注意格式是java -Dapollo.configService=http://config-service-url:port -jar xxx.jar
    • 也可以通过程序指定，如System.setProperty("apollo.configService", "http://config-service-url:port");
  2. 通过操作系统的System EnvironmentAPOLLO_CONFIGSERVICE
    • 可以通过操作系统的System Environment APOLLO_CONFIGSERVICE来指定
    • 注意key为全大写，且中间是_分隔
  3. 通过server.properties配置文件
    • 可以在server.properties配置文件中指定apollo.configService=http://config-service-url:port
    • 对于Mac/Linux，文件位置为/opt/settings/server.properties
    • 对于Windows，文件位置为C:\opt\settings\server.properties

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 client-local-cache

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

  1. request.timeout=2000
  2. batch=2000

1.2.3.1 自定义缓存路径

1.0.0版本开始支持以下方式自定义缓存路径，按照优先级从高到低分别为：

  1. 通过Java System Property apollo.cacheDir
    • 可以通过Java的System Property apollo.cacheDir来指定
    • 在Java程序启动脚本中，可以指定-Dapollo.cacheDir=/opt/data/some-cache-dir
      • 如果是运行jar文件，需要注意格式是java -Dapollo.cacheDir=/opt/data/some-cache-dir -jar xxx.jar
    • 也可以通过程序指定，如System.setProperty("apollo.cacheDir", "/opt/data/some-cache-dir");
  2. 通过Spring Boot的配置文件
    • 可以在Spring Boot的application.properties或bootstrap.properties中指定apollo.cacheDir=/opt/data/some-cache-dir
  3. 通过操作系统的System EnvironmentAPOLLO_CACHEDIR
    • 可以通过操作系统的System Environment APOLLO_CACHEDIR来指定
    • 注意key为全大写，且中间是_分隔
  4. 通过server.properties配置文件
    • 可以在server.properties配置文件中指定apollo.cacheDir=/opt/data/some-cache-dir
    • 对于Mac/Linux，文件位置为/opt/settings/server.properties
    • 对于Windows，文件位置为C:\opt\settings\server.properties

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

1.2.4 可选设置

1.2.4.1 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

文件内容形如：

  1. env=DEV

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

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

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

1.2.4.2 Cluster（集群）

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

1.0.0版本开始支持以下方式集群，按照优先级从高到低分别为：

  1. 通过Java System Property apollo.cluster
    • 可以通过Java的System Property apollo.cluster来指定
    • 在Java程序启动脚本中，可以指定-Dapollo.cluster=SomeCluster
      • 如果是运行jar文件，需要注意格式是java -Dapollo.cluster=SomeCluster -jar xxx.jar
    • 也可以通过程序指定，如System.setProperty("apollo.cluster", "SomeCluster");
  2. 通过Spring Boot的配置文件
    • 可以在Spring Boot的application.properties或bootstrap.properties中指定apollo.cluster=SomeCluster
  3. 通过Java System Property
    • 可以通过Java的System Property idc来指定环境
    • 在Java程序启动脚本中，可以指定-Didc=xxx
      • 如果是运行jar文件，需要注意格式是java -Didc=xxx -jar xxx.jar
    • 注意key为全小写
  4. 通过操作系统的System Environment
    • 还可以通过操作系统的System Environment IDC来指定
    • 注意key为全大写
  5. 通过server.properties配置文件
    • 可以在server.properties配置文件中指定idc=xxx
    • 对于Mac/Linux，文件位置为/opt/settings/server.properties
    • 对于Windows，文件位置为C:\opt\settings\server.properties

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）加载配置

1.2.4.3 设置内存中的配置项是否保持和页面上的顺序一致

适用于1.6.0及以上版本

默认情况下，apollo client内存中的配置存放在Properties中（底下是Hashtable），不会刻意保持和页面上看到的顺序一致，对绝大部分的场景是没有影响的。不过有些场景会强依赖配置项的顺序（如spring cloud zuul的路由规则），针对这种情况，可以开启OrderedProperties特性来使得内存中的配置顺序和页面上看到的一致。

配置方式按照优先级从高到低分别为：

  1. 通过Java System Property apollo.property.order.enable
    • 可以通过Java的System Property apollo.property.order.enable来指定
    • 在Java程序启动脚本中，可以指定-Dapollo.property.order.enable=true
      • 如果是运行jar文件，需要注意格式是java -Dapollo.property.order.enable=true -jar xxx.jar
    • 也可以通过程序指定，如System.setProperty("apollo.property.order.enable", "true");
  2. 通过Spring Boot的配置文件
    • 可以在Spring Boot的application.properties或bootstrap.properties中指定apollo.property.order.enable=true
  3. 通过app.properties配置文件
    • 可以在classpath:/META-INF/app.properties指定apollo.property.order.enable=true

1.2.4.4 配置访问密钥

适用于1.6.0及以上版本

Apollo从1.6.0版本开始增加访问密钥机制，从而只有经过身份验证的客户端才能访问敏感配置。如果应用开启了访问密钥，客户端需要配置密钥，否则无法获取配置。

配置方式按照优先级从高到低分别为：

  1. 通过Java System Property apollo.accesskey.secret
    • 可以通过Java的System Property apollo.accesskey.secret来指定
    • 在Java程序启动脚本中，可以指定-Dapollo.accesskey.secret=1cf998c4e2ad4704b45a98a509d15719
      • 如果是运行jar文件，需要注意格式是java -Dapollo.accesskey.secret=1cf998c4e2ad4704b45a98a509d15719 -jar xxx.jar
    • 也可以通过程序指定，如System.setProperty("apollo.accesskey.secret", "1cf998c4e2ad4704b45a98a509d15719");
  2. 通过Spring Boot的配置文件
    • 可以在Spring Boot的application.properties或bootstrap.properties中指定apollo.accesskey.secret=1cf998c4e2ad4704b45a98a509d15719
  3. 通过操作系统的System Environment
    • 还可以通过操作系统的System Environment APOLLO_ACCESSKEY_SECRET来指定
    • 注意key为全大写
  4. 通过app.properties配置文件
    • 可以在classpath:/META-INF/app.properties指定apollo.accesskey.secret=1cf998c4e2ad4704b45a98a509d15719