文件存储迁移到云开发

本文档将指导您如何将数据从本地存储或其他云平台迁移到 CloudBase 云存储。

迁移方案概览

根据您的数据来源和迁移需求，选择合适的迁移方案：

数据来源	推荐工具	适用场景	数据量
本地数据	COSBrowser	可视化操作、中小数据量	< 10GB
本地数据 / 腾讯云COS	COSCLI	命令行操作、批量处理	任意
第三方云存储	rclone、云迁移 CMG	跨云平台迁移	任意

一、本地数据迁移到云存储

方案 1：COSBrowser（推荐）

工具介绍

COSBrowser 是一款可视化界面工具，支持用户通过简单的界面操作进行数据上传、下载、生成访问链接等功能。

适用场景

✅ 中小数据量迁移（< 10GB）
✅ 需要可视化操作界面
✅ 批量上传下载文件
✅ 管理云存储文件

操作步骤

1. 下载并安装 COSBrowser

访问 COSBrowser 下载页面下载并安装客户端。

2. 使用密钥登录

重要说明

必须使用 密钥登录 方式，并指定存储桶名和地域。使用腾讯云账号直接登录无法管理 CloudBase 云存储桶。

登录步骤：

打开 COSBrowser 工具
选择「密钥登录」
填入以下信息：
- SecretId / SecretKey：在访问密钥管理中获取
- 存储桶名称：云开发/云存储获取存储桶名称
- 所属地域：选择您的环境所在地域（云存储这里固定为： ap-shanghai）

3. 上传本地文件

登录成功后：

在左侧本地文件系统中选择要上传的文件或文件夹
拖拽到右侧云存储区域，或右键点击选择「上传」
等待上传完成

详细使用方法请参考：COSBrowser 使用文档

方案 2：COSCLI

工具介绍

COSCLI 是客户端命令行工具，使用 Golang 构建，无需安装依赖环境，开箱即用。通过简单的命令行指令即可对云存储中的对象实现批量上传、下载、删除等操作。

技术支持说明

COSCLI 工具由 腾讯云 COS 团队 维护，CloudBase 云开发团队不提供该工具的技术支持。使用该工具需要具备一定的命令行操作和技术基础。如遇到工具相关问题，请参考 COSCLI 官方文档或联系 COS 团队。

适用场景

✅ 大量文件批量迁移
✅ 自动化脚本部署
✅ 熟悉命令行操作
✅ 支持跨桶操作

详细使用方法请参考：COSCLI 工具文档

二、第三方云存储迁移到云开发

方案：rclone 迁移（适用于 S3 兼容存储）

云开发云存储兼容 S3 协议，您可以直接使用 rclone 将 Supabase Storage、阿里云 OSS、AWS S3 等 S3 兼容存储的数据迁移到云开发。rclone 是 Go 语言编写的单二进制文件，无需额外依赖，支持断点续传和并发传输。

➡️ 详细步骤请参考：从 S3 兼容存储迁移

方案：云迁移 CMG

云迁移（Cloud Migration，CMG)是腾讯云提供的迁移工具整合以及监控平台。如果您的数据存储在阿里云 OSS、AWS S3 等第三方云平台，可以使用云迁移 CMG服务快速迁移到 CloudBase 云存储。

支持的云平台

云迁移 CMG 支持从以下云平台迁移数据：

云平台	迁移教程
阿里云 OSS	阿里云 OSS 迁移教程
AWS S3	AWS S3 迁移教程
七牛云	七牛云迁移教程
又拍云	又拍云迁移教程
华为云 OBS	华为云 OBS 迁移教程
金山云 KS3	金山云 KS3 迁移教程
百度云 BOS	百度云 BOS 迁移教程

三、LeanCloud 存储迁移到云开发

方案：使用迁移脚本工具

下载迁移脚本

本迁移方案需要使用官方提供的迁移脚本工具。请先下载脚本包：

➡️ 下载 LeanCloud 迁移工具

🚀 下载后解压到本地，请仔细阅读 README.md 文档，按照以下步骤进行配置和运行。

使用迁移脚本工具可以帮助你将 LeanCloud 存储的文件批量迁移到腾讯云开发云存储。

功能特性

✅ 从 LeanCloud _File 表读取所有文件元数据
✅ 自动拼接 URL 并批量下载文件
✅ 批量上传到腾讯云开发云存储
✅ 支持并发控制，提高迁移效率
✅ 自动重试失败的下载
✅ 生成详细的迁移报告

项目结构

原始结构（解压后）

这是你解压 zip 包后看到的文件结构：

leancloud_storage_migrate/
├── migrate.js              # 主迁移脚本（核心文件）
├── package.json            # 项目依赖配置文件
└── README.md               # 项目说明文档

说明

这 3 个文件是项目的原始文件，需要手动配置后才能使用。

安装依赖、脚本运行后的结构

leancloud_storage_migrate/
├── migrate.js              # 主迁移脚本（核心文件）
├── package.json            # 项目依赖配置文件
├── package-lock.json       # 依赖版本锁定文件（自动生成）
├── README.md               # 项目说明文档
├── .gitignore             # Git 忽略文件配置
├── node_modules/          # 依赖包目录（npm install 后生成）
├── temp_files/            # 临时文件存储目录（运行时自动创建，完成后自动删除）
└── migration_report.json  # 迁移报告文件（运行完成后生成）

快速开始

第一步：安装 Node.js 依赖

在项目目录下运行以下命令安装所需依赖：

cd /path/to/leancloud_storage_migrate
npm install

这将自动安装以下依赖包：

leancloud-storage - LeanCloud SDK
@cloudbase/node-sdk - 腾讯云开发 Node.js SDK

第二步：配置参数

打开 migrate.js 文件，找到配置区域（约在第 17-32 行），填入你的配置信息：

// LeanCloud 配置
const LEANCLOUD_CONFIG = {
  appId: 'YOUR_LEANCLOUD_APP_ID',        // 👈 替换为你的 LeanCloud App ID
  appKey: 'YOUR_LEANCLOUD_APP_KEY',      // 👈 替换为你的 LeanCloud App Key
  serverURL: 'https://YOUR_LEANCLOUD_SERVER_URL', // 👈 替换为你的 API 域名
  fileDomain: 'https://YOUR_FILE_DOMAIN' // 👈 替换为你的文件域名
};

// 腾讯云开发配置
const CLOUDBASE_CONFIG = {
  env: 'YOUR_ENV_ID',              // 腾讯云开发环境 ID
  secretId: 'YOUR_SECRET_ID',       // 腾讯云 API 密钥 SecretId
  secretKey: 'YOUR_SECRET_KEY'      // 腾讯云 API 密钥 SecretKey
};

获取配置信息说明

LeanCloud 配置：

登录 LeanCloud 控制台
选择你的应用
进入「设置」→「应用凭证」，获取 App ID 和 App Key
进入「设置」→「域名绑定」，获取 API 域名（serverURL）和文件域名（fileDomain）

腾讯云开发配置：

登录腾讯云开发平台
选择你的环境，获取环境 ID（env）
登录腾讯云 API 密钥管理
创建或查看密钥，获取 SecretId 和 SecretKey

⚠️ 重要：配置安全域名

登录腾讯云开发平台
进入「环境管理」→「安全来源」
添加你的域名到安全域名列表（避免 CORS 错误）

第三步：运行迁移脚本

配置完成后，执行以下命令启动迁移：

npm start

或者直接使用 Node.js 运行：

node migrate.js

第四步：查看运行结果

脚本运行时会实时显示进度信息：

========================================
LeanCloud → 腾讯云开发 文件迁移工具
========================================

开始从 LeanCloud 查询 _File 表...
已查询 50 个文件...
✓ 共查询到 50 个文件

开始迁移文件，并发数: 5
----------------------------------------

[1] 处理文件: example.jpg
  下载 URL: https://xxx.com/xxx.jpg
  正在下载...
  ✓ 下载完成
  正在上传到云开发: migrated/example.jpg
  ✓ 上传完成，fileID: cloud://xxx...

[2] 处理文件: photo.png
  下载 URL: https://xxx.com/yyy.png
  正在下载...
  ✓ 下载完成
  正在上传到云开发: migrated/photo.png
  ✓ 上传完成，fileID: cloud://yyy...

...

========================================
迁移完成！
----------------------------------------

总计: 50 个文件
成功: 48 个
失败: 2 个

迁移报告已保存到: ./migration_report.json

完成后会在当前目录生成 migration_report.json 报告文件。

可选配置

你可以调整以下配置来优化迁移性能：

const DOWNLOAD_CONFIG = {
  tempDir: './temp_files',  // 临时文件存储目录
  concurrency: 5,          // 并发下载数量（建议 3-10）
  retryTimes: 3,           // 下载失败重试次数
  timeout: 30000           // 请求超时时间（毫秒）
};

迁移流程

查询文件列表：从 LeanCloud _File 表查询所有文件
下载文件：根据 key 拼接 URL 并下载到本地临时目录
上传文件：将文件上传到腾讯云开发云存储
生成报告：生成 migration_report.json 报告文件
清理临时文件：删除本地临时文件

输出结果

迁移完成后，会生成 migration_report.json 报告文件，包含：

{
  "timestamp": "2026-01-21T10:30:00.000Z",
  "summary": {
    "total": 100,
    "success": 98,
    "failed": 2
  },
  "successList": [
    {
      "objectId": "xxx",
      "name": "example.jpg",
      "fileID": "cloud://xxx.cloudbase.net/xxx",
      "cloudPath": "migrated/example.jpg"
    }
  ],
  "errorList": [
    {
      "objectId": "yyy",
      "name": "failed.png",
      "error": "下载超时"
    }
  ]
}

注意事项

网络稳定性：确保网络连接稳定，大文件迁移可能需要较长时间
磁盘空间：确保有足够的磁盘空间存储临时文件
并发数量：根据网络带宽调整并发数，避免过高导致请求失败
重试机制：失败的文件会自动重试，最终失败的会记录在报告中
云端路径：所有文件会上传到 migrated/ 目录下，可根据需要修改
fileID 保存：上传后的 fileID 会记录在报告中，建议保存以便后续使用

故障排查

下载失败

检查 fileDomain 配置是否正确
检查网络连接是否正常
尝试增加 timeout 超时时间

上传失败

确认腾讯云开发环境 ID 正确
检查是否配置了安全域名
确认云存储配额是否充足

CORS 错误

登录腾讯云开发控制台
在「安全配置」→「安全来源」中添加你的域名

四、常见问题

1. 如何提高迁移速度？

使用 COSCLI 工具的并发上传功能
选择与源数据 相同地域 减少网络延迟
使用 高带宽网络 进行传输
对于小文件，可以 打包后上传 再解压

2. 迁移会产生哪些费用？

存储费用：按实际存储量计费
流量费用：CDN 流量费用

详见：CloudBase 计费说明

迁移方案概览​

一、本地数据迁移到云存储​

方案 1：COSBrowser（推荐）​

工具介绍​

适用场景​

操作步骤​

方案 2：COSCLI​

工具介绍​

适用场景​

二、第三方云存储迁移到云开发​

方案：rclone 迁移（适用于 S3 兼容存储）​

方案：云迁移 CMG​

支持的云平台​

三、LeanCloud 存储迁移到云开发​

方案：使用迁移脚本工具​

功能特性​

项目结构​

原始结构（解压后）​

安装依赖、脚本运行后的结构​

快速开始​

可选配置​

迁移流程​

输出结果​

注意事项​

故障排查​

四、常见问题​

1. 如何提高迁移速度？​

2. 迁移会产生哪些费用？​

迁移方案概览

一、本地数据迁移到云存储

方案 1：COSBrowser（推荐）

工具介绍

适用场景

操作步骤

方案 2：COSCLI

工具介绍

适用场景

二、第三方云存储迁移到云开发

方案：rclone 迁移（适用于 S3 兼容存储）

方案：云迁移 CMG

支持的云平台

三、LeanCloud 存储迁移到云开发

方案：使用迁移脚本工具

功能特性

项目结构

原始结构（解压后）

安装依赖、脚本运行后的结构

快速开始

可选配置

迁移流程

输出结果

注意事项

故障排查

四、常见问题

1. 如何提高迁移速度？

2. 迁移会产生哪些费用？