注册配置治理 Apollo 数据迁移方案

操作场景
腾讯云微服务引擎的 Apollo 配置中心（以下简称云上 Apollo 实例）即将下线。该任务指导您将云上 Apollo 实例的数据库导出为 SQL 文件，再导入到自建的 Apollo 实例中，完成配置数据的迁移。
维度
说明
Who
使用云上 Apollo 实例的运维或开发人员
What
导出云上实例的 Portal 库与各环境 Config 库，导入并恢复到自建 Apollo 实例
When
云上实例下线前，或需要将配置数据迁出云上环境时
Where
云上操作在 Apollo 控制台 完成；导入操作在自建 Apollo 实例所在服务器完成
Why
保留云上实例中已有的应用、命名空间与配置项，避免重新录入
How
通过控制台新建数据迁出任务获取数据库文件，使用 mysql 客户端导入目标库，并调整环境配置
How much
导出文件的数量 = 1 个 Portal 库 + N 个环境 Config 库（N 为云上实例的环境数）
对系统影响
导出操作为只读操作，不会影响云上 Apollo 实例的正常运行。
导入操作会按 SQL 文件中的 DROP TABLE 语句覆盖目标库中的同名表。若目标库已有业务数据，请先备份。
导入期间请勿向目标库写入数据，避免数据不一致。
前提条件
云上 Apollo 实例的版本与目标自建 Apollo 实例的版本完全一致。版本不一致时，两边的数据库表结构可能不兼容，导入后服务将无法启动。查看云上实例版本的方法请参见 引擎管理。
已准备目标自建 Apollo 实例的数据库，数据库版本为 MySQL 8.0。各环境需要一个独立的库，命名与云上实例保持一致，例如 ApolloPortalDB、ApolloConfigDB_dev2。
已获取目标数据库的内网地址、端口、账号与密码，且执行导入的服务器可以通过内网访问该数据库。
执行导入的服务器已安装 mysql 客户端和 unzip。
已使用与云上实例相同版本的镜像部署目标自建 Apollo 实例，但尚未执行 Apollo 官方的空库初始化脚本。部署方法请参见 Apollo 官方部署文档。
禁止：
目标库中已有数据时，请勿执行 Apollo 官方的初始化脚本。该脚本导入的是官方空库结构，会覆盖或破坏已导入的数据。
操作步骤
迁移流程分为五个阶段，请按顺序执行。
阶段一：导出云数据库文件
1. 登录 Apollo 控制台，进入 Apollo 配置中心的实例列表页面。
2. 在实例列表页面，单击目标实例的实例 ID，进入实例详情页面。
3. 在实例详情页面，选择迁移任务页签，单击新建迁移任务。
4. 在弹出的对话框中，配置以下参数：
参数
说明
迁移类型
选择数据迁出
5. 单击确定。任务创建后需要数分钟完成，请耐心等待。任务执行期间请勿重启或销毁该实例。
说明：
迁移任务支持按环境导出该实例下的全部数据库。若只需迁移部分环境，请在阶段三导入时仅导入对应的库文件。
导入时要求目标数据库名与源数据库名一致。
6. 任务完成后，在迁移任务列表中单击下载，获取全部 SQL 文件，并上传到执行导入的服务器，例如 /data/apollo-migration/sql/。
导出文件与数据库的对应关系如下：
导出文件
对应的库
说明
ApolloPortalDB-<时间戳>.zip
ApolloPortalDB
Portal 控制台数据，包含用户、权限与环境配置
ApolloConfigDB-<环境名>-<时间戳>.zip
ApolloConfigDB_<环境名>
该环境的应用、命名空间与配置项，每个环境一个文件
注意：
导出文件是按表导出的 SQL，文件头包含 Database: 字段，正文中不包含 CREATE DATABASE 和 USE 语句。导入前必须先手动建库，再指定库名执行。
阶段二：准备目标环境
1. 在执行导入的服务器上，创建工作目录并写入目标库连接信息。
mkdir -p /data/apollo-migration/{sql,config}
cat > /data/apollo-migration/config/db.env <<'EOF'
MYSQL_HOST=<目标 MySQL 内网地址>
MYSQL_PORT=3306
MYSQL_USER=<数据库账号>
MYSQL_PASSWORD=<数据库密码>
EOF
chmod 600 /data/apollo-migration/config/db.env
2. 执行以下命令，确认数据库可以连通。返回 8.0.x 表示连通正常。若连接超时，请检查目标数据库的安全组是否已放行本服务器的内网地址。
set -a
source /data/apollo-migration/config/db.env
set +a
mysql -h "$MYSQL_HOST" -P "$MYSQL_PORT" -u "$MYSQL_USER" -p"$MYSQL_PASSWORD" \\
  --protocol=TCP -e "SELECT VERSION();"
警告：
数据库密码只保存在服务器的 config/db.env 中，权限设为 600。请勿将密码写入部署清单或提交到代码仓库。
阶段三：导入数据库文件
1. 执行以下命令，确认每个导出文件对应的库名。请核对输出中的库名与文件名一致，避免导入到错误的库。
cd /data/apollo-migration/sql
for z in *.zip; do
  echo "===== $z ====="
  unzip -p "$z" | awk 'NR<=5 && /Database:/ {print}'
done
2. 执行以下命令，依次建库并导入。请将文件名替换为您实际下载的文件名。每个库导入完成后会输出 imported <库名>。
set -a
source /data/apollo-migration/config/db.env
set +a
﻿
import_dump() {
  local zip="$1"
  local db="$2"
  mysql -h "$MYSQL_HOST" -P "$MYSQL_PORT" -u "$MYSQL_USER" -p"$MYSQL_PASSWORD" \\
    --protocol=TCP -e "CREATE DATABASE IF NOT EXISTS \\`${db}\\` DEFAULT CHARACTER SET utf8mb4;"
  unzip -p "$zip" | mysql -h "$MYSQL_HOST" -P "$MYSQL_PORT" -u "$MYSQL_USER" \\
    -p"$MYSQL_PASSWORD" --protocol=TCP "$db"
  echo "imported $db"
}
﻿
cd /data/apollo-migration/sql
import_dump ApolloConfigDB-dev2.zip ApolloConfigDB_dev2
import_dump ApolloConfigDB-pro.zip  ApolloConfigDB_pro
import_dump ApolloConfigDB-prod.zip ApolloConfigDB_prod
import_dump ApolloPortalDB.zip      ApolloPortalDB
3. 执行以下 SQL，核对导入结果。请核对表数量、各环境的应用数量以及 Portal 用户列表，与云上实例保持一致。
mysql -h "$MYSQL_HOST" -P "$MYSQL_PORT" -u "$MYSQL_USER" -p"$MYSQL_PASSWORD" --protocol=TCP -e "
SELECT table_schema, COUNT(*) AS tables
FROM information_schema.tables
WHERE table_schema LIKE 'Apollo%'
GROUP BY table_schema;
SELECT 'dev2' env, COUNT(*) apps FROM ApolloConfigDB_dev2.App
UNION ALL SELECT 'pro', COUNT(*) FROM ApolloConfigDB_pro.App
UNION ALL SELECT 'prod', COUNT(*) FROM ApolloConfigDB_prod.App;
SELECT Username FROM ApolloPortalDB.Users;
"
阶段四：修改环境配置
云上实例的 Portal 库保存了云上环境的地址，导入后必须改为目标实例的地址，否则 Portal 仍会指向源环境。
1. 执行以下 SQL，修改 Portal 的环境列表与各环境的 Meta 地址。请将 <部署机内网 IP> 与端口替换为目标实例的实际值。
mysql -h "$MYSQL_HOST" -P "$MYSQL_PORT" -u "$MYSQL_USER" -p"$MYSQL_PASSWORD" \\
  --protocol=TCP ApolloPortalDB <<'SQL'
UPDATE ServerConfig
SET Value='dev2,pro,prod', DataChange_LastModifiedBy='migration'
WHERE `Key`='apollo.portal.envs' AND DeletedAt=0;
UPDATE ServerConfig
SET Value='{"dev2":"http://<部署机内网 IP>:18080","pro":"http://<部署机内网 IP>:28080","prod":"http://<部署机内网 IP>:38080"}',
    DataChange_LastModifiedBy='migration'
WHERE `Key`='apollo.portal.meta.servers' AND DeletedAt=0;
SELECT `Key`, Value FROM ServerConfig
WHERE `Key` IN ('apollo.portal.envs','apollo.portal.meta.servers') AND DeletedAt=0;
SQL
2. 确认查询结果已更新。
apollo.portal.envs          dev2,pro,prod
apollo.portal.meta.servers  {"dev2":"http://<部署机内网 IP>:18080","pro":"http://<部署机内网 IP>:28080","prod":"http://<部署机内网 IP>:38080"}
注意：
数据库中的环境列表与 Meta 地址，必须与目标实例 Portal 服务的配置保持一致。更换部署机 IP 或数据库地址时，需要同时修改这两处，否则 Portal 会读取到旧地址。
3. 若目标实例使用 Kubernetes 原生服务发现（Spring profile 包含 kubernetes），各环境 Config 库中的 eureka.service.url 保留原值即可，无需修改。若目标实例使用 Eureka 注册中心，请将该项改为目标 Eureka 的地址。
阶段五：启动并验收
1. 启动目标实例的 Config Service、Admin Service 与 Portal 服务，并确认全部 Pod 处于 Running 状态。
2. 执行以下命令，检查各服务的健康状态。全部返回 200 表示服务正常。若某个地址返回非 200，请检查该服务的数据源地址与数据库密码是否正确。
curl -s -o /dev/null -w "portal      %{http_code}\\n" http://<部署机内网 IP>:8070/health
curl -s -o /dev/null -w "config-dev2 %{http_code}\\n" http://<部署机内网 IP>:18080/health
curl -s -o /dev/null -w "admin-dev2  %{http_code}\\n" http://<部署机内网 IP>:18090/health
curl -s -o /dev/null -w "config-pro  %{http_code}\\n" http://<部署机内网 IP>:28080/health
curl -s -o /dev/null -w "admin-pro   %{http_code}\\n" http://<部署机内网 IP>:28090/health
curl -s -o /dev/null -w "config-prod %{http_code}\\n" http://<部署机内网 IP>:38080/health
curl -s -o /dev/null -w "admin-prod  %{http_code}\\n" http://<部署机内网 IP>:38090/health
3. 在浏览器中打开 http://<部署机内网 IP>:8070，使用云上实例的用户名 apollo 与原有密码登录。
4. 进入 管理员工具 > 系统信息，确认环境列表为目标环境，且各环境的 Meta 地址与阶段四的配置一致。
5. 在业务应用中，将 Apollo Client 的 apollo.meta 指向目标环境对应的 Config Service 地址。配置生效后，应用读取到的配置项应与云上实例中该环境的配置一致。
apollo:
  meta: http://<部署机内网 IP>:18080   # dev2 环境的 Config Service 地址
  bootstrap:
    enabled: true
    namespaces: application
app:
  id: demo-app-001
常见问题
云上实例与目标实例版本不一致会怎样？
版本不一致时，两边的数据库表结构可能不同，导入后服务启动会报错。请先确认版本一致再执行迁移。若版本必须升级，请先完成数据导入，再按官方升级流程升级目标实例。
可以只导出某一个环境的数据吗？
支持。新建迁移任务时选择指定环境的数据库即可。
可以重复导入同一个文件吗？
不建议。导出文件的 SQL 中包含 DROP TABLE 语句，重复导入会覆盖目标库中的同名表。若需要重新导入，请先备份目标库，或改用空库重新导入。
导入时提示 Unknown database 怎么办？
说明目标库尚未创建。导出文件的正文中不包含 CREATE DATABASE 语句，请先按阶段三的命令建库，再执行导入。
Portal 登录后看到的环境仍是源环境，是什么原因？
Portal 的环境列表读取的是 ApolloPortalDB.ServerConfig 中的 apollo.portal.envs。若导入后未执行阶段四的更新，该值仍是云上实例的环境名。请按阶段四修改，并重启 Portal 服务。
客户端连接 prod 环境，却读到了 pro 环境的配置？
Apollo Client 2.0.1 的内置环境只有 PRO，没有单独的 PROD。客户端会将 prod 转换为 PRO，因此只配置 prod.meta 时，实际读取的是 pro 的地址。请在客户端显式设置 apollo.meta 为该环境的 Config Service 地址，不要只依赖环境名。
导出的文件包含敏感信息吗？
导出文件包含配置项内容、Portal 用户与权限信息。数据库账号密码不包含在内。请妥善保管导出文件，迁移完成后及时删除服务器上的临时文件。
相关操作
﻿引擎管理﻿
﻿Apollo 官方部署文档﻿
附录
占位符对照表
使用本文时，请将以下占位符替换为实际值。
占位符
含义
示例
<目标 MySQL 内网地址>
目标数据库的 IP 或域名
21.214.255.6
<数据库账号>、<数据库密码>
目标数据库的账号与密码
root
<部署机内网 IP>
自建 Apollo 实例所在服务器的内网 IP
21.91.127.230
<环境名>
云上实例中的环境名称
dev2、pro、prod
<时间戳>
导出任务生成文件的时间标识
2026-09-30_18-08-00
默认端口说明
服务
默认端口
Portal
8070
Config Service（dev2 / pro / prod）
18080 / 28080 / 38080
Admin Service（dev2 / pro / prod）
18090 / 28090 / 38090
若您自定义了端口，请按实际端口替换文中的端口值。
操作实例
本文以 Apollo 2.0.1 为例。Apollo 迁移示例﻿

维度	说明
Who	使用云上 Apollo 实例的运维或开发人员
What	导出云上实例的 Portal 库与各环境 Config 库，导入并恢复到自建 Apollo 实例
When	云上实例下线前，或需要将配置数据迁出云上环境时
Where	云上操作在 Apollo 控制台完成；导入操作在自建 Apollo 实例所在服务器完成
Why	保留云上实例中已有的应用、命名空间与配置项，避免重新录入
How	通过控制台新建数据迁出任务获取数据库文件，使用 mysql 客户端导入目标库，并调整环境配置
How much	导出文件的数量 = 1 个 Portal 库 + N 个环境 Config 库（N 为云上实例的环境数）

导出文件	对应的库	说明
ApolloPortalDB-<时间戳>.zip	ApolloPortalDB	Portal 控制台数据，包含用户、权限与环境配置
ApolloConfigDB-<环境名>-<时间戳>.zip	ApolloConfigDB_<环境名>	该环境的应用、命名空间与配置项，每个环境一个文件

占位符	含义	示例
<目标 MySQL 内网地址>	目标数据库的 IP 或域名	21.214.255.6
<数据库账号>、<数据库密码>	目标数据库的账号与密码	root
<部署机内网 IP>	自建 Apollo 实例所在服务器的内网 IP	21.91.127.230
<环境名>	云上实例中的环境名称	dev2、pro、prod
<时间戳>	导出任务生成文件的时间标识	2026-09-30_18-08-00

服务	默认端口
Portal	8070
Config Service（dev2 / pro / prod）	18080 / 28080 / 38080
Admin Service（dev2 / pro / prod）	18090 / 28090 / 38090

Apollo 数据迁移方案

本页目录：

操作场景

对系统影响

前提条件

操作步骤

阶段一：导出云数据库文件

阶段二：准备目标环境

阶段三：导入数据库文件

阶段四：修改环境配置

阶段五：启动并验收

常见问题

云上实例与目标实例版本不一致会怎样？

可以只导出某一个环境的数据吗？

可以重复导入同一个文件吗？

导入时提示 Unknown database 怎么办？

Portal 登录后看到的环境仍是源环境，是什么原因？

客户端连接 prod 环境，却读到了 pro 环境的配置？

导出的文件包含敏感信息吗？

相关操作

附录

占位符对照表

默认端口说明

操作实例