uniCloud多云方案操作指南

新增于 HBuilderX 5.05+

uniCloud多云方案支持在不同云服务商的服务空间之间切换。通过uni扩展数据库和uni扩展存储共享数据与文件，配合云函数同步和客户端配置更新，客户端可以根据配置使用主服务空间或备用服务空间。

多云方案可用于跨云灾备，也可用于计划性的服务空间切换。开发者在控制台启用多云方案后，客户端将在新配置生效后使用所选的备用服务空间；关闭后，客户端将切换回主服务空间。

本文将配置多云方案的当前服务空间称为主空间，将启用后使用的目标服务空间称为备用空间。

前置准备

使用多云方案前，需要完成以下准备工作：

1. 准备备用服务空间

1. 在不同云服务商创建一个服务空间，推荐使用支付宝云或者腾讯云。
2. 备用空间用于承接主空间的业务，不建议预先部署其他业务的云函数/云对象代码。切换时会同步主空间代码，并覆盖备用空间中同名的云函数和Schema。

2. 开通扩展数据库

如项目涉及数据库操作，需要统一使用uni扩展数据库，确保主备空间访问同一份数据，避免切换后访问不同数据库造成数据不一致。

关于uni扩展数据库的介绍，请参考：uni扩展数据库

如何开通uni扩展数据库，请参考：开通uni扩展数据库

开通扩展数据库后，需要授权主空间和备用空间访问数据库，具体操作请参考：扩展数据库跨空间授权

3. 开通扩展存储

多云方案以uni扩展存储作为基础能力，配置文件通过CDN分发。需要在主空间开通uni扩展存储服务并绑定CDN域名。

如使用了云存储功能，建议将云存储切换到扩展存储。

关于uni扩展存储的介绍，请参考：uni扩展存储

如何开通uni扩展存储，请参考：开通uni扩展存储

4. 项目发行配置

要在服务空间相关联的项目中使用多云方案，必须在uniCloud控制台的“多云方案”页面配置并保存“服务接入点”后，重新关联服务空间并重新发行项目生效。

后续修改服务接入点，也需要重新关联服务空间并重新发行项目。

本地调试时需要重新关联服务空间并切换到云端才会生效。

控制台操作

在uniCloud控制台进入主服务空间详情，点击左侧“多云方案”菜单进行配置和管理。支付宝云、腾讯云、阿里云服务空间均提供此入口。

页面中的“状态”用于选择客户端使用的服务空间：

状态	含义
关闭	使用当前服务空间，即主空间
启用	使用“选择服务空间”中指定的备用空间

配置服务接入点

服务接入点是接入多云方案的基础，本质上是绑定扩展存储中的CDN域名，用于向客户端分发服务空间切换配置。

未开通扩展存储

如果未开通扩展存储服务，请按照提示开通扩展存储并绑定CDN域名。

已开通扩展存储

如果已开通扩展存储，请在“服务接入点”中选择对应的CDN域名，点击“保存”。

保存服务接入点后，在HBuilderX中重新关联服务空间并重新发行项目生效。

选择并保存服务接入点后，请勿在扩展存储中删除对应域名，以免客户端无法获取配置。切换服务空间前，必须先保存服务接入点。

切换到备用空间

需要使用备用空间时，按以下步骤操作：

1. 将“状态”设置为“启用”。
2. 在“选择服务空间”中选择备用空间。列表按云服务商分组，仅展示与主空间不同云服务商的服务空间。
3. 点击“应用”，在“服务空间切换”对话框中确认切换方向及注意事项，点击“继续”。
4. 等待系统将主空间云函数、公共模块、Schema同步至备用空间。任务完成后，系统更新CDN上的切换配置。

客户端获取到新配置后，需要重启应用才能使用备用空间，具体接入方式见客户端API。

注意

1. 切换过程中会同步主空间云函数至备用空间，备用空间有同名云函数、Schema将覆盖，在此期间请勿上传云函数。
2. 启用期间如需修改云函数代码，请手动切换至备用空间上传。
3. 如主空间中使用了付费云函数，需要在切换前重新购买至备用空间，防止切换后付费云函数无法使用。
4. 主空间如果存在定时任务，同步时会暂停主空间定时任务，自动在备用空间创建相同的定时任务执行。

切换回主空间

需要重新使用主空间时，在主空间的“多云方案”页面操作：

1. 将“状态”设置为“关闭”。
2. 点击“应用”，在“服务空间切换”对话框中确认切换方向，点击“继续”。
3. 等待系统将备用空间云函数、公共模块、Schema同步回主空间。任务完成后，系统更新CDN配置，客户端获取新配置并重启后使用主空间。

切换过程中同样会覆盖主空间中同名的云函数和Schema，请勿在同步期间上传云函数。同步完成后，建议检查主空间的云函数和数据访问是否与备用空间保持一致。

查看切换任务

切换期间，页面会展示同步方向、进度和最新日志，可点击“日志”查看详情。如果云函数同步失败，页面会提供“重新同步失败云函数”按钮，也可点击“取消”取消当前同步任务。

客户端 API

多云方案的客户端API名称保持为uniCloud.onFailover和uniCloud.offFailover。

uniCloud.onFailover(listener)

监听服务空间切换事件。当多云方案的切换状态发生变化时触发。

参数说明

参数名	类型	必填	说明
listener	Function	是	事件监听函数

listener回调参数

参数名	类型	说明
isEnabled	Boolean	是否启用多云方案（true表示使用备用空间，false表示使用主空间；新配置在重启后生效）
failoverSpace	Object	备用服务空间配置
hasStatusChanged	Boolean	状态是否发生变化（相比本地缓存的配置）

注意：当hasStatusChanged为true时，表示配置发生了变化，需要提示用户重启应用使新配置生效。

示例

// 在 App.vue 的 onLaunch 中监听
uniCloud.onFailover(function(event) {
  console.log('服务空间切换事件触发')
  console.log('最新配置状态:', event.isEnabled ? '需要使用备用空间' : '使用主空间')
  console.log('状态是否变化:', event.hasStatusChanged)

  if (event.hasStatusChanged) {
    // 配置发生变化，必须重启应用才能使新配置生效
    uni.showModal({
      title: '服务状态变更',
      content: event.isEnabled ? '服务配置已更新，需要重启应用切换到备用服务' : '服务配置已更新，需要重启应用切换回主服务',
      confirmText: '立即重启',
      cancelText: '稍后',
      success: (res) => {
        if (res.confirm) {
          // 重启应用使新配置生效
          // #ifdef APP-PLUS
          plus.runtime.restart()
          // #endif
          // #ifdef H5
          location.reload()
          // #endif
        }
      }
    })
  }
})

示例源码如下，请查看 pre > code 标签中的内容

// 在 App.vue 的 onLaunch 中监听
uniCloud.onFailover(function(event) {
  console.log('服务空间切换事件触发')
  console.log('最新配置状态:', event.isEnabled ? '需要使用备用空间' : '使用主空间')
  console.log('状态是否变化:', event.hasStatusChanged)

  if (event.hasStatusChanged) {
    // 配置发生变化，必须重启应用才能使新配置生效
    uni.showModal({
      title: '服务状态变更',
      content: event.isEnabled ? '服务配置已更新，需要重启应用切换到备用服务' : '服务配置已更新，需要重启应用切换回主服务',
      confirmText: '立即重启',
      cancelText: '稍后',
      success: (res) => {
        if (res.confirm) {
          // 重启应用使新配置生效
          // #ifdef APP-PLUS
          plus.runtime.restart()
          // #endif
          // #ifdef H5
          location.reload()
          // #endif
        }
      }
    })
  }
})

uniCloud.offFailover(listener)

移除服务空间切换事件监听。

参数说明

参数名	类型	必填	说明
listener	Function	是	要移除的监听函数，必须与添加时的函数引用一致

示例

// 正确用法：使用同一个函数引用
function failoverHandler(event) {
  console.log('服务空间切换:', event)
}

// 添加监听
uniCloud.onFailover(failoverHandler)

// 移除监听
uniCloud.offFailover(failoverHandler)

示例源码如下，请查看 pre > code 标签中的内容

// 正确用法：使用同一个函数引用
function failoverHandler(event) {
  console.log('服务空间切换:', event)
}

// 添加监听
uniCloud.onFailover(failoverHandler)

// 移除监听
uniCloud.offFailover(failoverHandler)

// 错误用法：无法移除
uniCloud.onFailover(function(event) {
  console.log(event)
})
uniCloud.offFailover(function(event) {
  console.log(event)  // 这是一个新的函数，无法移除上面的监听
})

示例源码如下，请查看 pre > code 标签中的内容

// 错误用法：无法移除
uniCloud.onFailover(function(event) {
  console.log(event)
})
uniCloud.offFailover(function(event) {
  console.log(event)  // 这是一个新的函数，无法移除上面的监听
})

使用场景

场景一：强制重启切换（推荐）

当检测到配置变化时，强制用户重启应用以确保切换生效。

// App.vue
export default {
  onLaunch() {
    uniCloud.onFailover((event) => {
      if (event.hasStatusChanged) {
        // 配置变化，必须重启才能生效
        uni.showModal({
          title: '服务状态变更',
          content: event.isEnabled
            ? '服务配置已更新，需要重启应用切换到备用服务'
            : '服务配置已更新，需要重启应用切换回主服务',
          showCancel: false,
          confirmText: '立即重启',
          success: () => {
            // #ifdef APP-PLUS
            plus.runtime.restart()
            // #endif
            // #ifdef H5
            location.reload()
            // #endif
          }
        })
      }
    })
  }
}

示例源码如下，请查看 pre > code 标签中的内容

// App.vue
export default {
  onLaunch() {
    uniCloud.onFailover((event) => {
      if (event.hasStatusChanged) {
        // 配置变化，必须重启才能生效
        uni.showModal({
          title: '服务状态变更',
          content: event.isEnabled
            ? '服务配置已更新，需要重启应用切换到备用服务'
            : '服务配置已更新，需要重启应用切换回主服务',
          showCancel: false,
          confirmText: '立即重启',
          success: () => {
            // #ifdef APP-PLUS
            plus.runtime.restart()
            // #endif
            // #ifdef H5
            location.reload()
            // #endif
          }
        })
      }
    })
  }
}

场景二：可选重启切换

让用户选择是否立即重启，适用于非紧急切换场景。

// App.vue
export default {
  onLaunch() {
    uniCloud.onFailover((event) => {
      if (event.hasStatusChanged) {
        uni.showModal({
          title: '提示',
          content: '服务状态已更新，重启应用后生效',
          confirmText: '立即重启',
          cancelText: '稍后',
          success: (res) => {
            if (res.confirm) {
              // #ifdef APP-PLUS
              plus.runtime.restart()
              // #endif
              // #ifdef H5
              location.reload()
              // #endif
            }
            // 用户选择稍后，下次启动应用时会使用新配置
          }
        })
      }
    })
  }
}

示例源码如下，请查看 pre > code 标签中的内容

// App.vue
export default {
  onLaunch() {
    uniCloud.onFailover((event) => {
      if (event.hasStatusChanged) {
        uni.showModal({
          title: '提示',
          content: '服务状态已更新，重启应用后生效',
          confirmText: '立即重启',
          cancelText: '稍后',
          success: (res) => {
            if (res.confirm) {
              // #ifdef APP-PLUS
              plus.runtime.restart()
              // #endif
              // #ifdef H5
              location.reload()
              // #endif
            }
            // 用户选择稍后，下次启动应用时会使用新配置
          }
        })
      }
    })
  }
}

场景三：静默记录

仅记录状态变化，不打扰用户。用户下次自然重启应用时会自动使用新配置。

// App.vue
export default {
  onLaunch() {
    uniCloud.onFailover((event) => {
      // 仅记录日志，不提示用户
      console.log('多云方案配置更新:', {
        isEnabled: event.isEnabled,
        hasStatusChanged: event.hasStatusChanged
      })
      // 用户下次重启应用时会自动使用新配置
    })
  }
}

示例源码如下，请查看 pre > code 标签中的内容

// App.vue
export default {
  onLaunch() {
    uniCloud.onFailover((event) => {
      // 仅记录日志，不提示用户
      console.log('多云方案配置更新:', {
        isEnabled: event.isEnabled,
        hasStatusChanged: event.hasStatusChanged
      })
      // 用户下次重启应用时会自动使用新配置
    })
  }
}

工作原理

切换机制说明：

多云方案的服务空间切换采用下次启动生效的机制，确保应用运行的稳定性：

1. 启动时读取缓存：应用启动时，SDK首先读取本地缓存的多云方案配置，根据缓存配置决定使用主空间还是备用空间
2. 异步获取最新配置：启动后SDK会异步从CDN请求最新的多云方案配置文件
3. 检测配置变化：将最新配置与本地缓存对比，如果状态发生变化（如从关闭变为启用），触发onFailover事件
4. 通知用户重启：开发者在onFailover事件中提示用户重启应用，重启后新配置才会生效
5. 请求失败时刷新配置：云函数/云对象/clientDB请求失败时，SDK会自动触发配置刷新，获取控制台发布的最新状态。服务空间的切换由开发者在控制台操作

重要：当检测到配置变化时，当前运行的应用仍使用原来的服务空间。必须重启应用（App重启或H5刷新页面）后，新的配置才会生效。

配置文件格式

多云方案配置文件由控制台生成并通过CDN分发，路径保持为 .unicloud/failover-cfg.json。启用多云方案并选择支付宝云备用空间时，配置示例如下：

{
  "enable": true,
  "interval": 300000,
  "space": {
    "provider": "alipay",
    "spaceId": "env-xxxxxxxx",
    ...
  },
  "_lastModifiedAt": 1702627200000
}

示例源码如下，请查看 pre > code 标签中的内容

{
  "enable": true,
  "interval": 300000,
  "space": {
    "provider": "alipay",
    "spaceId": "env-xxxxxxxx",
    ...
  },
  "_lastModifiedAt": 1702627200000
}

字段说明

字段	类型	说明
enable	Boolean	是否启用多云方案。true表示使用备用空间；false表示使用主空间
interval	Number	配置刷新间隔（毫秒）。0表示每次请求都检查；正数表示间隔时间
space	Object	备用服务空间配置，启用时提供；关闭时不包含此字段
space.provider	String	云服务商，可选值：aliyun、alipay、tcb
space.spaceId	String	服务空间ID
space.clientSecret	String	阿里云服务空间的客户端密钥
space.accessKey	String	支付宝云服务空间的accessKey
space.secretKey	String	支付宝云服务空间的secretKey
space.spaceAppId	String	支付宝云服务空间的应用ID
space.endpoint	String	服务空间的网关地址，存在已启用的网关域名时提供
space.cloudFunctionCustomDomain	String	云函数自定义域名，配置了该域名时提供
_lastModifiedAt	Number	配置最后修改时间戳（毫秒）

注意事项

1. 重启生效：多云方案配置变化后，必须重启应用（App重启或H5刷新页面）才能生效。当前运行的应用会继续使用原来的服务空间，直到下次启动

2. 发行与调试要求：配置或修改服务接入点后，需要重新关联服务空间并重新发行项目。运行本地云函数时不会使用多云方案；本地调试需要重新关联服务空间并切换到云端

3. 本地缓存：SDK会将配置缓存到本地存储，应用启动时优先使用缓存配置。即使CDN不可访问也能使用最近一次的配置

4. 首次启动：首次安装的应用没有缓存配置，会使用项目发行时配置的默认服务空间（主空间）

5. 刷新间隔：合理设置interval参数，避免频繁请求CDN造成不必要的流量消耗

6. 云函数同步：切换任务会同步云函数、公共模块和Schema。启用期间修改代码需上传至备用空间，切换回主空间时会将备用空间代码同步回来

7. 数据一致性：如项目涉及数据库操作，需使用uni扩展数据库并授权主备空间访问同一份数据。使用云存储时，建议统一使用uni扩展存储共享文件

相关文档

• uni扩展数据库
• uni扩展存储
• uniCloud客户端SDK