ossimport概述
ossimport是一款将数据迁移至OSS的工具。您可以将ossimport部署在本地服务器或云上ECS实例内,将您本地或其他云存储的数据迁移到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的详细过程如下:
|
Worker |
|
TaskTracker | 简称Tracker,负责Task的分发、Task状态跟踪。 |
Console | 负责与用户交互,接受命令并显示结果。支持系统管理命令deploy/start/stop,Job管理命令 submit/retry/clean。 |
Job | 用户提交的数据迁移任务,对用户来说一个任务对应一个配置文件 |
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.properties、local_job.cfg,分布式模式下有三个配置文件sys.properties、job.cfg、workers。其中local_job.cfg和job.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.cfg
和job.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设置为
oss
、qiniu
、baidu
、ks3
、s3
,则填写数据源的AccessKey。如果srcType设置为
local
、http
,则该项不需要填写。如果srcType设置为
youpai
、azure
,则填写用户名AccountName。
srcSecretKey
源SecretKey,字符串。
如果srcType设置为
oss
、qiniu
、baidu
、ks3
、s3
,则填写数据源的 SecretKey。如果srcType设置为
local
、http
,则该项不需要填写。如果srcType设置为
youpai
,则填写操作员密码。如果srcType设置为
azure
,则填写AccountKey。
srcDomain
源Endpoint
如果srcType设置为
local
、http
,则该项不需要填写。如果srcType设置为
oss
,则填写从控制台获取的域名,非带bucket前缀的二级域名。如果srcType设置为
qiniu
,则填写从七牛控制台获取的对应bucket的域名。如果srcType设置为bos,则填写百度BOS域名,如
http://bj.bcebos.com
或http://gz.bcebos.com
。如果srcType设置为ks3,则填写金山ks3域名,如
http://kss.ksyun.com
或http://ks3-cn-beijing.ksyun.com
或http://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设置为
local
、http
,则不需要填写。如果srcType设置为
azure
,则填写container名称。其他填写bucket名称。
srcPrefix
源前缀,字符串,默认为空
如果srcType设置为local,则填写本地目录,需要完整路径,以单个正斜线(/)进行分割并且以单个正斜线(/)结尾,仅支持如
c:/example/
或者/data/example/
的格式。重要c:/example//或 /data//example/ 或 /data/example//是非法的。
如果srcType设置为
oss
、qiniu
、bos
、ks3
、youpai
、s3
,则填写待同步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 | srcPrefix是以正斜线(/)结尾的绝对路径,如 | |
从七牛云存储迁移到OSS | srcPrefix和destPrefix可以配置为空;如果不为空,请以正斜线(/)结尾,如 | |
从百度bos迁移到OSS | srcPrefix和destPrefix可以配置为空;如果不为空,请以正斜线(/)结尾,如 | |
从Amazon S3迁移到OSS | 参见S3域名列表。 | |
从又拍云存储迁移到OSS | srcAccessKey/srcSecretKey填操作员账号及密码。 | |
从腾讯cos迁移到OSS | srcDomain请按照V4版本填写,如 | |
从Azure blob迁移到OSS | srcAccessKey/srcSecretKey填写存储账号及密钥。srcDomain填连接字符串中的 EndpointSuffix,如 | |
从OSS迁移到OSS | 适用于不同区域之间、不同存储类型之间、不同前缀之间的数据迁移。推荐在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.cfg或local_job.cfg的配置项jobType为audit而不是import,其他配置与数据迁移相同。
数据迁移增量模式
数据迁移增量模式,是指数据迁移任务启动后,先进行一次全量迁移,每隔一段时间自动的进行增量数据迁移。第一次数据迁移任务为全量迁移,提交任务后立即启动;后面的增量数据迁移每隔一个周期启动一次。数据迁移增量模式适用于数据备份和数据同步。
增量模式有两个配置项:
job.cfg中的isIncremental ,表示是否打开增量迁移模式, true表示打开增量模式,false表示关闭增量模式,默认关闭。
job.cfg中的incrementalModeInterval,表示增量模式下的同步间隔,即增量数据迁移的间隔周期,单位秒。
isIncremental=true
时有效。可配置的最小值为900秒
,不建议配置成小于3600
秒的值,会浪费大量请求,造成额外的系统开销。
指定迁移文件的过滤条件
迁移文件的过滤条件,即只迁移满足特定条件的文件。ossimport支持指定前缀和最后修改时间:
job.cfg中的srcPrefix,用来指定迁移文件的前缀,默认为空。
如果
srcType=local
,则填写本地目录。填写时需要完整路径,以正斜线(/)进行分割并且以正斜线(/)结尾,如c:/example/
或/data/example/
。如果
srcType
为oss
、qiniu
、bos
、ks3
、youpai
、s3
,则为待同步object的前缀,不包括bucket名称。如data/to/oss/
。迁移所有文件时srcPrefix
设置为空。
job.cfg中的importSince,用来指定迁移文件的最后修改时间,单位秒。importSince为Unix时间戳,即自1970年1月1日UTC零点以来的秒数,通过命令date +%s获取。默认值0,表示迁移全部数据。增量模式下只对第一次全量迁移有效,非增量模式对整个迁移任务有效。
如果文件的
LastModified Time
在importSince
之前,文件不被迁移。如果文件的
LastModified Time
在importSince
之后,文件将被迁移。