ossimport概述

更新时间:

ossimport是一款将数据迁移至OSS的工具。您可以将ossimport部署在本地服务器或云上ECS实例内,将您本地或其他云存储的数据迁移到OSS,同时,阿里云还为您提供标准化的在线迁移服务跨区域复制服务,帮助您白屏化实现存储数据上云与OSS之间的数据复制能力。

重要
  • ossimport不对迁移文件进行校验,无法保证迁移结果的正确性和一致性。在迁移任务完成后,请您务必自行做好源端和目的端数据的一致性校验。

    如您在未校验源端和目的端数据一致性前,删除源数据,由此所引起的一切损失和后果均由您自行承担。更多信息,请参见闪电立方服务协议

  • 如果您需要迁移其他第三方数据源,推荐使用在线迁移服务迁移您的数据。

  • 如果您需要在两个不同的Bucket中进行OSS数据的近实时复制,推荐使用OSS跨区域复制功能。

支持特性

  • 支持丰富的数据源,包括本地文件、七牛云Kodo、百度BOS、Amazon S3、Azure Blob、又拍云USS、腾讯云COS、金山KS3、HTTP或HTTPS URL列表、阿里云OSS等,并可根据需要扩展。

  • 支持单机模式和分布式模式。单机模式部署简单,使用方便,分布式模式适合大规模数据迁移。

    说明

    单机模式下一次只能迁移一个Bucket。

  • 支持断点续传。

  • 支持流量控制。

  • 支持迁移指定时间以后的文件、特定前缀的文件。

  • 支持并发数据下载和上传。

计费说明

ossimport工具本身不收费。在公有云情况下,数据源可能会产生公网流出流量、请求等费用,目的端为OSS会产生请求费用等。如果OSS开通和使用了传输加速,还会产生传输加速的费用。

注意事项

  • 迁移速度

    ossimport迁移速度取决于源端的读取带宽、本地网络带宽、文件大小等因素。对于小于200 KB文件的迁移,因IOPS使用率高的原因,可能会导致迁移较慢的问题。

  • 源端数据为归档类型

    通过ossimport迁移数据时,如果源端数据为归档类型,您需要对这部分数据解冻完成后再进行迁移。

  • 本地中转

    通过ossimport迁移数据时,数据流会经过本地内存中转后再上传至目的端。

  • 保留源端数据

    通过ossimport迁移数据时,仅对源端数据执行读取操作,不对源端数据进行修改和删除。

  • 其他迁移工具(ossutil)

    对于迁移小于30 TB的数据,推荐使用ossutil。该工具简单方便,通过-u,--update--snapshot-path选项还可以实现文件的增量迁移,详细说明请参见cp

运行环境

ossimport可以部署在Linux或Windows系统上,要求如下:

  • Windows7及以上版本

  • CentOS 6或者CentOS 7

  • Java 7或者Java 8

重要

分布式部署暂时不支持Windows系统。

部署方式选择

ossimport有单机模式和分布式模式两种部署方式。

  • 单机模式:当您需要迁移的数据小于30 TB时,推荐部署单机模式。您可以将ossimport部署在任意一台可以访问您待迁移数据,且可以访问OSS的机器上。

  • 分布式模式:当您需要迁移的数据大于30 TB时,推荐部署分布式模式。您可以将ossimport部署在任意多台可以访问您待迁移数据,且可以访问OSS的机器上。

    说明

    当您待迁移的数据过大时,为了节约时间,您可以将ossimport部署到与您OSS相同地域的ECS实例上,并通过专线将源数据存放的服务器挂载到阿里云VPC网络中。多台ECS实例将数据通过内网迁移至OSS,会极大的提升数据迁移效率。

    您也可以使用ossimport通过公网传输,传输速度受您本地服务器的带宽影响。

单机模式

Master、Worker、Tracker、Console运行在一台机器上,统一打包成ossimport2.jar。系统中有且只有一个Worker。

单机模式下文件结构如下:

ossimport
├── bin
│ └── ossimport2.jar  # 包括Master、Worker、Tracker、Console四个模块的总jar
├── conf
│ ├── local_job.cfg   # 单机Job配置文件
│ └── sys.properties  # 系统运行参数配置文件
├── console.bat         # Windows命令行,可以分布执行调入任务
├── console.sh          # Linux命令行,可以分布执行调入任务
├── import.bat          # Windows一键导入,执行配置文件为conf/local_job.cfg配置的数据迁移任务,包括启动、迁移、校验、重试
├── import.sh           # Linux一键导入,执行配置文件为conf/local_job.cfg配置的数据迁移任务,包括启动、迁移、校验、重试
├── logs                # 日志目录
└── README.md           # 说明文档,强烈建议使用前仔细阅读
  • import.bat/import.sh为一键导入脚本,修改完local_job.cfg后可以直接运行。

  • console.bat/console.sh为命令行工具,可用于分布执行命令。

  • 脚本或命令请在ossimport目录下执行,即 *.bat/*.sh 的同级目录。

分布式模式

ossimport是基于master-worker的分布式架构,结构如下:

Master --------- Job --------- Console
    |
    |
   TaskTracker
    |_____________________
    |Task     | Task      | Task
    |         |           |
Worker      Worker      Worker

参数

说明

Master

负责将Job切分成Task,按照数据大小和文件个数分解成Task,数据大小/文件个数可以在sys.properties中配置。Job切分成Task的详细过程如下:

  1. Master从本地/其他云存储中遍历出完整的待迁移的文件列表。

  2. 按照数据大小和文件个数把完整的文件列表切分成Task,每个Task负责部分文件的迁移或校验。

Worker

  • 负责Task的文件迁移和数据校验,从数据源上拉取指定文件,并上传到OSS的指定目录。迁移的数据源和OSS的配置在job.cfg或local_job.cfg中指定。

  • Worker数据迁移支持限流、指定Task并发数,在sys.properties中配置。

TaskTracker

简称Tracker,负责Task的分发、Task状态跟踪。

Console

负责与用户交互,接受命令并显示结果。支持系统管理命令deploy/start/stop,Job管理命令 submit/retry/clean。

Job

用户提交的数据迁移任务,对用户来说一个任务对应一个配置文件job.cfg

Task

Job按照数据大小和文件个数可以分成多个Task ,每个Task 迁移部分文件。Job切分成Task的最小单位是文件,同一个文件不会切分到多个Task中。

分布式模式下可以启动多台机器执行数据迁移,每台机器上只能启动一个Worker。Task平均分配到Worker上执行,一个Worker执行多个Task。

分布式模式下文件结构如下:

ossimport
├── bin
│ ├── console.jar     # Console模块jar包
│ ├── master.jar      # Master模块jar包
│ ├── tracker.jar     # Tracker模块jar包
│ └── worker.jar      # Worker模块jar包
├── conf
│ ├── job.cfg         # Job配置文件模板
│ ├── sys.properties  # 系统运行参数配置文件
│ └── workers         # Worker列表
├── console.sh          # 命令行工具,目前支持只Linux
├── logs                # 日志目录
└── README.md           # 说明文档,强烈建议使用前仔细阅读

配置文件

单机模式下有两个配置文件sys.propertieslocal_job.cfg,分布式模式下有三个配置文件sys.propertiesjob.cfgworkers。其中local_job.cfgjob.cfg的配置项是完全一样的,只是名称不一样,workers是分布式环境特有的。

  • sys.properties:系统运行参数

    参数

    含义

    说明

    workingDir

    工作目录

    工具包解压后的目录。单机模式下请不要修改此参数,分布式模式下每个机器的工作目录必须相同。

    workerUser

    Worker机器的ssh用户名

    • 如果配置了privateKeyFile ,则优先使用privateKeyFile。

    • 如果没有配置privateKeyFile,则使用workerUser/workerPassword。

    • 单机模式不需要修改此参数。

    workerPassword

    Worker机器的ssh用户密码

    单机模式不需要修改此参数。

    privateKeyFile

    private key文件路径

    • 如果已经打通了ssh通道,则可以指定此参数,否则为空。

    • 如果配置了privateKeyFile,则优先使用privateKeyFile。

    • 如果没有配置privateKeyFile,则使用workerUser/workerPassword。

    • 单机模式不需要修改此参数。

    sshPort

    ssh端口

    默认22,一般情况无需更改。 单机模式不需要修改此参数。

    workerTaskThreadNum

    Worker执行Task的最大线程数

    • 该参数与机器的内存/网络有关,建议值60 。

    • 物理机可以适当加大,例如150 。如果网络带宽已占满,请不要再加大。

    • 如果网络较差,请适当降低,例如30。防止请求竞争网络造成大量请求超时。

    workerMaxThroughput(KB/s)

    worker数据迁移的流量上限

    该值能起到限流作用,默认0表示不限流。

    dispatcherThreadNum

    Tracker的Task分发与状态确认的线程数

    默认值一般够用,没有特殊需要请不要修改默认值。

    workerAbortWhenUncatchedException

    表示遇到未知错误时是跳过还是终止

    默认跳过。

    workerRecordMd5

    在OSS中是否使用元数据x-oss-meta-md5记录迁移文件的MD5值,默认不记录。

    主要用于用户使用MD5校验文件数据。

  • job.cfg:数据迁移任务配置,local_job.cfgjob.cfg的配置项是完全一样的,只是名称不一样。

    参数

    含义

    说明

    jobName

    任务名字,字符串。

    • 任务的唯一标识,命名规则 [a-zA-Z0-9_-]{4,128},支持提交多个名字不同的任务。

    • 如果重复提交同名任务会提示任务已存在,清理(clean)同名任务前, 无法提交同名任务。

    jobType

    任务类型,字符串

    • 默认为 import

    isIncremental

    是否打开增量迁移模式,布尔类型。

    • 默认值false。

    • 如果设为true,会每间隔incrementalModeInterval(单位秒)重新扫描一次增量数据,并将增量数据迁移到OSS。

    incrementalModeInterval

    增量模式下的同步间隔,整型,单位秒。

    isIncremental=true时有效。可配置的最小间隔为900秒,不建议配置成小于3600秒的值,会浪费大量请求,造成额外的系统开销。

    importSince

    迁移大于该时间的数据,整型,单位秒。

    • 该时间为 Unix时间戳,即自1970年1月1日UTC零点以来的秒数,通过命令date +%s获取。

    • 默认为0,表示迁移全部数据。

    srcType

    同步源类型,字符串, 请注意大小写。

    支持以下类型:

    • local:从本地文件迁移数据到OSS,该选项只需要填写srcPrefix, 不需要填写srcAccessKey,srcSecretKey,srcDomain,srcBucket。

    • oss:从一个 OSS bucket 迁移到另一个 bucket。

    • qiniu:从七牛云存储迁移到OSS。

    • bos:从百度的云存储迁移到OSS。

    • ks3:从金山云存储迁移到OSS。

    • s3:从 Amazon S3迁移到OSS。

    • youpai:从又拍云迁移到OSS。

    • http:通过提供的HTTP或者HTTPS链接列表迁移数据到OSS。

    • cos:从腾讯云存储COS迁移到OSS。

    • azure:从Azure Blob迁移到OSS。

    srcAccessKey

    源AccessKey,字符串。

    • 如果srcType设置为ossqiniubaiduks3s3,则填写数据源的AccessKey。

    • 如果srcType设置为localhttp,则该项不需要填写。

    • 如果srcType设置为youpaiazure,则填写用户名AccountName。

    srcSecretKey

    源SecretKey,字符串。

    • 如果srcType设置为ossqiniubaiduks3s3,则填写数据源的 SecretKey。

    • 如果srcType设置为localhttp,则该项不需要填写。

    • 如果srcType设置为youpai,则填写操作员密码。

    • 如果srcType设置为azure,则填写AccountKey。

    srcDomain

    源Endpoint

    • 如果srcType设置为localhttp,则该项不需要填写。

    • 如果srcType设置为oss,则填写从控制台获取的域名,非带bucket前缀的二级域名。

    • 如果srcType设置为qiniu,则填写从七牛控制台获取的对应bucket的域名。

    • 如果srcType设置为bos,则填写百度BOS域名,如http://bj.bcebos.comhttp://gz.bcebos.com

    • 如果srcType设置为ks3,则填写金山ks3域名,如http://kss.ksyun.comhttp://ks3-cn-beijing.ksyun.comhttp://ks3-us-west-1.ksyun.coms

    • 如果srcType设置为S3, 则填写Amazon S3各region的域名。

    • 如果srcType设置为youpai,则填写又拍云域名,如自动判断最优线路http://v0.api.upyun.com或电信网通线路http://v1.api.upyun.com或联通网通线路http://v2.api.upyun.com或移动铁通线路http://v3.api.upyun.com

    • 如果srcType设置为cos,则填写腾讯云bucket所在的区域,例如华南园区为ap-guangzhou。

    • 如果srcType设置为azure,则填写Azure Blob连接字符串中的EndpointSuffix ,如core.chinacloudapi.cn。

    srcBucket

    源bucket名字或container名称

    • 如果srcType设置为 localhttp,则不需要填写。

    • 如果srcType设置为azure,则填写container名称。

    • 其他填写bucket名称。

    srcPrefix

    源前缀,字符串,默认为空

    • 如果srcType设置为local,则填写本地目录,需要完整路径,以单个正斜线(/)进行分割并且以单个正斜线(/)结尾,仅支持如c:/example/ 或者/data/example/ 的格式。

      重要

      c:/example//或 /data//example/ 或 /data/example//是非法的。

    • 如果srcType设置为ossqiniubosks3youpais3,则填写待同步object的前缀,不包括bucket名称,如data/to/oss/

    • 如需同步所有文件,则srcPrefix设置为空 。

    destAccessKey

    目的AccessKey,字符串。

    访问OSS服务的AccessKey ID,请到阿里云控制台查看。

    destSecretKey

    目的SecretKey,字符串。

    访问OSS的AccessKey Secret,请到阿里云控制台查看。

    destDomain

    目的endpoint,字符串。

    阿里云控制台获取,非带bucket前缀的二级域名,列表请参见域名列表。

    destBucket

    目的bucket,字符串。

    OSS的bucket名称,不需要以/结尾。

    destPrefix

    目标前缀,字符串,默认为空。

    • 目标前缀,默认为空,直接放在目标bucket下。

    • 如果要将数据同步到oss的某个目录下,请以/结尾,如data/in/oss/

    • 注意oss不支持以/作为文件的开头,所以destPrefix请不要配置以/作为开头。

    • 一个本地文件路径为srcPrefix+relativePath的文件,迁移到oss的路径为destDomain/destBucket/destPrefix +relativePath

    • 一个云端文件路径为srcDomain/srcBucket/srcPrefix+relativePath的文件,迁移到oss的路径为destDomain/destBucket/destPrefix+relativePath

    srcSignatureVersion

    源端签名版本。

    仅适用于云盒。

    取值:oss_signature_v4,表示OSS V4签名。

    destSignatureVersion

    目的端签名版本。

    仅适用于云盒。

    取值:oss_signature_v4,表示OSS V4签名。

    srcRegion

    源端地域。

    仅适用于云盒。

    destRegion

    目的端地域。

    仅适用于云盒。

    srcCloudBoxId

    源端云盒ID。

    仅适用于云盒。

    destCloudBoxId

    目的端云盒ID。

    仅适用于云盒。

    taskObjectCountLimit

    每个Task最大的文件数,整型,默认10000。

    该配置项会影响到任务执行的并行度,一般配置为总文件数/Worker总数/迁移线程数(workerTaskThreadNum) ,最大值不要超过50000,如果不知道总文件数,请使用默认值。

    taskObjectSizeLimit

    每个Task最大数据量,整型,单位bytes,默认1GB。

    该配置项会影响到任务执行的并行度,一般配置为总数据量/Worker总数/迁移线程数(workerTaskThreadNum),如果不知道总数据量,请使用默认值。

    isSkipExistFile

    数据迁移时是否跳过已经存在的文件,布尔类型。

    当设置为true时,根据文件的size和LastModifiedTime判断是否跳过;为false时,总是覆盖OSS上已有文件。默认为值为false。

    scanThreadCount

    并行扫描文件的线程数,整型。

    • 默认值:1

    • 有效值:1-32

    该配置项与扫描文件的效率有关,没有特殊需求请不要修改。

    maxMultiThreadScanDepth

    最大允许并行扫描目录的深度,整型。

    • 默认值:1

    • 有效值:1-16

    • 默认值1表示在顶级目录间并行扫描。

    • 没有特殊需求不要修改,随意配置过大值会导致任务无法正常运行 。

    appId

    腾讯云COS的appId ,整型。

    srcType=cos时有效。

    httpListFilePath

    HTTP列表文件的绝对路径,字符串。

    • srcType=http时有效,源为HTTP链接地址时,需要提供内容为HTTP链接地址文件的绝对路径,如c:/example/http.list。

    • 该文件中的HTTP链接需要划分成两列,以一个或多个空格分开,分别代表前缀和上传到OSS后的相对路径。例如c:/example/http.list文件内容如:

      http://xxx.xxx.com/aa/  bb.jpg
      http://xxx.xxx.com/cc/  dd.jpg

      指定destPrefix为ee/,则迁移到OSS的文件名如下:

      ee/bb.jpg
      ee/dd.jpg
  • workers:分布式模式特有,每个IP一行。如:

    192.168.1.6
    192.168.1.7
    192.168.1.8
    • 上述配置情况下,第一行的192.168.1.6一定是 master ;即192.168.1.6上会同时启动Master 、 Worker、TaskTracker。Console也需要在该机上运行。

    • 多个Worker机器的用户名、登录方式、工作目录请确保相同。

配置文件示例

下表中是分布式部署下的数据迁移任务配置文件,单机的配置文件名是local_job.cfg,配置项与分布式部署时没有区别。

迁移类型

配置文件

说明

从本地迁移到OSS

job.cfg

srcPrefix是以正斜线(/)结尾的绝对路径,如D:/work/oss/data//home/user/work/oss/data/

从七牛云存储迁移到OSS

job.cfg

srcPrefix和destPrefix可以配置为空;如果不为空,请以正斜线(/)结尾,如 destPrefix=docs/

从百度bos迁移到OSS

job.cfg

srcPrefix和destPrefix可以配置为空;如果不为空,请以正斜线(/)结尾,如destPrefix=docs/

Amazon S3迁移到OSS

job.cfg

参见S3域名列表

从又拍云存储迁移到OSS

job.cfg

srcAccessKey/srcSecretKey填操作员账号及密码。

从腾讯cos迁移到OSS

job.cfg

srcDomain请按照V4版本填写,如srcDomain=sh。srcPrefix可以为空,当不为空时候,请以 / 开头和结尾,如srcPrefix=/docs/

从Azure blob迁移到OSS

job.cfg

srcAccessKey/srcSecretKey填写存储账号及密钥。srcDomain填连接字符串中的 EndpointSuffix,如core.chinacloudapi.cn

从OSS迁移到OSS

job.cfg

适用于不同区域之间、不同存储类型之间、不同前缀之间的数据迁移。推荐在ECS上部署,并使用带internal的域名,可以节省流量费用。

高级设置

  • 分时限流

    sys.properties中的workerMaxThroughput(KB/s)表示Worker流量的上限,如果业务需要限流,例如源端流控控制、网络限制等情况。该参数的值应该小于机器的最大网络流量,并根据业务需要评估。修改后需要重启服务才能生效。

    分布式部署情况下,需要修改每个Worker的$OSS_IMPORT_WORK_DIR/conf下的sys.properties,然后重启服务。

    要实现分时限流,可通过crontab定时修改sys.properties,然后重启服务生效。

  • 修改任务并发数

    • sys.properties中的workerTaskThreadNum表示Worker并发执行的任务数量,如果网络较差、并发大,会出现大量超时错误,此时应该修改此配置,降低并发量,并重启服务。

    • sys.properties中的workerMaxThroughput(KB/s)表示Worker流量的上限,如果业务需要限流,例如源端流控控制、网络限制等情况。该参数的值应该小于机器的最大网络流量,并根据业务需要评估。

    • job.cfg中的taskObjectCountLimit ,每个Task 最大的文件数,默认10000。该参数会影响Task的数量,数量过小无法实现有效的并发。

    • job.cfg中的taskObjectSizeLimit , 每个Task最大数据量,默认1GB。该参数会影响Task的数量,数量过小无法实现有效的并发。

      重要
      • 请在启动迁移任务前,完成各项参数配置。

      • sys.properties中的参数修改后,重启迁移服务器后才能生效。

      • job.cfg任务提交后,任务的配置参数无法更改。

  • 只校验不迁移数据

    ossimport支持只校验数据不迁移数据,设置任务配置文件job.cfglocal_job.cfg的配置项jobTypeaudit而不是import,其他配置与数据迁移相同。

  • 数据迁移增量模式

    数据迁移增量模式,是指数据迁移任务启动后,先进行一次全量迁移,每隔一段时间自动的进行增量数据迁移。第一次数据迁移任务为全量迁移,提交任务后立即启动;后面的增量数据迁移每隔一个周期启动一次。数据迁移增量模式适用于数据备份和数据同步。

    增量模式有两个配置项:

    • job.cfg中的isIncremental ,表示是否打开增量迁移模式, true表示打开增量模式,false表示关闭增量模式,默认关闭。

    • job.cfg中的incrementalModeInterval,表示增量模式下的同步间隔,即增量数据迁移的间隔周期,单位秒。isIncremental=true时有效。可配置的最小值为900秒 ,不建议配置成小于3600秒的值,会浪费大量请求,造成额外的系统开销。

  • 指定迁移文件的过滤条件

    迁移文件的过滤条件,即只迁移满足特定条件的文件。ossimport支持指定前缀和最后修改时间:

    • job.cfg中的srcPrefix,用来指定迁移文件的前缀,默认为空。

      • 如果srcType=local,则填写本地目录。填写时需要完整路径,以正斜线(/)进行分割并且以正斜线(/)结尾,如c:/example//data/example/

      • 如果srcTypeossqiniubosks3youpais3,则为待同步object的前缀,不包括bucket名称。如data/to/oss/。迁移所有文件时srcPrefix设置为空。

    • job.cfg中的importSince,用来指定迁移文件的最后修改时间,单位秒。importSince为Unix时间戳,即自1970年1月1日UTC零点以来的秒数,通过命令date +%s获取。默认值0,表示迁移全部数据。增量模式下只对第一次全量迁移有效,非增量模式对整个迁移任务有效。

      • 如果文件的LastModified TimeimportSince之前,文件不被迁移。

      • 如果文件的LastModified TimeimportSince之后,文件将被迁移。