# 数据库一键搬家工具

下载地址与文档

下载： https://ext.dcloud.net.cn/plugin?id=6089 (opens new window)
文档： https://vkdoc.fsq.pub/db-migration/ (opens new window)

# 一键搬家的优势

1、官方的web控制台 需要一个一个表导出导入，操作繁琐。而 一键搬家 不需要。
2、直接用 官方的web控制台 导出的 json 文件导入腾讯云，会出现 24 位 id 和外键搜索查不到的 bug。而 一键搬家 自动帮你所有 24 位 id 增加 1 位解决此 bug。
3、不仅支持将 A账号 下的 A1空间 搬家到 A2空间，还支持将 A账号 下的 A1空间 搬家到 B账号 下的 B1空间。
4、支持全端（阿里云、腾讯云、支付宝云）
5、省心、省力、解放双手！

# 一键搬家最重要的优势

如果你用 官方的web控制台 从阿里云空间导出的 json 文件导入腾讯云空间，你会发现根据 _id 搜索时，有可能无法搜索到数据，那是因为腾讯云不支持阿里云生成的 24 位 _id，阿里云生成的 24 位 _id 导入到腾讯云空间后，会造成无法根据 _id 来查询数据，而 一键搬家 可以帮你完美解决这个棘手问题。

# 效果视频

# 名词定义

1、旧空间：就是你需要搬家的空间。
2、新空间：就是你需要把旧空间搬到这的空间。

# 注意事项

1、请确保 旧空间 和 新空间 是可以正常访问的空间。
2、新空间 数据库的数据在导入前 会被全部清空（需要注意空间别选错了，否则后果自负）。
3、旧空间 数据库的数据 不会被清空（也不会被修改）
4、搬家会消耗数据库查询次数、写入次数，以及云函数流量（请确保资源充足）。
6、目前大致耗时 = （你数据量总记录数 / 1000）秒（即每秒搬 1000 条数据）（后面会继续优化这个速度）
7、如有问题，可以加 Q 群：22466457 进行反馈（关于插件问题必定会得到处理）。

# 插件市场地址

点击前往 (opens new window)

# 一键搬家配置

从 1.9.0 起，【一键搬家】项目根目录下的配置分为主配置和扩展配置：

配置文件	用途
`vk.db.config.js`	主配置：旧空间、新空间、每批数据量、文件链接替换规则和需要迁移的表列表
`vk.db.config-ext.js`	扩展配置：并发、重试、日志和数据兼容处理等参数，一般保持默认即可

通常只需修改主配置中的 oldEnv、newEnv 和 db，按需调整 maxPageSize、fileRule；需要调整并发或重试等行为时，再修改扩展配置。

这里的“扩展配置”是对配置文件的拆分，与 dbType: 'ext-db' 表示的“扩展数据库”无关，使用内置数据库时同样会加载扩展配置。云函数目录下的 vk.db.config.js 仍用于配置 actionsecret、runKey 等云函数参数。

# 主配置 vk.db.config.js

主配置通过 import 引入扩展配置，并在配置对象开头使用 ...dbConfigExt 合并，请保留这两处代码。

/**
 * 一键搬家配置
 */
import dbConfigExt from './vk.db.config-ext.js';

export default {
  // 并发、重试、日志等参数统一在扩展配置中维护
  ...dbConfigExt,
  // 旧环境
  oldEnv: {
    cloud: 'uniCloud', // 通用参数 固定为 uniCloud
    platform: 'aliyun', // 通用参数 阿里云：aliyun 腾讯云：tencent 支付宝云：alipay 私有云：dcloud
    dbType: '', // 数据库类型 不填代表内置数据库，ext-db 代表扩展数据库
    spaceId: 'mp-9dd9a70d-0000-6666-a520-105287d47ff4', // 通用参数 从 https://unicloud.dcloud.net.cn/home 获取 对应SpaceId参数
    clientSecret: '阿里云专属参数', // 阿里云专属参数 从 https://unicloud.dcloud.net.cn/home 获取 对应ClientSecret参数
    spaceAppId: '支付宝云专属参数', // 支付宝云专属参数 从 https://unicloud.dcloud.net.cn/home 获取 对应SpaceAppId参数
    accessKey: '支付宝云专属参数', // 支付宝云专属参数 从 https://unicloud.dcloud.net.cn/home 获取 对应AK参数
    secretKey: '支付宝云专属参数', // 支付宝云专属参数 从 https://unicloud.dcloud.net.cn/home 获取 对应SK参数
    actionsecret: '5d44a032652974c3e53644945a95b126', // 通用参数 请求密钥，从 uniCloud/cloudfunctions/vk-db-migration/vk.db.config.js 获取（两者保持一样即可）
    endpoint: '私有云专属参数', // 私有云专属参数 从 https://unicloud.dcloud.net.cn/pages/private-cloud/cluster-list 获取 ApiEndpoint
  },
  // 新环境
  newEnv: {
    cloud: 'uniCloud', // 通用参数 固定为 uniCloud
    platform: 'aliyun', // 通用参数 阿里云：aliyun 腾讯云：tencent 支付宝云：alipay 私有云：dcloud
    dbType: '', // 数据库类型 不填代表内置数据库，ext-db 代表扩展数据库
    spaceId: 'env-00jx6s6j6mnt', // 通用参数 空间id 从 https://unicloud.dcloud.net.cn/home 获取 对应SpaceId参数
    clientSecret: '阿里云专属参数', // 阿里云专属参数 从 https://unicloud.dcloud.net.cn/home 获取 对应ClientSecret参数
    spaceAppId: '支付宝云专属参数', // 支付宝云专属参数 从 https://unicloud.dcloud.net.cn/home 获取 对应SpaceAppId参数
    accessKey: '支付宝云专属参数', // 支付宝云专属参数 从 https://unicloud.dcloud.net.cn/home 获取 对应AK参数
    secretKey: '支付宝云专属参数', // 支付宝云专属参数 从 https://unicloud.dcloud.net.cn/home 获取 对应SK参数
    actionsecret: '5d44a032652974c3e53644945a95b126', // 通用参数 请求密钥，从 uniCloud/cloudfunctions/vk-db-migration/vk.db.config.js 获取（两者保持一样即可）
    endpoint: '私有云专属参数', // 私有云专属参数 从 https://unicloud.dcloud.net.cn/pages/private-cloud/cluster-list 获取 ApiEndpoint
  },
  maxPageSize: 500, // 数据库单次请求获取数量，默认500，如果前端报内存超出大小限制的错误，可以尝试调小此值来解决。如设置为100或50或更小的值，最小为1，最大1000
  // 数据库内存储链接地址域名替换规则
  // 打开 fileRule 内的注释，编写旧域名和新域名，导入后数据库内的文件链接会用新域名代替旧域名
  fileRule: [
    // { "old": "https://test1.xxx.com", "new": "https://test2.xxx.com" }
  ],
  // 数据库集合（表）列表，目前没有接口可以直接获取表列表，故需要在此手动填写数据库中需要搬家的表信息
  // 可以自动根据 database 目录内的文件 生成数据库表名列表 方法：在项目根目录执行 node vk.create-db-config.js 详见文档 https://vkdoc.fsq.pub/db-migration/#如何生成数据库初始化文件
  // prettier-ignore
  "db": [{ name: 'uni-id-users' }, { name: 'uni-id-roles' }, { name: 'uni-id-permissions' }, { name: 'opendb-admin-menus' }, { name: 'opendb-app-list' }],
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

如何获取空间环境参数？

登录unicloud-web 控制台 (opens new window)，在总览页面即可看到对应的参数。

# 扩展配置 vk.db.config-ext.js

以下为扩展配置的默认值，可根据实际需要调整：

export default {
  debug: false, // 浏览器控制台是否打印请求日志，设置为 false 可以提升性能
  countBatchSize: 10, // 获取记录数时每批查询的表数，必须为正整数
  maxConcurrentCountRequests: 5, // 获取记录数时最多同时执行的批次数，必须为正整数；1表示按批串行
  maxConcurrentTables: 5, // 最大同时迁移的表数，必须为正整数；1表示按表串行
  concurrencyImport: false, // 同一张表内是否并发导入数据批次；false保持单表内原始导入顺序，true不保证顺序
  maxConcurrentImports: 5, // 每张表最多同时进行的导入请求数，必须为正整数；仅concurrencyImport为true时生效
  errorReconnectionCount: 10, // 数据库连接失败后的重试次数
  maxImportQueueCount: 10, // 每张表最大等待的导入队列数，最小为1，最大为20；太大会影响前端性能
  maxLogCount: 200, // 页面控制台显示的最大日志数量；太大会影响前端性能
  handleObjectKeyName: true, // 处理阿里云_id格式时，true同时处理字段名和字段值，false只处理字段值
  removeNullValueFieldsForAlipay: true, // 迁移到支付宝云内置数据库时删除null值字段，解决int/long/bool类型字段不能为null的问题
};

1
2
3
4
5
6
7
8
9
10
11
12
13

并发参数如何配合？

获取记录数：countBatchSize 控制每批查询多少张表，maxConcurrentCountRequests 控制同时查询多少批，默认每批 10 张表、最多同时查询 5 批，与迁移并发独立。
多表迁移：maxConcurrentTables 控制同时迁移的表数，默认 5 张表；任意一张表完成或失败收尾后，会继续处理下一张表。
单表导入：concurrencyImport 控制同一张表内的数据批次是否并发导入。默认 false，单表按顺序导入，但仍可同时迁移多张表；设为 true 后，每张表最多同时发起 maxConcurrentImports 个导入请求，无法保证单表内的原始导入顺序。

如果希望逐表、逐批顺序迁移，将 maxConcurrentTables 设为 1，并保持 concurrencyImport: false 即可。

旧版本配置如何调整？

将原主配置中的并发、重试、日志及数据兼容处理参数移到 vk.db.config-ext.js，保留原来需要的参数值，并在主配置中加入上述 import 和 ...dbConfigExt。主配置中写在 ...dbConfigExt 后面的同名参数会覆盖扩展配置，请将这些参数统一在扩展配置中维护，避免修改后未生效。

# 操作步骤

1、打开【一键搬家】项目根目录的主配置 vk.db.config.js，修改 oldEnv、newEnv，按需调整 maxPageSize、fileRule。并发、重试等参数在 vk.db.config-ext.js 中修改，一般保持默认即可；表列表 db 可在第 3 步生成。

2、生成 database 目录下的数据库初始化文件

# 如何生成数据库初始化文件？

在 uniCloud控制台 云数据库菜单下点击 生成初始化数据 选择只导出首条记录，生成不包含 ID（包含也没事）【一键搬家】运行时，会自动清空新空间的数据。

注意：如果生成失败，不要慌，过一会再试

3、把生成并解压的 database 文件全部复制到【一键搬家】项目根目录的 uniCloud/database目录下

注意：如果【一键搬家】项目的 uniCloud/database目录下 有 db_init.json 文件，则需要删除 Ta（这步很重要，因为上面介绍的是使用新的数据库初始化方式的，当然老的 db_init.json 方式目前也还是支持的）

然后在项目根目录执行 node vk.create-db-config.js，生成的表列表会写入主配置 vk.db.config.js 的 db，扩展配置 vk.db.config-ext.js 不会被修改。如果需要按 startId、endId 指定迁移范围，请在生成后补充到 db 中对应的表配置，再次生成会覆盖这些表配置。

4、【一键搬家】项目绑定 旧空间，并上传云函数 vk-db-migration 和 vk-db-migration-ext-db

5、【一键搬家】项目切换到 新空间 ，在 新空间 也上传云函数 vk-db-migration 和 vk-db-migration-ext-db

如何切换空间?

右键 uniCloud 目录，点击关联空间，选择需要切换的空间。

如何切换阿里云、腾讯云、支付宝云空间

右键 uniCloud 目录，点击重命名，腾讯云为: uniCloud-tcb ，阿里云为 uniCloud-aliyun，支付宝云为 uniCloud-alipay，然后再右键 uniCloud 目录，点击关联空间，选择需要切换的空间。

# 特别注意：如果你购买的是普通授权版（非源码授权版），你可能需为两个空间各购买 1 次插件。

6、切换到 新空间 后，在 新空间 初始化你自己数据库（注意：如果初始化报错，不要急，再初始化一次，直到提示成功或提示没有任何表数据要上传时，则代表成功）

7、启动 一键搬家 项目（请使用连接云端云函数）

注意：运行前先确认下，旧空间和新空间没有填错，否则运行时，新空间数据会清空（旧空间数据不会变）

8、启动【一键搬家】项目，访问首页，当看到页面控制台上打印 点击上方【开始一键搬家】按钮可进行一键搬家 时，点击此按钮即可。
9、点击【开始一键搬家】按钮
10、等待全部表完成。连接失败会按扩展配置 vk.db.config-ext.js 中的 errorReconnectionCount 重试，默认 10 次。某张表最终失败不会中止其他表；若有失败，请复制页面生成的重试配置，替换主配置 vk.db.config.js 内的 db，然后刷新页面重新迁移失败表。
11、完成后请将 uniCloud/cloudfunctions/vk-db-migration/vk.db.config.js 和 uniCloud/cloudfunctions/vk-db-migration-ext-db/vk.db.config.js 的 runKey 设置为 false，再分别上传到 旧空间 和 新空间（这步很关键，防止后面误点导致数据被清空，也可以直接去 web 控制台删除云函数 vk-db-migration 和 vk-db-migration-ext-db）
12、完成。

# 常见问题

# 如你已付费购买，缺还提示[vk-database-one-click-migration]：不能在当前云服务空间使用

如果使用数据库搬家项目的时候遇到 data undefined 同时提示 [vk-database-one-click-migration]：不能在当前云服务空间使用 则去项目根目录下的 package.json 文件内查看看是否有名为 sn 的属性，把 Ta 删除后再试试。

# 当需要迁移的数据条数非常多时，且迁移的时候不想停服太长时间时，支持先迁移部分数据（这部分数据需要保证不会再被修改和删除）

只有表存在不会再被修改和删除的数据时才能先迁移这部分数据，迁移的时候旧空间是不需要停服的

假设表 uni-id-log 有 2000 万条数据，其中这 2000 万条数据都不会再被修改和删除（因为这是日志表，不会被修改和删除，只会新增），这些数据的最后一条数据的 _id 是 666c48a1a891ba9fb989fb30（请必须通过 _id 降序排序后拿第一条数据的_id，千万不要去控制台翻最后一页）

拿到目前最后一条 _id 的数据库语句如下，请在云函数中自己执行并获取到 endId

const db = uniCloud.database();
let dbRes = await db.collection('uni-id-log').orderBy('_id', 'desc').limit(1).get();
let endId = dbRes.data[0]._id;
console.log('endId: ', endId);

1
2
3
4

在主配置 vk.db.config.js 的 db 中，为对应的表增加一个参数 endId，配置如下

解释：endId 代表只迁移到这个 _id（包含此 id）后就结束此表

...其他配置

"db": [
  ...其他表
	{ "name": "uni-id-log", "endId": "666c48a1a891ba9fb989fb30" },
]

1
2
3
4
5
6

下次停服全量迁移的时候，再多配置一个参数 startId，并去掉之前的参数 endId，配置如下

...其他配置

"db": [
  ...其他表
	{ "name": "uni-id-log", "startId": "666c48a1a891ba9fb989fb30" },
]

1
2
3
4
5
6

解释：startId 代表迁移时从这个 _id（不包含此 id，即此 id 的下一条记录）开始

# 数据库里的文件 URL 域名如何替换？

修改主配置 vk.db.config.js 中的 fileRule 数组，如下所示

注意：文件本身不会迁移，这里只替换域名，适用于云存储文件已迁移完成只需要改数据库内字段的 URL 值的情况。

"fileRule": [
	{ "old": "https://test1.xxx.com", "new": "https://test2.xxx.com" }
],

1
2
3

# 特别注意

搬家完成后请将 uniCloud/cloudfunctions/vk-db-migration/vk.db.config.js 和 uniCloud/cloudfunctions/vk-db-migration-ext-db/vk.db.config.js 的 runKey 设置为 false，再分别上传到 旧空间 和 新空间（这步很关键，防止后面误点导致数据被清空，也可以直接去 web 控制台删除云函数 vk-db-migration 和 vk-db-migration-ext-db）