準備工作
環境要求
- Java: 1.7+
- Guava: 15.0+(Apollo用戶端預設會引用Guava 19,如果你的項目引用了其它版本,請確定版本号大于等于15.0)
必選設定
Apollo用戶端依賴于AppId,Apollo Meta Server等環境資訊來工作,是以請確定閱讀下面的說明并且做正确的配置
1.AppId
AppId是應用的身份資訊,是從服務端擷取配置的一個重要資訊。有以下幾種方式設定,按照優先級從高到低分别為:
(1)System Property
Apollo 0.7.0+支援通過System Property傳入app.id資訊,如-Dapp.id=YOUR-APP-ID
(2)作業系統的System Environment
Apollo 1.4.0+支援通過作業系統的System Environment APP_ID來傳入app.id資訊,如APP_ID=YOUR-APP-ID
(3)Spring Boot application.properties
Apollo 1.0.0+支援通過Spring Boot的application.properties檔案配置,如app.id=YOUR-APP-ID,該配置方式不适用于多個war包部署在同一個tomcat的使用場景
(4)app.properties
確定classpath:/META-INF/app.properties檔案存在,并且其中内容形如:app.id=YOUR-APP-ID檔案位置參考如下:
注:app.id是用來辨別應用身份的唯一id,格式為string
2.Apollo Meta Server
Apollo支援應用在不同的環境有不同的配置,是以需要在運作提供給Apollo用戶端目前環境的Apollo Meta Server資訊。預設情況下,meta server和config service是部署在同一個JVM程序,是以meta server的位址就是config service的位址
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的使用場景)
(3)通過作業系統的System EnvironmentAPOLLO_META
- 可以通過作業系統的System Environment APOLLO_META來指定
- 注意key為全大寫,且中間是_分隔
(4)通過server.properties配置檔案(推薦)
- 可以在server.properties配置檔案中指定apollo.meta=http://config-service-url
- 對于Mac/Linux,檔案位置為/opt/settings/server.properties
- 對于Windows,檔案位置為C:\opt\settings\server.properties
(5)通過app.properties配置檔案
可以在classpath:/META-INF/app.properties指定apollo.meta=http://config-service-url
(6)通過Java system property ${env}_meta
- 如果目前env是dev,那麼使用者可以配置-Ddev_meta=http://config-service-url
- 使用該配置方式,那麼就必須要正确配置Environment
(7)通過作業系統的System Environment ${ENV}_META (1.2.0版本開始支援)
- 如果目前env是dev,那麼使用者可以配置作業系統的System Environment DEV_META=http://config-service-url
- 注意key為全大寫
- 使用該配置方式,那麼就必須要正确配置Environment,詳見1.2.4.1 Environment
(8)通過apollo-env.properties檔案
- 使用者也可以建立一個apollo-env.properties,放在程式的classpath下,或者放在spring boot應用的config目錄下
- 使用該配置方式,那麼就必須要正确配置Environment,詳見1.2.4.1 Environment
- 檔案内容形如:
dev.meta=http://1.1.1.1:8080
fat.meta=http://apollo.fat.xxx.com
uat.meta=http://apollo.uat.xxx.com
pro.meta=http://apollo.xxx.com
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
自定義緩存路徑
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都挂掉的情況下需要擴容,那麼也可以先把配置從已有機器上的緩存路徑複制到新機器上的相同緩存路徑
4.可選設定
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)
注:這裡還有叢集、叢集順序、配置通路等相關請檢視官文
樣例:建議開發本地建立server.properties檔案,是apollo配置與業務代碼解耦;
Maven依賴
用戶端用法
Apollo支援API方式和Spring整合方式,該怎麼選擇用哪一種方式?
API方式靈活,功能完備,配置值實時更新(熱釋出),支援所有Java環境。
- Spring方式接入簡單,結合Spring有N種酷炫的玩法,如
- Placeholder方式:
- 代碼中直接使用,如:@Value("${someKeyFromApollo:someDefaultValue}")
- 配置檔案中使用替換placeholder,如:spring.datasource.url: ${someKeyFromApollo:someDefaultValue}
- 直接托管spring的配置,如在apollo中直接配置spring.datasource.url=jdbc:mysql://localhost:3306/somedb?characterEncoding=utf8
- Placeholder方式:
2. Spring boot的@ConfigurationProperties方式(這種不會自動重新整理,需要配合@RefreshScope和手動重新整理方法實作自動重新整理)
手動重新整理方法如下
- Spring方式也可以結合API方式使用,如注入Apollo的Config對象,就可以照常通過API方式擷取配置了:
有配置遷移
很多情況下,應用可能已經有不少配置了,比如Spring Boot的應用,就會有bootstrap.properties/yml, application.properties/yml等配置。
在應用接入Apollo之後,這些配置是可以非常友善的遷移到Apollo的,具體步驟如下:
- 在Apollo為應用建立項目
- 在應用中配置好META-INF/app.properties
- 建議把原先配置先轉為properties格式,然後通過Apollo提供的文本編輯模式全部粘帖到應用的application namespace,釋出配置(如果原來格式是yml,可以使用YamlPropertiesFactoryBean.getObject轉成properties格式)
- 如果原來是yml,想繼續使用yml來編輯配置,那麼可以建立私有的application.yml namespace,把原來的配置全部粘貼進去,釋出配置(需要apollo-client是1.3.0及以上版本)
- 把原先的配置檔案如bootstrap.properties/yml, application.properties/yml從項目中删除(如果需要保留本地配置檔案,需要注意部配置設定置如server.port必須確定本地檔案已經删除該配置項)
如:
其他問題
eureka統一注冊
Apollo預設自帶了Eureka作為内部的注冊中心實作,一般情況下不需要考慮為Apollo單獨部署注冊中心。不過有些公司自己已經有了一套Eureka,如果希望把Apollo的Config Service和Admin Service也注冊過去實作統一管理的話,可以按照如下步驟操作:
- 配置Config Service不啟動内置Eureka Server
為apollo-configservice配置apollo.eureka.server.enabled=false即可,通過bootstrap.yml或-D參數等方式皆可。
- 修改ApolloConfigDB.ServerConfig表中的eureka.service.url,指向自己的Eureka位址
比如自己的Eureka服務位址是1.1.1.1:8761和2.2.2.2:8761,那麼就将ApolloConfigDB.ServerConfig表中設定eureka.service.url為:
http://1.1.1.1:8761/eureka/,http://2.2.2.2:8761/eureka/
需要注意的是更改Eureka位址隻需要改ApolloConfigDB.ServerConfig表中的eureka.service.url即可,不需要修改meta server位址。預設情況下,meta service和config service是部署在同一個JVM程序,是以meta service的位址就是config service的位址,修改Eureka位址時不需要修改meta server位址。