简介Apollo 1.4.0 源码适配包面向需要将 Apollo 配置中心数据源从 MySQL 切换为 PostgreSQL 的 Java 开发与运维人员。官方默认仅支持 MySQL该压缩包通过改动源码解除此限制适配 PostgreSQL 11.4并集成 42.2.5 版本 JDBC 驱动。资源共 2000 个文件约 11.46MB包含 646 个 Java 源文件、607 个编译后的 class 文件、64 个 SQL 脚本、61 个 XML 与 40 个 yml 配置以及构建脚本、Dockerfile、前端静态资源等便于直接查看改动点、编译部署或按需二次调整。.properties 与 yml 为主的配置模块和 SQL 初始化脚本均保持完整可快速定位数据源相关的全部改动。内容预览中的 README 与 build.bat 提示包内保留构建说明和编译入口ReleaseService 等核心类则有助于追踪服务端改造逻辑。目前已有 4184 人学习/下载适合正在规划 Apollo 数据源扩展或需要落地 PostgreSQL 高可用方案的团队参考。1. 拿到 apollo-1.4.0.zip 先别急着解压先搞清它解决什么问题一个微服务拆到十几个之后配置管理就会变成最磨人的杂活。改一个开关要登服务器改文件再重启开发、测试、生产三套环境各改各的时间一长连自己都记不清哪台机器上的配置是新的。apollo-1.4.0.zip 这个压缩包对应的就是一套开源的分布式配置中心核心作用是把散落在各服务里的配置收拢到一个管理界面上发布之后客户端自动感知、动态刷新不用再为改配置重启服务。1.4.0 这个版本在配置中心里属于被验证得比较充分的一个版本部署方式不复杂单台机器就能跑完整套环境。这篇笔记适合正在搭微服务基座、想自己先跑通 Config Service、Admin Service、Portal 三个服务的团队也适合手里只有这个 zip 包、想搞明白从解压到客户端接入完整链路的人。2. 部署前准备环境核对、数据库初始化、解压三件套2.1 Java 环境与端口占用两个容易忽略的前置条件Apollo 的服务端是 Spring Boot 打的包启动脚本本质上是 Java 进程所以第一件事是确认机器上有 JDK。1.4.0 这个版本要求 JDK 8 及以上我一般会用java -version先看一眼确认不是只装了 JRE 就动手。很多部署卡在启动脚本报Unable to locate a Java Runtime这种错根源就是 PATH 里没找到 java 或者 JAVA_HOME 指错了位置。端口方面默认端口是固定的Config Service 是 8080Admin Service 是 8090Portal 是 8070。部署前用下面命令确认这些端口没被别的进程占用我用的是 Golang 项目里常见的lsofLinux 上也可以换ss -lntp。lsof -i :8080 -i :8090 -i :8070提示如果机器上同时跑着别的 Java 应用8080 被占用的概率很高。不建议为了迁就端口去改系统里其他应用的配置直接改 Apollo 的server.port更干净后面会讲到具体改哪几个文件。内存方面三个服务加起来大约需要 1.5GB 左右的堆内存如果机器本身只有 2GB建议只部署 Config Service 和 PortalAdmin Service 可以等用到管理功能时再起。这个取舍在初期验证阶段完全够用。2.2 初始化数据库两套 SQL 脚本的区别与执行顺序服务端有三个模块但数据库只需要两个库ApolloPortalDB 和 ApolloConfigDB。PortalDB 存的是用户、权限、项目列表这类管理数据ConfigDB 存的是真正的配置内容、发布历史、灰度规则。解压后 sql 目录下一般能看到两个脚本分别对应这两个库。一个常见的误操作是只导入了 ConfigDB结果 Portal 能登录但看不到任何项目。两个库都要建而且字符集建议直接指定utf8mb4原因是配置内容里可能出现特殊字符或扩展字符集内容默认的 latin1 会直接导致乱码。mysql -u root -p -e CREATE DATABASE ApolloPortalDB DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; mysql -u root -p -e CREATE DATABASE ApolloConfigDB DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; mysql -u root -p ApolloPortalDB apolloportaldb.sql mysql -u root -p ApolloConfigDB apolloconfigdb.sql这里先建库再导数据顺序不能反。如果先导数据再建库MySQL 会直接报Unknown database。脚本执行完毕后可以用SHOW TABLES;各看一眼PortalDB 里常见的是users、permissions这类表ConfigDB 里应该能看到app、item、release等表。看到这些表基本说明导入成功了。2.3 解压后该认得哪些目录配置文件的改动范围zip 包解压后常见做法是得到一个或多个按模块命名的目录每个目录里都有conf和scripts两个关键目录。conf里放着application.properties和startup.sh这两个文件就是要改的全部scripts里是启动辅助脚本正常不需要动。我第一次部署时把所有文件都翻了一遍后来发现真正需要改的就三类数据源连接串、Eureka 地址、Portal 的访问地址。其他配置保持默认即可。这个认知能帮你省不少时间——不要被目录里大量配置文件干扰Apollo 的默认行为已经适合大多数场景。3. 单机部署三个服务从配置修改到启动验证3.1 修改 configservice 与 adminservice 的配置先处理 Config Service。进入它的conf目录打开application.properties主要改数据源。默认文件里会有一段 Spring 数据源的配置需要替换成你自己的 MySQL 地址、账号、密码。关键是要在连接串里带characterEncodingutf8和serverTimezone否则后面启动时可能报时区错误或者出现中文乱码。spring.datasource.url jdbc:mysql://127.0.0.1:3306/ApolloConfigDB?characterEncodingutf8serverTimezoneAsia/Shanghai spring.datasource.username root spring.datasource.password your_passwordConfig Service 内部嵌了 Eureka所以它自己不需要额外指定注册中心地址只要保证数据库能连上即可。Admin Service 的配置改动方式和它一样只是连接的数据库同样是ApolloConfigDB两个服务共享这一个库。这里有个细节Admin Service 的application.properties里需要指定eureka.service.url指向 Config Service 的地默认值是http://127.0.0.1:8080/eureka/单机部署不用改但如果是多机部署就要把127.0.0.1换成 Config Service 所在机器的实际 IP。eureka.service.url http://127.0.0.1:8080/eureka/注意很多部署问题出在把 Config Service 和 Admin Service 的 IP 写成了localhost而客户端或 Portal 在另一台机器上解析不到。单机验证无所谓一旦要给别人访问统一用内网 IP。3.2 配置 portal数据源、地址、登录账号Portal 是管理界面配置项比前两个多一处。它的application.properties同样要改数据源但连接的是ApolloPortalDB而不是 ConfigDB。这一点最容易糊涂。另外还要配置 Admin Service 的访问地址Portal 管理配置时实际是调用 Admin Service 的接口所以这个地址错了会出现能登录但发布配置失败的情况。spring.datasource.url jdbc:mysql://127.0.0.1:3306/ApolloPortalDB?characterEncodingutf8serverTimezoneAsia/Shanghai spring.datasource.username root spring.datasource.password your_password apollo.portal.envs dev apollo.portal.meta.servers {dev:http://127.0.0.1:8080}apollo.portal.envs声明了当前环境列表这里只写dev就够单机验证如果你想模拟多环境把dev和pro都写上然后apollo.portal.meta.servers里对应给每个环境配置不同的 Config Service 地址。登录账号要自己往apollo-portal的conf目录下的apollo-env.properties里加或者在数据库里直接插入一条用户记录我一般图省事用后者。默认库里会有一个apollo用户密码存在users表里常见值是$2a$10$7fU7DVN0cJwkQzpB7pIqOuuASzqP8F6pGjVgJYvWQx6jzTZ1aTk6W这种 BCrypt 哈希对应明文密码admin注意这是一版很常见的默认组合部署后第一件事就该改掉。3.3 启动顺序与验证命令三个端口必须各就各位启动顺序我一般固定是 Config Service → Admin Service → Portal。原因不复杂Config Service 内含 EurekaAdmin Service 启动时要向它注册Portal 启动后要拉环境列表和 Admin Service 信息链路是从下往上的。如果顺序反了服务本身不会崩但日志里全是连接超时排查起来费神。启动脚本都在各模块的scripts目录下直接执行./startup.sh脚本内部会调java -jar并把日志写到logs目录。启动后不要急着看界面先用命令确认端口监听状态每个服务启动大约要 10 到 20 秒Eureka 注册可能需要更久。ss -lntp | grep -E 8080|8090|8070三个端口都出现在输出里说明进程起来了。接着验证 Eureka 是否正常工作Config Service 的 Eureka 接口可以直接用 curl 探curl http://127.0.0.1:8080/eureka/apps返回一段 XML里面包含 Admin Service 和 Config Service 的注册信息就说明注册中心正常。此时打开http://127.0.0.1:8070能看到登录页用默认账号登录后就是空的项目列表界面。到这里服务端就绪可以开始接客户端了。4. 客户端接入Spring Boot 项目里配两个键、写一段读取逻辑4.1 引入客户端依赖与版本对齐服务端是 1.4.0客户端依赖版本也要保持一致。在 Spring Boot 项目的pom.xml里加入 Apollo 客户端依赖版本号直接写 1.4.0。很多人在这一步栽过跟头客户端用了新版本或者旧版本连上服务端后出现序列化不兼容或者接口 404。dependency groupIdcom.ctrip.framework.apollo/groupId artifactIdapollo-client/artifactId version1.4.0/version /dependency这个依赖会带入apollo-core和apollo-client-api不需要额外手工添加。如果你的项目里同时有别的配置中心依赖建议先排除掉或者确认接口不冲突Apollo 的Value注解在 Spring Boot 环境里会和原生注解冲突后面会细说。4.2 元数据配置app.id 与 apollo.meta 的作用边界客户端启动时要连到 Config Service 拿配置它需要知道两件事自己是谁、去哪找配置中心。前者是app.id后者是apollo.meta。在application.yml里写app: id: sample-service apollo: meta: http://192.168.1.100:8080 bootstrap: enabled: true eagerLoad: enabled: trueapp.id对应 Portal 里创建项目时填的应用 ID两边必须完全一致大小写和特殊字符都要一字不差。apollo.meta填的是 Config Service 的地址注意不是 Portal 的地址也不是 Admin Service 的。eagerLoad.enabled建议设为true否则配置是异步加载的程序里第一次读取配置时可能拿到null这个坑很隐蔽尤其在 Spring Boot 启动阶段读取配置的场景里。在 1.4.0 这个版本里客户端拿到apollo.meta后会请求它的/eureka/apps接口获取 Config Service 实例列表所以即使apollo.meta配的是内网 IP也要保证客户端机器能访问到那个地址的 8080 端口。4.3 两种读配置姿势注解与程序化获取接入 Apollo 后代码里读配置的方式和原来差不多但有一个关键区别需要注意。直接用Value是最常见的姿势Component public class CacheService { Value(${redis.cache.ttl:300}) private int cacheTtl; public int getCacheTtl() { return cacheTtl; } }逻辑说明Value注解在 Spring 容器启动时注入属性值${redis.cache.ttl:300}的意思是读 Apollo 上redis.cache.ttl这个配置项如果不存在则用默认值 300。Apollo 的动态刷新能力在这里的体现是当你在 Portal 上修改这个配置并发布后Spring 容器里的cacheTtl字段会被自动更新不需要重启服务。参数说明redis.cache.ttl这个 key 必须在 Apollo 配置里存在否则走默认值默认值冒号后面不能留空格。有一点容易翻车——如果你在类里同时用了Value和自定义的 ConfigurationProperties 类读取同一份配置刷新时前者会更新而后者不会因为 Apollo 只对注解字段做注入。程序化获取是更可靠的方式Config config ConfigService.getAppConfig(); Integer ttl config.getIntProperty(redis.cache.ttl, 300);这种方式适合在非 Spring 管理的类里使用或者需要动态获取多个配置项的场景。它每次都会实时取 Apollo 的本地缓存配合监听器可以感知配置变更。两种姿势可以混用但同一份配置别同时用两种方式维护否则调试时不知道哪个值生效。5. Apollo 1.4.0 部署避坑实录五条现象与排查路径5.1 configservice 启动日志一直报 Eureka 连接被拒现象Config Service 进程起来了8080 端口也监听着但日志每隔几秒刷一条Connection refused: connect指向的地址是自己。原因Config Service 内嵌的 Eureka 在启动初期会尝试注册自己而此时注册中心还没完全就绪于是反复重试。另一个常见原因是你把eureka.service.url配置里的 localhost 写成了别的 IP导致自行探测时连到了错误地址。解决如果日志里的地址是 127.0.0.1:8080这属于正常启动过程等 30 秒左右观察日志是否停止报错即可。如果持续报错检查application.properties里eureka.instance.homePageUrl和eureka.service.url是否一致全部改成机器实际内网 IP然后重启。5.2 portal 登录后项目列表一直空白现象登录 Portal 成功但界面上看不到任何项目手动创建项目时下拉框里也没有环境。原因最常见的是 Portal 连接的数据库不对或者apollo.portal.envs和apollo.portal.meta.servers的配置有问题。Portal 启动后要请求 Config Service 获取环境信息拿不到就会显示空白。解决先用 curl 确认 Config Service 的 Eureka 接口能返回服务列表再检查 Portal 的application.properties里apollo.portal.meta.servers的 JSON 格式是否正确。这个配置项是字符串不是 YAML 对象常见错误是漏了外层引号或者写了单引号导致解析失败。修正后重启 Portal。5.3 客户端启动直接报 Apollo config not found现象Spring Boot 项目启动时抛异常提示找不到 Apollo 配置网上搜到的说法是配置地址连不上但地址明明能 ping 通。原因apollo.meta配的是 Portal 地址而不是 Config Service 地址或者app.id在 Portal 里还没创建对应的项目。前者会导致客户端请求到错误的端口后者会让 Config Service 返回App not found。解决先确认 Portal 里已经创建了和app.id同名的项目。然后检查apollo.meta这个地址一定要指向 Config Service 的 8080 端口。如果确认都正确打开客户端的 debug 日志在application.yml加一句logging.level.com.ctrip.framework.apolloDEBUG启动时会打印实际请求的 meta 地址和响应内容问题瞬间定位。5.4 配置改了但不生效本地缓存与监听器两个疑点现象Portal 上修改配置并发布客户端日志看不到拉取动作代码里读取的值还是旧的重启后才生效。原因Apollo 客户端默认有本地缓存它会在启动后台线程定期拉取更新但频率不是秒级的。另外如果代码里用了ApolloConfigChangeListener但监听器内部逻辑有异常刷新会失败而 Spring 的Value注入依赖的是配置变更事件事件被异常中断后不会重放。解决先确认客户端日志里有没有Config changed字样没有就查客户端是否真正连接到了 Config Service可以用curl直接请求配置接口curl http://192.168.1.100:8080/configs/sample-service/default/application能返回 JSON 就说明服务端有配置。有日志但没生效检查监听器方法内部是否抛了异常把监听器逻辑精简为只打日志确认事件流畅通后再加业务逻辑。另外注意Apollo 发布是有版本概念的修改后要点“发布”按钮不是保存就算生效这个操作很多人漏掉。5.5 数据库连接串少了两个参数页面乱码、写入超时现象Portal 页面能打开但配置项里输入中文保存后变问号或者偶发写入超时。原因数据库连接串没有指定characterEncodingMySQL 客户端默认用了latin1做连接字符集同时没指定serverTimezone时在新版 MySQL 驱动下会报时区错误或者使用服务器本地时区导致时间不一致。解决在前面提到的三处数据源连接串中统一加上?characterEncodingutf8serverTimezoneAsia/Shanghai。注意utf8在 MySQL 里是utf8mb3的别名如果你希望完全支持 emoji 字符数据库和连接串都要用utf8mb4连接串参数写成characterEncodingutf8即可因为 JDBC 驱动的utf8对应的是utf8mb4。改完连接串后重启三个服务重新导入一次数据最稳妥。6. 部署验收三步走热更新、灰度回滚、缓存日志观测服务端和客户端都跑通之后不要急着写业务先用三个小实验把 Apollo 的核心能力验证一遍。第一步是热更新验证。在 Portal 里新建一个配置项比如test.refreshtrue在客户端代码里用Value注入它然后修改为false并发布。观察客户端日志正常情况下 2 到 3 秒内会出现Config changed的打印程序无需重启值就变了。这一步过了说明 Spring 集成和事件通知链路是通的。第二步验证灰度发布与回滚。Apollo 的灰度是针对实例 IP 的在 Portal 里把配置发布到灰度环境指定某个客户端实例的 IP然后检查只有那台机器收到了新值其他机器保持旧值。回滚操作在发布历史里找到上一次发布记录点“回滚”即可。这个能力在生产环境非常关键出了问题能在秒级恢复到上一个稳定版本比重启快太多。第三步看本地缓存与日志。找到客户端机器上~/data/{appId}/目录下的缓存文件里面是配置的 JSON 快照确认它和服务端一致。这一步的价值在于验证“客户端在服务端不可达时如何用本地缓存兜底”。你可以把 Config Service 停掉再重启客户端观察它是否能用缓存启动启动后配置是否正确。这个实验建议每个环境都做一遍。我自己的习惯是部署完写一个一页纸的检查单把端口、数据库、Eureka 地址、app.id 四项核对完再收工。这套流程走下来后面接真实业务配置时基本不会再被底层问题绊住。希望帮到你。本文还有配套的精品资源点击获取