Default new installs to database discovery (#5580)

* feat: default new installs to database discovery

* docs: update changelog for database discovery default

* docs: emphasize discovery default change in changelog

Author: nobodyiam

CHANGES.md

@@ -6,6 +6,7 @@ Apollo 3.0.0
 
 ------------------
 * [Fix: include super admin in hasAnyPermission semantics](https://github.com/apolloconfig/apollo/pull/5568)
+* [Change: official Config/Admin packages now default to database discovery; upgraded Eureka deployments should explicitly keep the `github` profile to preserve legacy behavior](https://github.com/apolloconfig/apollo/pull/5580)
 
 ------------------
 All issues and pull requests are [here](https://github.com/apolloconfig/apollo/milestone/18?closed=1)

apollo-adminservice/src/main/docker/Dockerfile

@@ -17,6 +17,7 @@
 # 1. ./scripts/build.sh
 # 2. Build with: mvn docker:build -pl apollo-adminservice
 # 3. Run with: docker run -p 8090:8090 -e SPRING_DATASOURCE_URL="jdbc:mysql://fill-in-the-correct-server:3306/ApolloConfigDB?characterEncoding=utf8" -e SPRING_DATASOURCE_USERNAME=FillInCorrectUser -e SPRING_DATASOURCE_PASSWORD=FillInCorrectPassword -d -v /tmp/logs:/opt/logs --name apollo-adminservice apolloconfig/apollo-adminservice
+#    Add -e SPRING_PROFILES_ACTIVE=github if you need legacy Eureka behavior after upgrading.
 
 FROM alpine:3.15.5
 

apollo-adminservice/src/main/resources/application.properties

@@ -14,7 +14,9 @@
 # limitations under the License.
 #
 
-# You may uncomment the following config to activate different spring profiles
+# Official build packages enable github,database-discovery by default.
+# You may uncomment the following config to override the default discovery profile.
+#spring.profiles.active=github
 #spring.profiles.active=github,consul-discovery
 #spring.profiles.active=github,zookeeper-discovery
 #spring.profiles.active=github,custom-defined-discovery

apollo-configservice/src/main/docker/Dockerfile

@@ -17,6 +17,7 @@
 # 1. ./scripts/build.sh
 # 2. Build with: mvn docker:build -pl apollo-configservice
 # 3. Run with: docker run -p 8080:8080 -e SPRING_DATASOURCE_URL="jdbc:mysql://fill-in-the-correct-server:3306/ApolloConfigDB?characterEncoding=utf8" -e SPRING_DATASOURCE_USERNAME=FillInCorrectUser -e SPRING_DATASOURCE_PASSWORD=FillInCorrectPassword -d -v /tmp/logs:/opt/logs --name apollo-configservice apolloconfig/apollo-configservice
+#    Add -e SPRING_PROFILES_ACTIVE=github if you need legacy Eureka behavior after upgrading.
 
 FROM alpine:3.15.5
 

apollo-configservice/src/main/resources/application.properties

@@ -14,11 +14,13 @@
 # limitations under the License.
 #
 
-# You may uncomment the following config to activate different spring profiles
+# Official build packages enable github,database-discovery by default.
+# You may uncomment the following config to override the default discovery profile.
+#spring.profiles.active=github
 #spring.profiles.active=github,consul-discovery
 #spring.profiles.active=github,zookeeper-discovery
 #spring.profiles.active=github,custom-defined-discovery
 #spring.profiles.active=github,database-discovery
 
 # You may change the following config to activate different database profiles like h2/postgres
-spring.profiles.group.github = mysql
+spring.profiles.group.github = mysql

docs/en/deployment/distributed-deployment-guide.md

@@ -477,6 +477,8 @@ This script will package apollo-configservice, apollo-adminservice, apollo-porta
 
 > Note: Since ApolloConfigDB is deployed in each environment, you need to use different packages for config-service and admin-service for different environments with different database connection information, and only one package for portal
 
+> Note: When built with the official `build.sh/build.bat` script, `apollo-configservice` and `apollo-adminservice` default to `github,database-discovery`, while `apollo-portal` defaults to `github,auth`. If you are rebuilding source for an existing Eureka deployment and want to keep the old behavior, change the corresponding Maven command back to `-Dapollo_profile=github`. For already unpacked installation packages or running containers, explicitly set `SPRING_PROFILES_ACTIVE=github`, or configure `spring.profiles.active=github` in `config/application.properties`.
+
 ##### 2.2.1.2.4 Get the apollo-config-service installation package
 
 Located in the `apollo-configservice/target/` directory `apollo-configservice-x.x.x-github.zip`
@@ -495,6 +497,8 @@ Note that since ApolloConfigDB is deployed in each environment, the admin-servic
 
 ### 2.2.2 Deploy Apollo server
 
+> Note: Installation packages for `apollo-configservice` and `apollo-adminservice` generated from the official release packages, Docker images, or `build.sh/build.bat` now enable `database-discovery` by default. If you want an upgraded legacy Eureka deployment to keep the old behavior, explicitly set `SPRING_PROFILES_ACTIVE=github` at runtime, or configure `spring.profiles.active=github` in the unpacked `config/application.properties`.
+
 #### 2.2.2.1 Deploy apollo-configservice
 
 Upload the `apollo-configservice-x.x.x-github.zip` of the corresponding environment to the server, decompress it and execute scripts/startup.sh. To stop the service, execute scripts/shutdown.sh.
@@ -509,9 +513,9 @@ export JAVA_OPTS="-server -Xms6144m -Xmx6144m -Xss256k -XX:MetaspaceSize=128m -X
 
 > Note 2: To adjust the log output path of the service, you can modify `LOG_DIR` in scripts/startup.sh and apollo-configservice.conf.
 
-> Note 3: To adjust the listening port of the service, you can modify the `SERVER_PORT` in scripts/startup.sh. In addition, apollo-configservice also assumes the responsibility of meta server. If you want to modify the port, pay attention to the `eureka.service.url` configuration item in the ApolloConfigDB.ServerConfig table and the meta server information used in apollo-portal and apollo-client. For details, see: [2.2.1.1.2.4 Configuring the meta service information of apollo-portal](en/deployment/distributed-deployment-guide?id=_221124-configuring-apollo-portal39s-meta-service-information) and [1.2.2 Apollo Meta Server](en/client/java-sdk-user-guide?id=_122-apollo-meta-server).
+> Note 3: To adjust the listening port of the service, you can modify the `SERVER_PORT` in scripts/startup.sh. In addition, apollo-configservice also assumes the responsibility of meta server. If you want to modify the port, update the meta server information used by apollo-portal and apollo-client as well. For details, see [2.2.1.1.2.4 Configuring the meta service information of apollo-portal](en/deployment/distributed-deployment-guide?id=_221124-configuring-apollo-portal39s-meta-service-information) and [1.2.2 Apollo Meta Server](en/client/java-sdk-user-guide?id=_122-apollo-meta-server). If you still use the built-in Eureka, you also need to update the `eureka.service.url` configuration item in the ApolloConfigDB.ServerConfig table.
 
-> Note 4: If the eureka.service.url of ApolloConfigDB.ServerConfig is only configured with the currently starting machine, the eureka registration failure information will be output in the log during the process of starting apollo-configservice, such as `com.sun.jersey .api.client.ClientHandlerException: java.net.ConnectException: Connection refused`. It should be noted that this is the expected situation, because apollo-configservice needs to register the service with the Meta Server (itself), but because it has not yet woken up during the startup process, it will report this error. The retry action will be performed later, so the registration will be normal after the service is up.
+> Note 4: This note only applies when you keep using the built-in Eureka. If the `eureka.service.url` of ApolloConfigDB.ServerConfig is configured with only the machine that is currently starting, apollo-configservice may log Eureka registration failures such as `com.sun.jersey.api.client.ClientHandlerException: java.net.ConnectException: Connection refused` during startup. This is expected because apollo-configservice needs to register itself to the Meta Server while it is still starting. It will retry automatically and register successfully after the service is fully up.
 
 > Note 5: Starting from version 2.5.0, apollo-configservice supports graceful shutdown. When the service receives a stop signal, it will wait for in-flight requests to complete before shutting down, with a default timeout of 10 seconds. This feature is enabled via Spring Boot's `server.shutdown=graceful` and `spring.lifecycle.timeout-per-shutdown-phase=${GRACEFUL_SHUTDOWN_TIMEOUT:10s}` configuration. To adjust the timeout, you can set the `GRACEFUL_SHUTDOWN_TIMEOUT` environment variable (e.g., `30s`, `60s`, `2m`) or modify the settings in application.yml. In Kubernetes environments, ensure the Pod's `terminationGracePeriodSeconds` is greater than the configured timeout (recommend at least 10 seconds more).
 
@@ -739,32 +743,27 @@ apollo.config-service.url=http://apollo-config-service
 apollo.admin-service.url=http://apollo-admin-service
 ```
 
-#### 2.2.3.5 database-discovery
+#### 2.2.3.5 database-discovery (default for 3.0.0+)
 
-> For version 2.1.0 and above
+> Supported since 2.1.0, enabled by default since 3.0.0
 
 Enable database-discovery to replace built-in eureka
 
 Apollo supports the use of internal database table as registry, without relying on third-party registry.
 
-1. Modify `config/application.properties` after decompression of `apollo-configservice-x.x.x-github.zip` and `apollo-adminservice-x.x.x-github.zip`, uncomment
-    ```properties
-    #spring.profiles.active=github,database-discovery
-    ```
+1. `apollo-configservice` and `apollo-adminservice` packages built from the official release packages, Docker images, or `build.sh/build.bat` already enable `database-discovery` by default, so no extra change is required.
 
-    to
+2. If you are upgrading an existing Eureka deployment and want to keep the old behavior, choose the rollback method based on how you deploy:
+   - Unpacked installation packages or containers at runtime: set `SPRING_PROFILES_ACTIVE=github`, or configure `spring.profiles.active=github` in `config/application.properties`
+   - Source rebuilds: change the build command from `-Dapollo_profile=github,database-discovery` back to `-Dapollo_profile=github`
 
-    ```properties
-    spring.profiles.active=github,database-discovery
-    ```
-
-2. (optional) In multi-cluster deployments, if you want apollo client only read Config Service in the same cluster,
+3. (optional) In multi-cluster deployments, if you want apollo client only read Config Service in the same cluster,
 you can add a property in `config/application-github.properties` of the Config Service and Admin Service installation package
 ```properties
 apollo.service.registry.cluster=same name with apollo Cluster
 ```
 
-2. (optional) If you want to customize Config Service and Admin Service's uri for Client, 
+4. (optional) If you want to customize Config Service and Admin Service's uri for Client, 
    for example when deploying on the intranet, 
    if you don't want to expose the intranet ip, 
    you can add a property in `config/application-github.properties` of the Config Service and Admin Service installation package
@@ -778,6 +777,8 @@ apollo.service.registry.cluster=same name with apollo Cluster
 
 Apollo version 1.7.0 starts uploading Docker images to [Docker Hub](https://hub.docker.com/u/apolloconfig) by default, which can be obtained by following these steps
 
+> Note: Official `apollo-configservice` and `apollo-adminservice` images enable `database-discovery` by default, so you do not need to add an extra profile. If you want an upgraded legacy Eureka deployment to keep the old behavior, add `-e SPRING_PROFILES_ACTIVE=github` when starting the container.
+
 #### 2.3.1.1 Apollo Config Service
 
 ##### 2.3.1.1.1 Get the image
@@ -1678,5 +1679,3 @@ Default is false. Assess total configuration size and adjust Config Service memo
 > Ensure that the `app.id`、`apollo.cluster` of the configuration in the application is in the correct case when caching is enabled, otherwise it will not fetch the correct configuration, You can also refer to the `config-service.cache.key.ignore-case` configuration for compatibility processing.
 
 > `config-service.incremental.change.enabled` configuration adjustment requires a restart of the config service to take effect
-
-

docs/zh/deployment/distributed-deployment-guide.md

@@ -461,6 +461,8 @@ META_SERVERS_OPTS="-Ddev_meta=$dev_meta -Dfat_meta=$fat_meta -Duat_meta=$uat_met
 
 > 注：由于ApolloConfigDB在每个环境都有部署，所以对不同环境的config-service和admin-service需要使用不同的数据库连接信息打不同的包，portal只需要打一次包即可
 
+> 注：通过官方`build.sh/build.bat`脚本构建时，`apollo-configservice`和`apollo-adminservice`默认会使用`github,database-discovery`，`apollo-portal`默认使用`github,auth`。如果是已有的Eureka部署升级后仍希望保持原行为，源码重新打包时可将对应的Maven命令改回`-Dapollo_profile=github`；对于已经解压的安装包或运行中的容器，可显式设置`SPRING_PROFILES_ACTIVE=github`，或在`config/application.properties`中配置`spring.profiles.active=github`。
+
 ##### 2.2.1.2.4 获取apollo-configservice安装包
 
 位于`apollo-configservice/target/`目录下的`apollo-configservice-x.x.x-github.zip`
@@ -479,6 +481,8 @@ META_SERVERS_OPTS="-Ddev_meta=$dev_meta -Dfat_meta=$fat_meta -Duat_meta=$uat_met
 
 ### 2.2.2 部署Apollo服务端
 
+> 注：通过官方release包、Docker镜像或`build.sh/build.bat`新生成的`apollo-configservice`和`apollo-adminservice`安装包默认启用`database-discovery`。如果现有Eureka部署升级后仍需保持原行为，请在运行时显式设置`SPRING_PROFILES_ACTIVE=github`，或在解压目录的`config/application.properties`中配置`spring.profiles.active=github`。
+
 #### 2.2.2.1 部署apollo-configservice
 将对应环境的`apollo-configservice-x.x.x-github.zip`上传到服务器上，解压后执行scripts/startup.sh即可。如需停止服务，执行scripts/shutdown.sh.
 
@@ -491,9 +495,9 @@ export JAVA_OPTS="-server -Xms6144m -Xmx6144m -Xss256k -XX:MetaspaceSize=128m -X
 
 > 注2：如要调整服务的日志输出路径，可以修改scripts/startup.sh和apollo-configservice.conf中的`LOG_DIR`。
 
-> 注3：如要调整服务的监听端口，可以修改scripts/startup.sh中的`SERVER_PORT`。另外apollo-configservice同时承担meta server职责，如果要修改端口，注意要同时ApolloConfigDB.ServerConfig表中的`eureka.service.url`配置项以及apollo-portal和apollo-client中的使用到的meta server信息，详见：[2.2.1.1.2.4 配置apollo-portal的meta service信息](#_221124-配置apollo-portal的meta-service信息)和[1.2.2 Apollo Meta Server](zh/client/java-sdk-user-guide#_122-apollo-meta-server)。
+> 注3：如要调整服务的监听端口，可以修改scripts/startup.sh中的`SERVER_PORT`。另外apollo-configservice同时承担meta server职责，如果要修改端口，需要同步更新apollo-portal和apollo-client中的meta server信息，详见：[2.2.1.1.2.4 配置apollo-portal的meta service信息](#_221124-配置apollo-portal的meta-service信息)和[1.2.2 Apollo Meta Server](zh/client/java-sdk-user-guide#_122-apollo-meta-server)。如果当前仍使用内置Eureka，还需要同时更新ApolloConfigDB.ServerConfig表中的`eureka.service.url`配置项。
 
-> 注4：如果ApolloConfigDB.ServerConfig的eureka.service.url只配了当前正在启动的机器的话，在启动apollo-configservice的过程中会在日志中输出eureka注册失败的信息，如`com.sun.jersey.api.client.ClientHandlerException: java.net.ConnectException: Connection refused`。需要注意的是，这个是预期的情况，因为apollo-configservice需要向Meta Server（它自己）注册服务，但是因为在启动过程中，自己还没起来，所以会报这个错。后面会进行重试的动作，所以等自己服务起来后就会注册正常了。
+> 注4：仅当继续使用内置Eureka时，如果ApolloConfigDB.ServerConfig的`eureka.service.url`只配了当前正在启动的机器，那么在启动apollo-configservice的过程中会在日志中输出eureka注册失败的信息，如`com.sun.jersey.api.client.ClientHandlerException: java.net.ConnectException: Connection refused`。这是预期现象，因为apollo-configservice需要向Meta Server（它自己）注册服务，但在启动过程中自己还没有完全起来。后续会自动重试，等服务启动完成后注册就会正常。
 
 > 注5：apollo-configservice从2.5.0版本开始支持优雅下线功能。当服务收到停止信号时，会等待正在处理的请求完成后再关闭，默认等待时间为10秒。此功能通过Spring Boot的`server.shutdown=graceful`和`spring.lifecycle.timeout-per-shutdown-phase=${GRACEFUL_SHUTDOWN_TIMEOUT:10s}`配置启用。如需调整超时时间，可以通过环境变量`GRACEFUL_SHUTDOWN_TIMEOUT`设置（如`30s`、`60s`、`2m`等），或直接修改application.yml中的配置。在Kubernetes环境中，请确保Pod的`terminationGracePeriodSeconds`大于配置的超时时间（建议至少多10秒）。
 
@@ -697,33 +701,28 @@ apollo.admin-service.url=http://apollo-admin-service
 ```
 
 
-#### 2.2.3.5 database-discovery
+#### 2.2.3.5 database-discovery（3.0.0及以上版本默认）
 
-> 仅支持 2.1.0 及以上版本
+> 2.1.0 起支持，3.0.0 起默认启用
 
 启用database-discovery替换内置eureka
 
 Apollo支持使用内部的数据库表作为注册中心，不依赖第三方的注册中心
 
-1. 修改`apollo-configservice-x.x.x-github.zip`和`apollo-adminservice-x.x.x-github.zip`解压后的`config/application.properties`，取消注释，把
-    ```properties
-    #spring.profiles.active=github,database-discovery
-    ```
-
-    变成
+1. 通过官方release包、Docker镜像或`build.sh/build.bat`构建得到的`apollo-configservice`和`apollo-adminservice`安装包默认已经启用`database-discovery`，无需额外修改。
 
-    ```properties
-    spring.profiles.active=github,database-discovery
-    ```
+2. 如果你是已有Eureka部署升级到新版本后仍希望保持原行为，可以按部署方式显式回退到Eureka：
+   - 已解压安装包或容器运行时：设置`SPRING_PROFILES_ACTIVE=github`，或者在解压目录的`config/application.properties`中配置`spring.profiles.active=github`
+   - 源码重新打包：将构建命令中的`-Dapollo_profile=github,database-discovery`改回`-Dapollo_profile=github`
 
-2. （可选）在多机房部署时，
+3. （可选）在多机房部署时，
    如果你需要apollo客户端只读取同机房内的Config Service，
    你可以在Config Service和Admin Service安装包中`config/application-github.properties`新增一条配置
     ```properties
     apollo.service.registry.cluster=与apollo的Cluster同名
     ```
 
-3. （可选）如果你希望自定义Config Service和Admin Service给Client使用的uri，
+4. （可选）如果你希望自定义Config Service和Admin Service给Client使用的uri，
     例如在内网部署时，
     如果不希望暴露内网ip，
     你可以在Config Service和Admin Service安装包中`config/application-github.properties`新增一条配置
@@ -735,6 +734,8 @@ Apollo支持使用内部的数据库表作为注册中心，不依赖第三方
 ### 2.3.1 1.7.0及以上版本
 Apollo 1.7.0版本开始会默认上传Docker镜像到[Docker Hub](https://hub.docker.com/u/apolloconfig)，可以按照如下步骤获取
 
+> 注：官方`apollo-configservice`和`apollo-adminservice`镜像默认启用`database-discovery`，无需额外指定profile。如果已有Eureka部署升级后仍需保持原行为，可以在运行容器时额外添加`-e SPRING_PROFILES_ACTIVE=github`。
+
 #### 2.3.1.1 Apollo Config Service
 
 ##### 2.3.1.1.1 获取镜像
@@ -1618,4 +1619,4 @@ json
 > 开启缓存后必须确保应用中配置的`app.id`、`apollo.cluster`
 > 大小写正确，否则将获取不到正确的配置，另可参考`config-service.cache.key.ignore-case`配置做兼容处理。
 
-> `config-service.incremental.change.enabled` 配置调整必须重启 config service 才能生效
+> `config-service.incremental.change.enabled` 配置调整必须重启 config service 才能生效