从 S3 标准存储迁移

云开发云存储兼容 S3 协议，您可以使用 rclone 将其他 S3 兼容存储（Supabase Storage、阿里云 OSS、腾讯云 COS 等）的数据迁移到云开发云存储。

本文介绍云存储文件（bucket 中的对象）的迁移，不涉及数据库、认证、云函数等其他资源的迁移。

前置准备：安装 rclone

rclone 是本次迁移的核心工具，Go 语言编写、单二进制文件、无外部依赖，支持所有 S3 兼容存储之间的数据同步。

官网：https://rclone.org
GitHub：https://github.com/rclone/rclone

macOS
Linux
Windows

推荐使用 Homebrew 安装：

brew install rclone

也可以手动下载二进制：

curl -O https://downloads.rclone.org/rclone-current-osx-amd64.zip
unzip rclone-current-osx-amd64.zip
cd rclone-*-osx-amd64
sudo cp rclone /usr/local/bin/
sudo chown root:wheel /usr/local/bin/rclone
sudo chmod 755 /usr/local/bin/rclone

推荐使用官方安装脚本：

curl https://rclone.org/install.sh | sudo bash

也可以使用系统包管理器：

# Debian / Ubuntu
sudo apt install rclone

# CentOS / RHEL
sudo yum install rclone

推荐使用 Scoop 安装：

scoop install rclone

也可以使用 Chocolatey：

choco install rclone

或者从 rclone 下载页下载 Windows 安装包，解压后把 rclone.exe 放到 PATH 路径中。

验证安装

$ rclone version
rclone v1.74.4
- os/version: darwin 15.3 (64 bit)
- os/kernel: 24.3.0 (arm64)
- os/type: darwin
- os/arch: arm64 (ARMv8 compatible)
- go/version: go1.26.5
- go/linking: dynamic
- go/tags: cmount

rclone 的 remote 配置存储在：

系统	配置文件路径
macOS / Linux	`~/.config/rclone/rclone.conf`
Windows	`%USERPROFILE%\.config\rclone\rclone.conf`

第一步：配置云开发目标端

从任何 S3 兼容源迁入，云开发侧的 remote 配置是一样的。

获取云开发凭证

登录腾讯云访问管理控制台获取 SecretId 和 SecretKey
在云开发-云存储确认对应的 COS bucket 名称和所在 Region

配置 remote

# 直接编辑配置文件
cat >> ~/.config/rclone/rclone.conf << 'EOF'
[cloudbase]
type = s3
provider = Other
access_key_id = <您的 SecretId>
secret_access_key = <您的 SecretKey>
endpoint = cos.ap-shanghai.myqcloud.com
region = ap-shanghai
force_path_style = false
EOF

💡 配置块里的 [cloudbase] 是您给云开发目标端起的 remote 别名，后续所有 rclone 命令都通过 cloudbase: 来引用这个端点；: 是 rclone 区分 remote 和路径的分隔符。名称可以改成您喜欢的（比如 [tcb]），只要全文保持一致即可。

💡 想了解云存储的更多操作，请参考云存储概述。

⚠️ 关键配置：

Region 和 endpoint 要对应，例如上海是 ap-shanghai，endpoint 就是 cos.ap-shanghai.myqcloud.com

force_path_style = false 必加：腾讯云 COS 仅支持 Virtual Hosted-Style 寻址，不加会报 403 PathStyleDomainForbidden

验证连通性

# 列出云开发下的所有 bucket
rclone lsd cloudbase:

# 列出目标 bucket 的文件（迁移前应为空或仅有已有数据）
rclone ls cloudbase:<目标桶名>

第二步：配置源端 S3 Remote

根据您的源存储类型选择对应的配置方式。

从 Supabase Storage 迁移

登录 Supabase Dashboard → 目标项目 → Settings → Storage
启用 S3 connection，生成 S3 Access Key 和 S3 Secret Key
记录项目引用 ID（Project URL 中 <project-ref> 部分）

cat >> ~/.config/rclone/rclone.conf << 'EOF'
[supabase-source]
type = s3
provider = Other
access_key_id = <Supabase S3 Access Key>
secret_access_key = <Supabase S3 Secret Key>
endpoint = https://<project-ref>.supabase.co/storage/v1/s3
region = <源 Region，如 ap-south-1>
EOF

# 验证连通性
rclone lsd supabase-source:
rclone ls supabase-source:<源bucket名>
rclone size supabase-source:<源bucket名>

从阿里云 OSS 迁移

登录阿里云 RAM 控制台获取 AccessKey ID 和 AccessKey Secret
在 OSS 控制台确认 bucket 名称、Region、endpoint

cat >> ~/.config/rclone/rclone.conf << 'EOF'
[oss-source]
type = s3
provider = Alibaba
access_key_id = <阿里云 AccessKey ID>
secret_access_key = <阿里云 AccessKey Secret>
endpoint = oss-<Region>.aliyuncs.com
region = <Region>
EOF

# 验证连通性
rclone lsd oss-source:
rclone size oss-source:<源bucket名>

从腾讯云 COS 迁移

同账号同地域（如源和目标都在广州同一账号下）—— 无需新建 remote，直接复用 cloudbase remote：

rclone copy cloudbase:<源桶名> cloudbase:<目标桶名> --progress

不同账号或不同地域 —— 新建独立的源端 remote：

cat >> ~/.config/rclone/rclone.conf << 'EOF'
[cos-source]
type = s3
provider = Other
access_key_id = <SecretId>
secret_access_key = <SecretKey>
endpoint = cos.<源Region>.myqcloud.com
region = <源Region>
force_path_style = false
EOF

# 验证连通性
rclone lsd cos-source:
rclone size cos-source:<源桶名>

从其他 S3 兼容存储迁移

AWS S3、MinIO、七牛云 Kodo、又拍云 USS 等 S3 兼容存储，均可通过 rclone 的 S3 类型对接：

cat >> ~/.config/rclone/rclone.conf << 'EOF'
[s3-source]
type = s3
provider = <AWS 选 AWS，自建 MinIO 选 Minio，其他选 Other>
access_key_id = <Access Key>
secret_access_key = <Secret Key>
endpoint = <S3 Endpoint>
region = <Region>
EOF

更多 provider 类型请参考 rclone S3 文档。

第三步：执行迁移

建议按以下三步执行：先试运行预览，再正式迁移，最后校验完整性。

# Step 1: 试运行，预览待传输文件
rclone copy <源remote>:<源bucket> cloudbase:<目标桶名> \
  --dry-run \
  --progress \
  --transfers 4

# Step 2: 正式执行迁移
rclone copy <源remote>:<源bucket> cloudbase:<目标桶名> \
  --progress \
  --transfers 4 \
  --checkers 8 \
  --retries 3

# Step 3: 单向校验完整性
rclone check <源remote>:<源bucket> cloudbase:<目标桶名> \
  --one-way \
  --progress

性能调优建议

参数	作用	建议值
`--transfers N`	并发传输文件数	同 Region 8-16，跨云 4
`--checkers N`	并发校验数	通常 2× transfers
`--retries N`	失败重试次数	3
`--bwlimit X`	限速	跨云时建议 `10M` 防占满带宽
`--fast-list`	减少 API 调用	大文件量桶建议加

# 同 Region 高速传输
rclone copy <源>:<源bucket> cloudbase:<目标桶名> \
  --transfers 16 --checkers 32 --fast-list --progress

# 跨云限速传输
rclone copy <源>:<源bucket> cloudbase:<目标桶名> \
  --transfers 4 --bwlimit 10M --retries 3 --progress

关于校验结果

执行 rclone check --one-way 时如果出现 N hashes could not be checked，不是错误。原因是不同 S3 提供商的 ETag/MD5 计算方式不同，rclone 无法直接比对 checksum 时会自动降级为按文件名 + 文件大小校验。只要最终显示 0 differences + N matching files，说明文件完整对应。

断点续传

rclone 的 copy 命令天生支持断点续传：中断后重新执行同一命令，会自动跳过已完成的文件，只传剩余部分。

# 传到一半 Ctrl+C 中断后，重跑同一条命令即可
rclone copy <源>:<源bucket> cloudbase:<目标桶名> --progress

rclone 命令速查

浏览与查看

rclone lsd remote:              # 列出所有 bucket
rclone ls remote:bucket         # 递归列出文件（含大小）
rclone lsl remote:bucket        # 列出文件（含大小+修改时间）
rclone tree remote:bucket       # 树状展示目录结构
rclone size remote:bucket       # 统计文件数和总大小

传输：copy / move / sync 的区别

命令	作用	源文件	目标多余文件
`copy`	拷贝	保留	保留
`move`	移动	删除	保留
`sync`	同步（镜像）	保留	删除

sync 会让目标桶与源桶完全一致，目标端多余文件会被删除，务必须先 --dry-run。

校验与对比

# checksum 校验
rclone check remote:src remote:dst

# 单向校验（只查源→目标）
rclone check remote:src remote:dst --one-way

# 按文件大小校验（跨云 checksum 不可用时）
rclone check remote:src remote:dst --size-only --one-way

过滤传输

# 只传图片
rclone copy remote:src remote:dst --include "*.{jpg,png,gif}"

# 排除临时文件
rclone copy remote:src remote:dst --exclude "*.tmp" --exclude ".DS_Store"

# 按大小过滤
rclone copy remote:src remote:dst --min-size 1M

常见问题

错误信息	可能原因	解决方案
`403 Forbidden`	凭证错误或权限不足	检查 SecretId/SecretKey，确认有 bucket 读写权限
`403 PathStyleDomainForbidden`	rclone 默认用 Path-Style	在云开发 remote 配置中加 `force_path_style = false`
`404 Not Found`	bucket 名不对	确认桶名正确，endpoint 与 Region 匹配
`SignatureDoesNotMatch`	签名错误	SecretKey 可能有多余空格/换行，重新复制
`connection refused`	网络不通	检查防火墙/代理，确认 endpoint 可公网访问
`slow transfer`	跨云公网传输慢	增大 `--transfers` 并发数，或用 `--bwlimit` 放开限制

调试命令

# 查看 rclone 配置
rclone config show

# 调试模式运行（输出详细 HTTP 请求日志）
rclone copy source:bucket cloudbase:bucket --progress -vv

# 按文件大小快速对比（不校验 checksum）
rclone check source:bucket cloudbase:bucket --one-way --size-only

前置准备：安装 rclone​

验证安装​

第一步：配置云开发目标端​

获取云开发凭证​

配置 remote​

验证连通性​

第二步：配置源端 S3 Remote​

从 Supabase Storage 迁移​

从阿里云 OSS 迁移​

从腾讯云 COS 迁移​

从其他 S3 兼容存储迁移​

第三步：执行迁移​

性能调优建议​

关于校验结果​

断点续传​

rclone 命令速查​

浏览与查看​

传输：copy / move / sync 的区别​

校验与对比​

过滤传输​

常见问题​

调试命令​

下一步​