# uniCloud 阿里云服务空间一键迁移使用说明

背景说明

为了方便开发者将业务从阿里云服务空间迁移到其他云,我们提供了一键迁移的功能,开发者可在uniCloud web 控制台操作迁移。

# 一、功能说明

开发者可以按业务模块迁移阿里云服务空间中的资源:

模块 可迁移内容
云数据库 选择备份中的数据表、数据和索引,可迁移到目标空间的内置数据库或扩展数据库
云存储 云存储中的文件及目录结构,可迁移到目标空间的内置云存储或扩展存储
前端网页托管 前端网页托管中的文件及目录结构,可迁移到目标空间的内置前端网页托管或扩展存储
云函数&公共模块 云函数、公共模块、schema、环境变量、定时任务配置及相关插件授权等

由于数据库schema的场景应用在云函数中,所以会跟随函数进行迁移,另外以下资源会在“云函数&公共模块”任务中按条件一并处理:

  • 如有开通扩展存储,绑定关系支持转移至目标空间;
  • 如有开通Redis,绑定关系支持转移至目标空间(仅支付宝云);
  • 一键登录、短信、uni-push等业务服务空间白名单。

每个业务模块需要分别配置和提交迁移。这样做虽然多了几次确认,但好处是每个模块都有自己的进度和日志,某个业务模块失败时也不会拖着其他业务模块一起重来。

推荐按照云数据库、云存储、前端网页托管、云函数和公共模块的业务顺序进行迁移。先迁移被云函数依赖的数据和文件,最后迁移云函数、定时任务及关联资源。

四个业务模块仍然相互独立,可以根据实际业务自由切换和提交。

同时一键迁移还提供“停服维护”功能,用于在最终迁移和业务切换期间拦截源阿里云空间的云函数及云对象请求。

注意:

  • 一键迁移不是实时同步数据到目标空间。迁移任务创建后,阿里云服务空间里新产生的数据或文件不一定会进入这次任务。仍在持续写入的业务,最好安排维护窗口。
  • 一键迁移实现的是阿里云服务空间数据迁移,仅做数据迁移,不会变动阿里云服务空间数据,不会转移阿里云服务空间套餐的剩余有效期;不会影响已发布的App、Web 或小程序等客户端,客户端的更新需开发者使用目标空间进行发版。
  • 由于牵涉资源众多,目标空间仅支持当前账号下的服务空间,不支持协作空间。

# 二、绑定目标空间

先在当前账号下创建一个支付宝云或腾讯云服务空间,正式开始前,建议做如下检查:

  1. 确认目标服务空间数据库、云存储和前端网页托管有足够容量能覆盖阿里云服务空间已有用量。
  2. 确认目标数据库中没有与待迁移数据冲突的同名数据表和数据。
  3. 对持续写入数据库或云存储的业务安排维护窗口,避免迁移期间继续写入造成数据不一致。

# 2.1 进入一键迁移页面

一键迁移入口在阿里云服务空间中:

  1. 登录 uniCloud web 控制台
  2. 选择到需要迁移的阿里云服务空间
  3. 在左侧管理菜单中点击“一键迁移”

# 2.2 选择并绑定目标空间

首次迁移前,要先为当前阿里云空间绑定一个目标服务空间。

  1. 在目标空间列表中选择当前账号创建的支付宝云或腾讯云服务空间
  2. 核对目标空间名称、空间 ID 和云厂商。
  3. 点击“确认绑定”。
  4. 在确认窗口中再次核对目标空间后完成绑定。

未提交迁移任务前,仍可切换绑定空间,在目标空间中选择其他服务空间后,点击“切换绑定空间”来换绑

首次成功提交迁移任务后绑定已锁定,不再支持更换目标空间,如需调整请前往阿里云服务空间迁移指南uni-im群中联系管理员申请。

注意:

  • 目标空间只能绑定当前账号创建的服务空间,不能绑定协作服务空间。
  • 绑定后且未提交任何迁移任务前,目标服务空间仍可更换,首次成功提交迁移任务后,目标服务空间将永久锁定。
  • 特殊情况下需要更换目标空间时,请在一键迁移uni-im群中联系管理员申请。

# 三、迁移任务的通用操作

迁移任务提交后会在云端自动执行,离开页面或关闭浏览器不会中断。再次进入页面后,可以继续查看最新进度和日志。每个业务模块都会保留最近一次迁移任务的日志。

# 3.1 任务状态

迁移任务可能处于以下状态:

状态 说明
等待执行 任务已提交,正在等待云端执行
执行中 正在迁移资源
已成功 任务已经执行完成,接下来需要验证目标空间
已失败 部分或全部资源迁移失败,可以从失败项和日志开始排查
已取消 主动取消了任务,已经写入目标空间的内容不会回滚

# 3.2 任务信息

每个迁移任务都有唯一的任务ID。任务执行过程中会记录详细的日志及任务进度,以便更好的了解任务执行到哪一步。

如果迁移过程出现失败,您也可以从日志中看到具体错误信息。

# 3.3 取消迁移

执行中的任务可以取消,但“取消”不等于“撤销”。它只会停止后续处理,已经写入目标空间的资源会保留。

所以,任务取消后如果准备重新迁移,建议先将目标服务空间已迁移资源删除。

# 3.4 重新迁移和重试

当前不支持迁移任务失败或取消后从中断位置继续。点击“重新迁移”只会恢复上一次任务的主要配置,重新提交后会创建新任务,并从头执行当前业务模块的迁移。

对于部分特定失败,页面可能提供“重试失败定时任务”“重试失败文件”或“重新打包”等局部处理入口,这些操作只处理对应失败项。

  • 重新迁移:恢复上一次任务的主要配置,确认或调整后再创建新任务,并从头执行当前业务模块的迁移。
  • 重试失败定时任务:只重试未成功同步的定时任务配置,不重新迁移云函数代码。
  • 重试失败文件:只处理云存储或前端网页托管中失败的文件,不重复迁移已成功文件。
  • 重新打包:只重建并上传未成功的迁移文件压缩分卷,不重新迁移文件。

# 四、迁移云数据库

阿里云会在凌晨备份前一天的数据,由于整体量级较大,有的空间在阿里云测备份执行较早,备份完成的时间也会早一些,一般会在凌晨5~7点完成。

迁移任务迁移的是阿里云空间已有备份里的数据,数据备份日当天发生的新增和修改不会迁移,所以应当安排好停服维护的逻辑和时间。

# 4.1 选择目标数据库

在“云数据库”页签中选择以下一种目标:

  • 目标空间内置数据库:迁移到目标服务空间自带的云数据库;
  • 扩展数据库:迁移到已经授权给目标空间的扩展数据库。

如果选择扩展数据库,还需选择对应的数据库名称。如果扩展数据库列表为空,通常是目标空间还没有获得扩展数据库授权,可以参考授权绑定空间先完成授权后再回来继续操作。

# 4.2 选择备份和数据表

  1. 选择“备份时间”。页面默认选中最新可用备份。
  2. 等待系统读取该备份包含的数据表。
  3. 勾选需要迁移的数据表,或使用“全选”。
  4. 确认目标数据库不存在会发生冲突的同名数据表和数据。

切换备份时间后,页面会重新读取该备份包含数据表。

# 4.3 设置过滤规则(可选)

如果数据里保存了阿里云服务空间的资源链接,可以使用过滤规则顺手替换,最多可设置五组。

例如,数据库中保存了阿里云云存储文件的完整 URL,可以将阿里云云存储域名替换为目标空间的新域名。

过滤规则只处理数据内容里的字符串,不会重命名数据表或字段。这里的替换会真正写入目标数据库,提交前务仔细必核,该操作会增加一定迁移时长。

# 4.4 提交任务

  1. 确认目标数据库、备份时间、数据表和过滤规则
  2. 点击“开始迁移”
  3. 页面会二次弹窗确认已选设置
  4. 点击“确认开始迁移”后真正开始执行迁移

# 4.5 数据库迁移注意事项

  • 阿里云会在每天的凌晨3点开始执行备份,备份完成时间一般在4~8点,备份包含的数据截止时间为当日凌晨执行备份时的数据快照。
  • 建议迁移当天凌晨3点前先停止业务写入,备份完成后再选择最新备份进行迁移。
  • 目标数据库已有相同数据时可能导致主键或索引冲突。
  • 取消或失败不会删除已经导入的内容。

# 五、迁移内置云存储

注意

如果内置云存储容量较大且文件数量较多(如容量10GB以上且小文件居多),该迁移工具会非常耗时,建议通过扩展存储回源的方式将内置云存储迁移至扩展存储,费用相较内置存储也会降低,点击查看文档 并参考其中的“方案二”。

内置云存储支持迁移至目标服务空间内置云存储或扩展存储,文件会按原目录结构上传到目标位置。

# 5.1 选择迁移目标

在“云存储”页签中选择:

  • 内置云存储:迁移到目标空间自带的云存储;
  • 扩展存储:迁移到目标空间已经开通的扩展存储。

只有目标空间存在可用扩展存储时,才能选择“扩展存储”。

# 5.2 是否开启打包上传

开启“打包上传”后,系统会在迁移文件的同时生成 ZIP 分卷:

  • 每个分卷约 900 MB;
  • 文件名为 unicloud-aliyun-migration-*.zip;
  • 分卷保存在目标空间的目标位置根目录;
  • 分卷会额外占用目标空间容量;
  • 开启打包会延长任务执行时间。

打包不是迁移文件的必要条件。只有确实需要在迁移后下载一份归档时再开启,否则保持关闭可以节省时间和目标空间容量。

# 5.3 提交任务

  1. 选择迁移目标。
  2. 根据需要设置“打包上传”。
  3. 点击“开始迁移”。
  4. 页面会二次弹窗确认已选设置。
  5. 点击“确认开始迁移”。

# 5.4 云存储迁移注意事项

  • 目标位置存在同名文件时会直接覆盖,不比对、不跳过,也不会自动回滚。
  • 防盗链、文件权限等配置不会迁移,需要在目标空间重新设置。
  • 迁移到内置云存储前,请确认目标服务空间套餐容量是否足够。
  • 迁移到扩展存储时,文件写入目标空间当前绑定的扩展存储,不会同时写入内置云存储。
  • 迁移过程中新增或修改的源文件可能不在当前任务的迁移范围内。
  • 个别文件失败时,可以使用“重试失败文件”,不用把已经成功的文件再传一遍。

# 六、迁移前端网页托管

HBuilderX 发行 Web 时生成的是编译产物,会包含原阿里云服务空间 ID。直接复制旧编译产物到目标空间后,页面仍无法请求到新空间。其他非编译产物的静态资源(如图片)可正常访问。

所以迁移完成后,需在 HBuilderX 中把项目关联到目标空间,重新发行 Web并上传前端网页托管。

# 6.1 选择迁移目标

在“前端网页托管”页签中选择:

  • 内置前端网页托管:迁移到目标空间自带的前端网页托管;
  • 扩展存储:迁移到目标空间已经开通的扩展存储。

如果目标空间是支付宝云,还要留意路由模式:支付宝云前端网页托管不支持 history 模式。项目当前使用 history 模式时,可以改为 hash 模式,或者把扩展存储作为迁移目标,详见扩展存储托管 Web 静态站点说明。

# 6.2 是否开启打包上传

前端网页托管的打包规则与云存储一致:开启后会在目标位置根目录生成约 900 MB 的 unicloud-aliyun-migration-*.zip 分卷,并额外占用容量。

# 6.3 提交任务

  1. 选择迁移目标。
  2. 根据需要设置“打包上传”。
  3. 点击“开始迁移”。
  4. 页面会二次弹窗确认已选设置。
  5. 点击“确认开始迁移”。

# 6.4 前端网页托管迁移注意事项

  • 只迁移文件,绑定域名及相关配置不会迁移。
  • 目标位置存在同名文件时会直接覆盖。
  • 使用自定义域名时,需要在目标空间重新绑定域名并修改 DNS 解析。
  • 迁移到内置前端网页托管前,需要确认目标服务空间容量是否足够。
  • 前端网页托管迁移与云数据库、云存储迁移不能同时执行,请等待当前任务结束后再提交下一个任务。
  • 个别文件失败时,可以使用“重试失败文件”。

# 七. 迁移云函数和公共模块

“云函数&公共模块”建议放在最后迁移,因为它不仅涉及代码,还要处理运行依赖、插件授权、定时任务和部分空间关联配置。通常把数据库、云存储和网页托管准备好之后,再做这个模块会更稳妥。

如果您的阿里云服务空间开通了激励视频回调功能,uniAdCallback云函数迁移新空间后无法直接使用,因为广告位配置关联的仍是阿里云服务空间,需要在uni-ad控制台创建新的广告位来关联新空间,该操作会自动更新新空间的激励视频回调配置。

# 7.1 执行迁移前检测

该操作会先做一次资源检测,看看哪些内容能直接迁、哪些内容需要你先处理:

  1. 进入“云函数&公共模块”页签。
  2. 点击“检测资源”。
  3. 等待系统读取当前空间资源。
  4. 检查云函数、公共模块、定时任务和插件授权的检测结果。

检测只是“体检”,不会修改阿里云服务空间或目标空间,也不会创建迁移任务,可以放心执行。

检测结果可能包含:

  • 云函数和公共模块数量;
  • 带定时任务的云函数;
  • 付费插件资源;
  • 无法读取或解析的定时任务配置。

如果检测结果里出现无法读取或解析的定时任务配置,先通过阿里云服务空间修正配置后再重新检测。

# 7.2 选择定时任务运行空间

定时任务运行空间支持多选:

  • 旧空间:迁移完成后继续在源阿里云空间运行;
  • 新空间:迁移完成后在目标空间运行。

页面默认只选择新空间,至少要保留一个选项。选择时请注意:

  • 不建议同时选择旧空间和新空间,会导致业务逻辑重复执行;
  • 只选择新空间时,系统会先在新空间重建定时任务,成功后再清理旧空间对应的定时任务;
  • 新空间设置失败时,系统不会清理旧空间定时任务,避免两个空间都无法运行;
  • 云函数代码迁移成功但部分定时任务同步失败时,可以单独点击“重试失败定时任务”。

# 7.3 转移扩展存储

如果阿里云服务空间开通了扩展存储,并且目标空间未开通扩展存储,页面会显示“转移扩展存储”开关。开启后:

  • 扩展存储及其域名、文件转移至目标空间;
  • 阿里云服务空间不再绑定该扩展存储;
  • 阿里云服务空间和目标空间的云函数仍可继续使用该扩展存储;
  • 阿里云服务空间如果在迁移后重新开通扩展存储,则无法继续操作原已迁移的扩展存储。

转移执行期间,不要在控制台操作两个空间的扩展存储。如果目标空间已经存在扩展存储绑定,将不能接收转移。如需转移,请先销毁目标空间的扩展存储。

# 7.4 转移 Redis

阿里云空间如果开通了包年包月 Redis,且目标空间是支付宝云空间时(需未开通Redis),页面会显示“转移 Redis”开关。开启后:

  • Redis连接信息不变,与服务空间的关联关系转移到目标支付宝云空间;
  • 阿里云服务空间和目标空间的云函数仍可继续使用该 Redis;
  • 阿里云服务空间如果在迁移后重新开通Redis,则无法继续操作原已迁移的Redis。

如果 Redis 已开启自动续费,转移时会先关闭。任务完成后可操作重新开启。

# 7.5 业务服务空间白名单配置

这部分不需要额外设置,迁移任务会自动处理阿里云空间已经配置的业务白名单,并将目标空间添加到白名单中,涉及到的业务有:

  • 实人认证
  • 短信服务
  • 一键登录
  • uni-ai
  • 手机号实名核验
  • uni-push

没有配置白名单,或配置中没有待迁移的阿里云服务空间时,不做处理。系统只会追加目标空间,不会删掉原空间。

# 7.6 提交任务

  1. 确认资源检测已经完成,且检测结果仍然有效。
  2. 选择定时任务运行空间。
  3. 根据页面能力和业务需要设置“转移扩展存储”和“转移 Redis”。
  4. 页面会二次弹窗确认已选设置。
  5. 点击“确认开始迁移”。

# 7.7 云函数迁移注意事项

  • 有效的付费和试用插件授权会按迁移规则处理。
  • 单个云函数或公共模块失败时,其他资源会继续处理,最终任务会显示失败项。
  • 迁移后建议检查云函数环境变量、定时任务等配置。

# 八、停服维护

在迁移过程中,如果需要拦截云函数/云对象的请求,不触发函数逻辑执行,可以使用该功能。

开启后,阿里云空间的云函数和云对象请求会被统一拦截,业务代码不会继续执行,表现如下:

  • 云对象:如果客户端没有主动拦截错误并且没有关闭显示交互界面,会自动弹窗显示该提示语
  • 云函数:会直接抛错,需客户端主动拦截报错并提示

# 8.1 开启停服维护

  1. 进入“停服维护”页签。
  2. 打开“停服维护”开关。
  3. 填写不超过 50 个字符的维护提示语,例如“系统维护中,请稍后再试”。
  4. 点击“保存并执行”。
  5. 页面会二次弹窗确认已选设置。
  6. 在确认窗口中点击“确认开启”。

任务执行期间,函数会逐个更新,因此可能出现部分请求已经被拦截、部分请求仍可正常执行的短暂状态。需要依赖停服维护控制数据写入时,务必等任务全部成功后再进行下一步。

此时函数被请求时,success为false,response中会包含对应的维护提示语:

{
    "success": false,
    "error": {
        "code": "FunctionBizError",
        "message": "系统维护中,请稍后再试"
    }
}

# 8.2 关闭停服维护

需要恢复阿里云空间云函数请求时:

  1. 关闭“停服维护”开关
  2. 点击“保存并执行”
  3. 在确认窗口中点击“确认关闭”

关闭任务同样会逐个更新函数。任务完成前,可能有部分函数已经恢复、部分函数仍返回维护提示语。

关闭后系统会保留上一次维护提示语,之后再次开启时可以直接复用;在关闭状态下只修改提示语时,只保存配置,不会创建函数更新任务。

# 8.3 停服维护注意事项

  • 停服维护只对当前阿里云服务空间生效,不会让目标空间进入维护状态。
  • 停服维护任务与“云函数&公共模块”迁移任务、失败定时任务重试互斥,请等待其中一个结束后再执行另一个。
  • 函数请求的次数和资源用量仍会产生,只是不会执行函数逻辑。

# 九、迁移完成

页面显示任务成功,只代表该任务配置的资源已经处理完成。切换业务前,建议先在目标空间核对迁移结果:

  • 数据库中的目标数据表、记录数量、字段类型和索引符合预期;
  • 云存储和前端网页托管中的关键文件可以正常访问,路径和目录结构正确;
  • 云函数、公共模块、依赖和环境变量正常,定时任务只在预期空间运行;
  • 已选择转移的扩展存储和 Redis 状态正确,业务服务白名单包含目标空间;

一键迁移任务完成后,还需要进行客户端升级、域名和第三方配置修改、业务测试及流量切换。这些内容请继续按照uniCloud 阿里云服务空间迁移公告中的“执行迁移后检查及配置”和“注意事项”完成。

# 十、常见问题

# 10.1 可以一次迁移所有模块吗?

不能。云函数&公共模块、云数据库、云存储和前端网页托管需要分别提交。这样可以按业务依赖安排顺序,某个业务模块失败时也能单独处理。

# 10.2 离开页面会中断迁移吗?

不会。迁移任务在云端执行,关闭浏览器或切换到其他页面都不影响。之后再回到这个页面,进度和日志还在。

# 10.3 迁移失败或取消后会从中断位置继续吗?

不会。点击“重新迁移”只会恢复原任务的主要配置,重新提交后会创建新任务,并从头执行当前业务模块。只有页面明确提供的“重试失败定时任务”“重试失败文件”或“重新打包”属于局部处理。

# 10.4 迁移失败会自动回滚吗?

不会。已经写入目标空间的资源会保留。

# 10.5 可以迁移到协作空间吗?

不能。目标空间必须由当前登录账号创建并拥有。即使当前账号拥有协作空间的管理权限,该空间也不能作为迁移目标。

# 10.6 取消后可以更换目标空间吗?

不能。首次成功提交任意业务模块任务后,目标空间绑定就会锁定;取消或失败也不会解锁。

# 10.7 为什么数据库中没有最新数据?

数据库迁移使用的是所选备份。备份完成后产生的数据不会进入这次任务。可以在维护窗口内停止写入,再选择最终备份进行迁移。

# 10.8 为什么目标空间已有文件被替换?

云存储和前端网页托管遇到同名文件时会直接覆盖,不进行内容比对,也不会自动保留旧版本。

# 10.9 Redis 转移会改变实例地址或迁移数据吗?

不会。原实例、数据、地域和公网地址都保持不变。。

# 10.10 扩展存储转移后,原空间还能使用吗?

可以继续通过原空间云函数访问。转移后扩展存储改由目标空间管理,但迁移流程会保留原空间云函数的访问能力。

# 10.11 打包上传生成的 ZIP 有什么用途?

它会在目标空间留下一份便于下载的迁移归档。如果没有下载归档的需求,可以不开启;它不是迁移必需项,还会额外占用容量和执行时间。

本页导读
uni-agent