COS Migration工具

功能说明

COS Migration 是一个集成了 COS 数据迁移功能的一体化工具。通过简单的配置操作，用户可以将源地址数据快速迁移至 COS 中，它具有以下特点：

• 丰富的数据源：

  • 本地数据：将本地存储的数据迁移到 COS。

  • 其他云存储：目前支持 AWS S3，阿里云 OSS，七牛存储迁移至 COS，后续会不断扩展。

  • URL 列表：根据指定的 URL 下载列表进行下载迁移到 COS。

  • Bucket 相互复制：COS 的 Bucket 数据相互复制，支持跨账号跨地域的数据复制。

• 断点续传：工具支持上传时断点续传。对于一些大文件，如果中途退出或者因为服务故障，可重新运行工具，会对未上传完成的文件进行续传。

• 分块上传：将对象按照分块的方式上传到 COS。

• 并行上传：支持多个对象同时上传。

• 迁移校验：对象迁移后的校验。

注意：

• COS Migration 的编码格式只支持 UTF-8 格式。
• 使用该工具上传同名文件，会覆盖较旧的同名文件，不支持校对是否存在同名文件的功能。

使用环境

系统环境

Windows、Linux 和 macOS 系统。

软件依赖

• JDK 1.8 X64或以上，有关 JDK 的安装与配置请参见 Java 安装与配置。

使用方法

1. 获取工具

前往下载 COS Migration 工具。

2. 解压缩工具包

Windows

解压并保存到某个目录，例如

C:\Users\Administrator\Downloads\cos_migrate

Linux

解压并保存到某个目录

unzip cos_migrate_tool_v5-master.zip && cd cos_migrate_tool_v5-master

迁移工具结构

正确解压后的 COS Migration 工具目录结构如下所示：

COS_Migrate_tool
|——conf  #配置文件所在目录
|   |——config.ini  #迁移配置文件
|——db    #存储迁移成功的记录
|——dep   #程序主逻辑编译生成的JAR包
|——log   #工具执行中生成的日志
|——opbin #用于编译的脚本
|——src   #工具的源码
|——tmp   #临时文件存储目录
|——pom.xml #项目配置文件
|——README  #说明文档
|——start_migrate.sh  #Linux 下迁移启动脚本
|——start_migrate.bat #Windows 下迁移启动脚本

说明：

• db 目录主要记录工具迁移成功的文件标识，每次迁移任务会优先对比 db 中的记录，若当前文件标识已被记录，则会跳过当前文件，否则进行文件迁移。
• log 目录记录着工具迁移时的所有日志，若在迁移过程中出现错误，请先查看该目录下的 error.log。

3. 修改 config.ini 配置文件

在执行迁移启动脚本之前，需先进行 config.ini 配置文件修改（路径：./conf/config.ini），config.ini 内容可以分为以下几部分：

3.1 配置迁移类型

type 表示迁移类型，用户根据迁移需求填写对应的标识。例如，需要将本地数据迁移至 COS，则[migrateType]的配置内容是type=migrateLocal。

[migrateType]
type=migrateLocal

目前支持的迁移类型如下：

3.2 配置迁移任务

用户根据实际的迁移需求进行相关配置，主要包括迁移至目标 COS 信息配置及迁移任务相关配置。

# 迁移工具的公共配置分节，包含了需要迁移到目标 COS 的账户信息。
[common]
secretId=COS_SECRETID
secretKey=COS_SECRETKEY
bucketName=examplebucket-1250000000
region=ap-guangzhou
storageClass=Standard
cosPath=/
https=off
tmpFolder=./tmp
smallFileThreshold=5242880
smallFileExecutorNum=64
bigFileExecutorNum=8
entireFileMd5Attached=on
daemonMode=off
daemonModeInterVal=60
executeTimeWindow=00:00,24:00
encryptionType=sse-cos

3.3 配置数据源信息

根据[migrateType]的迁移类型配置相应的分节。例如[migrateType]的配置内容是type=migrateLocal, 则用户只需配置[migrateLocal]分节即可。

3.3.1 配置本地数据源 migrateLocal

若从本地迁移至 COS，则进行该部分配置，具体配置项及说明如下：

# 从本地迁移到 COS 配置分节
[migrateLocal]
localPath=E:\\code\\java\\workspace\\cos_migrate_tool\\test_data
excludes=
ignoreModifiedTimeLessThanSeconds=

3.3.2 配置阿里 OSS 数据源 migrateAli

若从阿里云 OSS 迁移至 COS，则进行该部分配置，具体配置项及说明如下：

# 从阿里 OSS 迁移到 COS 配置分节
[migrateAli]
bucket=bucket-aliyun
accessKeyId=yourAccessKeyId
accessKeySecret=yourAccessKeySecret
endPoint= oss-cn-hangzhou.aliyuncs.com
prefix=
proxyHost=
proxyPort=

3.3.3 配置 AWS 数据源 migrateAws

若从 AWS 迁移至 COS，则进行该部分配置，具体配置项及说明如下：

# 从 AWS 迁移到 COS 配置分节
[migrateAws]
bucket=bucket-aws
accessKeyId=AccessKeyId
accessKeySecret=SecretAccessKey
endPoint=s3.us-east-1.amazonaws.com
prefix=
proxyHost=
proxyPort=

3.3.4 配置七牛数据源 migrateQiniu

若从七牛迁移至 COS，则进行该部分配置，具体配置项及说明如下：

# 从七牛迁移到COS配置分节
[migrateQiniu]
bucket=bucket-qiniu
accessKeyId=AccessKey
accessKeySecret=SecretKey
endPoint=www.bkt.clouddn.com
prefix=
proxyHost=
proxyPort=

3.3.5 配置 URL 列表数据源 migrateUrl

若从指定 URL 列表迁移至 COS，则进行该部分配置，具体配置项及说明如下：

# 从 URL 列表下载迁移到 COS 配置分节
[migrateUrl]
urllistPath=D:\\folder\\urllist.txt

3.3.6 配置 Bucket 相互复制 migrateBucketCopy

若从 COS 的一个指定 Bucket 迁移至另一个 Bucket，则进行该部分配置，具体配置项及说明如下：

注意：

发起迁移的账号，需具备源读权限、目的写权限。

# 从源 Bucket 迁移到目标 Bucket 配置分节
[migrateBucketCopy]
srcRegion=ap-shanghai
srcBucketName=examplebucket-1250000000
srcSecretId=COS_SECRETID
srcSecretKey=COS_SECRETKEY
srcCosPath=/

3.3.7 配置又拍云数据源 migrateUpyun

若从又拍云迁移至 COS，则进行该部分配置，具体配置项及说明如下：

[migrateUpyun]
# 从又拍迁移
bucket=xxx
#又拍云操作员的 ID
accessKeyId=xxx
#又拍云操作员的密码     
accessKeySecret=xxx       
prefix=

#又拍云 sdk 限制，这个 proxy 会被设置成全局的 proxy
proxyHost=
proxyPort=

4. 运行迁移工具

Windows

双击 start_migrate.bat 即可运行。

Linux

1.从 config.ini 配置文件读入配置，运行命令为：

sh start_migrate.sh

2.部分参数从命令行读入配置，运行命令为：

sh start_migrate.sh -Dcommon.cosPath=/savepoint0403_10/

说明：

• 工具支持配置项读取方式有两种：命令行读取或配置文件读取。
• 命令行优先级高于配置文件，即相同配置选项会优先采用命令行里的参数。
• 命令行中读取配置项的形式方便用户同时运行不同的迁移任务，但前提是两次任务中的关键配置项不完全一样，例如 Bucket 名称，COS 路径，要迁移的源路径等。因为不同的迁移任务写入的是不同的 db 目录，可以保证并发迁移。请参照前文中的工具结构中的 db 信息。
• 配置项的形式为 -D{sectionName}.{sectionKey}={sectionValue} 的形式。其中 sectionName 是配置文件的分节名称，sectionKey 表示分节中配置项名称，sectionValue 表示分节中配置项值。如设置要迁移到的 COS 路径，则以 -Dcommon.cosPath=/bbb/ddd 表示。

迁移机制及流程

迁移机制原理

COS 迁移工具是有状态的，已经迁移成功的会记录在 db 目录下，以 KV 的形式存储在 leveldb 文件中。每次迁移前对要迁移的路径，先查找下 db 中是否存在， 如果存在，且属性和 db 中存在的一致， 则跳过迁移，否则进行迁移。这里的属性根据迁移类型的不同而不同，对于本地迁移，会判断 mtime。对于其他云存储迁移与 Bucket 复制，会判断源文件的 etag 和长度是否与 db 一致。因此，我们参照 db 中是否有过迁移成功的记录，而不是查找 COS，如果绕过了迁移工具，通过别的方式（如 COSCMD 或者控制台）删除修改了文件，那么运行迁移工具由于不会察觉到这种变化，是不会重新迁移的。

迁移流程步骤

1. 读取配置文件，根据迁移 type，读取相应的配置分节，并执行参数的检查。

2. 根据指定的迁移类型，扫描对比 db 下对所要迁移文件的标识，判断是否允许上传。

3. 迁移执行过程中会打印执行结果，其中 inprogress 表示迁移中，skip 表示跳过，fail 表示失败，ok 表示成功， condition_not_match 表示因为表示因不满足迁移条件而跳过的文件（如 lastmodifed 和 excludes）。失败的详细信息可以在 log 的 error 日志中查看。执行过程示意图如下图所示：

4. 整个迁移结束后会打印统计信息，包括累积的迁移成功量，失败量，跳过量，耗时。对于失败的情况，请查看 error 日志，或重新运行，因为迁移工具会跳过已迁移成功的，对未成功的会重新迁移。运行完成结果示意图如下图所示：

常见问题

如您在使用 COS Migration 工具过程中，遇到迁移失败、运行报错等异常情况，请参阅 COS Migration 工具类常见问题 寻求解决。