BosImport

概述

BosImport工具用于将其它云存储的数据迁移到BOS。 工具基于C-S结构实现,client端负责读取文件列表, 任务调度和进度统计等工作, 所有和迁移相关的参数/配置都在client端进行;迁移任务在server端完成, client端通过RPC请求通知server对哪些文件进行迁移。

BosImport工具具有以下特点:

  • 支持多种迁移方式, 可扩展性良好, 支持迁移不同的源端目的端,目前支持AWS S3、阿里云OOS、腾讯云COS、七牛、小米生态云、BOS等;
  • 支持实时迁移并发度/压力调节,server"热升级";
  • 支持迁移任务热启停,迁移进度实时显示;
  • 数据传输过程不落磁盘, 减少磁盘IO, 传输过程中将大文件切块传输, 块大小可以实时配置, 最大效率地利用迁移机器的带宽资源;
  • 负载均衡, client会选择没有压力的server进行迁移任务;
  • 支持自定义迁移的任务列表和文件数目;
  • 支持迁移任务QPS和流量限速;
  • 支持多种迁移策略:
    1. FORCE_OVERWRITE: 强制覆盖目的端文件, 可能会破坏目的端文件, 危险, 慎用, 在确定需求的前提下使用;
    2. KEEP_DESTITNATION: 如果目的端有同名文件文件存在则跳过;
    3. KEEP_NEWER: 如果目的端有同名文件存在, 且新于源端文件, 则跳过, 否则覆盖之; 如果目的端没有"同名"文件(有可能迁移时文件需要改名)存在, 则按照迁移规则直接复制到目的端

下载地址

文件名及下载地址 MD5
bosimport-1.0.0.tar a8093d5cda3d13c38a563f622440e3a1

运行环境

Java 1.7及以上

目录结构

├── client
│   ├── client.jar   # client jar,负责读取文件列表, 任务调度和进度统计等工作
│   ├── resources    # client配置文件夹
│   │   ├── client.properties   # client迁移任务配置文件
│   │   └── client_logback.xml   # client日志配置文件
│   ├── start_client.sh   # 启动client进程
│   └── stop_client.sh   # 停止client进程
├── properties_examples   # 迁移任务client.properties不同源示例配置
│   ├── client.properties.bos   # BOS迁移到BOS
│   ├── client.properties.bos-check   # BOS到BOS校验
│   ├── client.properties.cos   # COS迁移到BOS
    ├── client.properties.fds   # 小米生态云迁移到BOS
│   ├── client.properties.http   # HTTP迁移到BOS
│   ├── client.properties.oss   # OOS迁移到BOS
│   ├── client.properties.qiniu   # 七牛迁移到BOS
│   └── client.properties.s3   # AWS S3迁移到BOS
├── server
│   ├── resources   # server配置文件夹
│   │   ├── server.properties   # server配置文件
│   │   └── server_logback.xml   # server日志配置文件
│   ├── server.jar   # server.jar,负责读取数据源并迁移到BOS
    ├── supervise.sh   # supervisor脚本,保持server进程退出自动重启
│   ├── start_server.sh   # 启动server进程
│   └── stop_server.sh   # 停止server进程
├── start_migration.sh   # 一键启动迁移任务,包括server和client
└── stop_migration.sh   # 一键停止迁移任务,包括server和client

部署方式

BosImport工具主要包括server和client两部分。

  • 对于小于30TB的小规模数据迁移,client和server可以运行在同一个机器上,修改client.properties文件,然后直接sh start_migration.sh启动迁移即可。
  • 对于大规模的数据迁移,或者需要提高迁移速度,可以部署多个server到多台机器上,client通过serverList配置多个server,并根据负载选择一个合适的server进行迁移,从而提高迁移效率。

注意事项

  1. 单机可以开多个server进程,但是需要注意server/logs文件夹占用空间大小;
  2. server进程线程数需要根据机器CPU核数调整到合适数目,maxConnectionsPerServer建议设置为1,否则fail出现次数容易比较多。

部署server

  1. 修改server的配置文件 server.properties, 主要修改监听端口号;
  2. 如果需要多个server并发迁移,可以批量复制server文件夹到用于迁移的多台机器上;
  3. 执行sh start_server.sh启动server,通过检查server进程是否监听了指定端口来判断是否已经成功启动server。

部署client

修改client.properties文件对client进行配置, 主要配置项包括

  1. 迁移类型:type,迁移名称:migrationName
  2. server响应单次请求所使用的并发数:serverThreadNum
  3. 单次请求文件数量: filesPerRequest
  4. 任务列表: taskList
  5. 文件列表:listDelimiter, 指定文件列表的表示形式: listFormat
  6. 源端目的端ak, sk, endpoint等信息
  7. 迁移策略:migrationStrategy
  8. 切块大小: blockSize, 默认5MB,因为BOS分块上传时Part数目范围是1-10000,blockSize=5MB时可以上传的单个Object最大为50GB,迁移大文件时需要调大该参数,Part数目在1000以内较佳。

启动迁移

server和client单机部署时,执行sh start_migration.sh脚本启动server和client,系统根据client.properties文件中配置的文件列表迁移数据;如果server部署到了多台机器上,需要在每台机器上分别执行sh start_server.sh启动server进程。

停止迁移

执行sh stop_migration.sh脚本停止server和client。如果server部署到了多台机器上,需要在每台机器上分别执行sh stop_server.sh停止server进程。

配置文件

server.properties

server.properties文件用于配置端口、流量限制以及RPC服务线程数, 在没有特殊要求的情况下, 一般只需要修改监听端口号即可, 默认监听8090端口。

## server进程监听的端口号
serverPort=8090

# 每个client请求对应的处理线程数目
fileWorkerNum=50

client.properties

client.properties必须是UTF8编码的):主要包含迁移的任务列表信息和并发度, 配置文件中有些配置被修改后会自动重新加载, 如serverThreadNum(单次迁移请求期望server使用的并发线程数量); 有些是不能重新加载的, 如taskList(任务任务列表),具体配置可以参考文件内的说明。

配置示例

迁移类型 示例文件 说明
从http迁移到BOS properties_examples/client.properties.http 给定url(每个URL代表一个可以直接使用GET请求下载的文件)列表, 迁移到BOS
从OSS迁移到BOS properties_examples/client.properties.oss 给定OOS的Object列表, 配置源端和目的端ak/sk等信息
从COS迁移到BOS properties_examples/client.properties.cos 给定COS的Object列表, 配置源端和目的端ak/sk等信息
从七牛迁移到BOS properties_examples/client.properties.qiniu 给定七牛的Object列表, 配置源端和目的端ak/sk等信息
从AWS S3迁移到BOS properties_examples/client.properties.s3 给定AWS S3的Object列表, 配置源端和目的端ak/sk等信息;srcEndpoint参数需要填S3 region
从FDS迁移到BOS properties_examples/client.properties.fds 给定源小米生态云的Object列表, 配置源端和目的端ak/sk 等信息
从BOS迁移到BOS properties_examples/client.properties.bos 给定源BOS的Object列表, 配置源端和目的端ak/sk等信息
从BOS到BOS的check校验 properties_examples/client.properties.bos-check 给定源BOS的Object列表和相关信息, 校验目的端是否和源端匹配

参数说明

  • serverThreadNumber:此配置项设置单个请求发送到server后, server使用多少个线程来处理该请求, 在源端和目
    的端以及server资源条件允许的情况下, 一般以打满server带宽为标准来设置该数值, 需要
    调整几次. server占用内存 = serverThreadNumber blockSize maxConnectionsPerServer

  • serverList:迁移server列表,每个server由ip和端口号组成, server之间使用;进行分隔,举例如下:

    serverList=192.168.1.1 8090;192.168.1.2 8090

    serverList 这个选项可以置空,置空没有可用的迁移server, 迁移会暂停。

  • filesPerRequest:每次请求分发到迁移server的文件数量。建议该值配置完后每次迁移请求的完成时间大于30秒。 因为一次请求使用一个tcp连接,需要保证在下个请求开始时上一次tcp连接可以正常断开, 避免tcp fd过多, 可以在开始迁移时尝试由小到大增大这个值, 直到每次迁移请求完成时间大于30秒为止。

  • taskList:任务列表(绝对路径)。taskList包含了一个或多个迁移任务列表(文件的绝对路径), 这些任务列表是预先处理好的,每个文件的行数就是任务的粒度, 粒度越小越利于在任务进度恢复的时候减少重复的迁移工作。

    示例:

    /home/work/list/object_list1.txt
    /home/work/list/object_list2.txt
    #/home/work/list/object_list2.txt
    

    以上taskList内容表示有3个文件列表。当以#开头时表示该行被注释掉, 不会被当做迁移任务处理。

  • listDelimiterlistFormat

    文件列表格式对应配置文件中的properties名称,字段值大小写敏感。listDelimiter表示文件列表中每行数据的每一列之间的分隔符,listFormat表示文件列表中每一行应该包括哪几列,列名以;分割。

    listDelimiter=" "
    listFormat=bucketName;objectName;dstObjectName
    

    文件列表内容示例

    bucketA    prefixA/aaa/object1    prefixB/bbb/object1
    bucketA    prefixA/aaa/object2    prefixB/bbb/object2
    #bucketA prefixA/aaa/object3 prefixB/bbb/object3
    bucketA    prefixA/aaa/object4    prefixB/bbb/object4
    

    当以#开头时表示该行被注释掉, 不会被当做迁移任务处理。

    目前文件列表格式中支持的的各个fields包括:

    field 意义 示例
    srcAk 源端ak
    srcSk 源端sk
    dstAk 目的端(bos)ak
    dstSk 目的端(bos)sk
    srcBucketName 源端bucket名称
    srcObjectName 源端object名
    bucketName 源端bucket名称
    objectName 源端object名
    dstBucketName 目的端bucket名称
    dstObjectName 迁移之后的名称, 可以通过这一项来实现改名
    contentType 如果源端没有, 迁移之后存放到bos的contentType text/plain
    contentDisposition 如果源端没有, 迁移之后存放到bos的contentDisposition attachment; filename="abc.mp4"
    toBosIa 是否迁移到bos ia toBosIa

    srcBucketName/bucketName,srcObjectName/objectName都是或的关系,两者取其一,优先取srcBucketName/srcObjectName

  • migrationStrategy:迁移策略

    1. FORCE_OVERWRITE: 强制覆盖目的端文件, 可能会破坏目的端文件, 危险, 慎用, 在确定需求的前提下使用
    2. KEEP_DESTITNATION: 如果目的端有同名文件文件存在则跳过
    3. KEEP_NEWER: 如果目的端有同名文件存在, 且新于源端文件, 则跳过, 否则覆盖之;如果目的端没有"同名"文件(有可能迁移时文件需要改名)存在, 则按照迁移规则直接复制到目的端
    • KEEP_DESTITNATIONKEEP_NEWER 这两个迁移策略比较适合用于业务平稳切换时, 在源端和目的端进行双写时使用, 两者的效率相当, 根据具体需求确定使用。
    • 迁移策略设置成三种策略之外的未知策略,会默认设置成KEEP_DESTINATION。
  • headQpsputQpsbandwidth:QPS和带宽限速

    1. headQps表示从数据源迁移到BOS或者与BOS数据check对比时getObjectMeta请求的QPS上限,最大不超过5000次/秒;
    2. putQps表示从数据源迁移到BOS时putObject请求的QPS上限,最大不超过1500次/秒;
    3. bandwidth表示从数据源迁移到BOS时putObject请求的带宽上限,最大不超过3000MBps。
    headQps=5000
    putQps=1500
    bandwidth=3000
    

日志

  1. src_not_found.log

    源端未找到, 在尝试迁移所给的文件列表中的文件时, 发现源文件找不到。

    示例

    2015-12-31 17:13:48.014 bucket1 obj24
    2015-12-31 17:13:48.015 bucket1 obj25
    2015-12-31 17:13:48.016 bucket1 obj26
    
  2. migrate_failed.log

    迁移过程发生异常(包括迁移过程中写目的端中途失败,迁移后校验时发现读目的端文件信息异常或者目的端和源端不一致等情况),发生概率低,需要以FORCE_OVERWRITE策略重做。

    示例

    2015-12-31 17:13:48.014 bucket1 obj24
    2015-12-31 17:13:48.015 bucket1 obj25
    2015-12-31 17:13:48.016 bucket1 obj26
    
  3. redo_list.log

    迁移任务失败(包括迁移过程中读取源端文件数据或信息异常,迁移后校验时发现目的端文件不存在等情况),需要重做。

    示例

    2015-12-31 17:13:48.014 bucket1 obj24
    2015-12-31 17:13:48.015 bucket1 obj25
    2015-12-31 17:13:48.016 bucket1 obj26
    
  4. dst_not_match.log

    只有check任务会生成, 表示目的端和源端不一致, 只用来迁移则无需理会。

    示例

    2015-12-31 17:13:48.014 bucket1 obj24
    2015-12-31 17:13:48.015 bucket1 obj25
    2015-12-31 17:13:48.016 bucket1 obj26
    
  5. status.log

    当前进度, 每3秒更新一次, x/y 表示处理进度, x为已经处理的数量, y表示总量;y为-1表示未读完该文件列表, 完成迁移的列表后会标记一个finished

    示例:

    2015-12-31 17:13:42.013 object_list1.txt 2/2 finished
    2015-12-31 17:13:45.014 object_list2.txt 3/-1
    2015-12-31 17:13:48.014 object_list3.txt 4/6
    
  6. unsent.log

    由于网络或者server不可用等问题在发送迁移请求给server时报错, 告知有哪些文件在尝试迁移的时候server拒绝了。

    示例

    2015-12-31 17:13:48.014 bucket1 obj24
    2015-12-31 17:13:48.015 bucket1 obj25
    2015-12-31 17:13:48.016 bucket1 obj26
    
  1. client.log

    client端日志, 记录着各个迁移任务分发的情况以及当前client的情况, 可以从这个日志中分析出文件的平均大小, 和单个文件迁移所用时间, 从而调整迁移参数, 实现高效迁移。

  2. server.log

    迁移server端日志, 主要包含文件迁移的过程(head get put verify), 根据request-id可以跟踪某个迁移任务的处理过程。

第1-6种log的格式除了每行开头加上了产生该行的时间之外, 和所提供的文件列表格式一样。

任务进度恢复

status.log 里可以看到相应的文件列表具体的迁移进度, 如果client崩溃了可以从日志中找到相应的断点恢复迁移, 进度恢复是根据任务列表(list)的粒度来进行的。

示例:

client.properties

taskList=/path/to/task_list.txt

task_list.txt 内容如下

/home/work/list/object_list1.txt
/home/work/list/object_list2.txt
#/home/work/list/object_list2.txt

object_list1.txt 内容如下

bucket1 obj1
bucket1 obj2
bucket1 obj3
#bucket1 obj4
bucket1 obj5

object_list2.txt 内容如下

bucket1 obj21
#bucket1 obj22
bucket1 obj23
bucket1 obj24
bucket1 obj25
bucket1 obj26

status.log 内容如下

2015-12-31 17:13:42.013 object_list1.txt 2/-1
2015-12-31 17:13:45.014 object_list2.txt 3/-1
2015-12-31 17:13:48.014 object_list2.txt 4/6
2015-12-31 17:13:51.014 object_list1.txt 5/5 finished
2015-12-31 17:13:53.014 object_list2.txt 4/6

object_list1.txt 2/-1 表示已经处理完了 object_list1.txt 这个列表的第2行,-1 表示这个文件还没有读完不知道有多少行, 如果这个时候崩溃了, 由于采用了并发,所以并不知道具体是完成了列表中的哪几个文件的迁移。

从某个进度重新开始任务, 需要建立新的list文件, 如本例中object_list1_continue.txtobject_list2_continue.txt,然后将恢复进度的
list文件列表放在新的task_list里, 参考本例中 task_list_continue.txt

恢复进度重新启动任务的配置如下:

在client.properties中的

taskList=task_list_continue.txt

其中task_list_continue.txt 内容如下

object_list1_continue.txt
object_list2_continue.txt

使用新的配置重新启动client就可以了。

redo重传

当所有需要迁移的列表处理完之后, 需要对迁移失败或者迁移过程当中出现问题的文件进行重传。 从迁移日志中整理出重传的列表: redo, unsent部分使用正常迁移的迁移策略,但是对于failed的文件列表, 需要考虑使用FORCE_OVERWRITE策略进行迁移, 因为可能是因为迁移出现了数据错误。

异常处理

server异常处理

  • 多步上传到BOS异常

    上传到BOS的multiupload在完成最后一个part的时候会调用 finishUpload,由于是多线程, 同个文件的多个part可能在最后一part完成之前未完成, 在调用finishUpload 的时候可能会失败, 处理这个问题的策略是:重试5次, 每次间隔20秒,重试5次失败后abort掉之前已经完成的part。

    建议:当出现5次重试依旧失败的情况,可以把blockSize尽量调大,使得part总数较少。

client 异常处理

  • 当server不可用时, client在第一次尝试将迁移请求发送给该server时可以立即发现其不可用, 将该请求记录为unsent, 并标记该server不可用, 之后的请求不会再发往该server。如果确定该server修复之后, 可以touch一下client的配置文件client.properties, 触发client配置重新加载;建议设置一个crontab定时去touch配置文件client.properties。

  • client达到系统分配的fd(socket fd)数量极限,检查是否filesPerrequet是否过小, 如果确定是这个原因, 则需要适当调大, 杀掉所有server(或者让client于所有server"失联"), 等待已经占有的大部分socket fd释放之后重新touch client的配置文件。

版本记录

  • BosImport工具包 [2018-12-05] 版本号1.0.0

    • 支持多种迁移方式, 支持迁移不同的源端到目的端,目前支持AWS S3、阿里云OOS、腾讯云COS、七牛、小米生态云、BOS等;
    • 支持实时迁移并发度/压力调节,server"热升级";支持迁移任务热启停,迁移进度实时显示;
    • 大文件切块传输, 块大小支持实时配置, 最大效率地利用迁移机器的带宽资源;
    • 负载均衡, client会选择没有压力的server进行迁移任务;
    • 支持自定义迁移的任务列表和文件数目;支持迁移任务QPS和流量限速;支持多种迁移策略。