KS3Up-tool数据迁移工具说明

---

一．主要特性

• 支持将本地目录内文件、url列表文件或公有云文件同步到指定KS3 Bucket上，目前支持将金山云KS3、阿里云OSS、腾讯云COS、百度云、七牛云和 AWS S3 设置为迁移源
• 支持增量上传：a. 不在成功列表中；b. 在成功列表中，但最后更新时间不同
• 支持大文件断点续传
• 支持流量控制
• 并发上传
• 迁移进度查询
• 海量文件迁移，部分失败情况，重新全量上传即可，已经成功上传的文件会自动跳过（勿删除log）
• 支持选择存储类型，标准或低频 工具下载地址: http://ks3-tools.ks3-cn-beijing.ksyun.com/ks3up-tool-2.0.12.zip

二．运行环境

用户系统需要具备jdk 1.6/1.7/1.8 环境，建议使用Oracle版本JDK

Windows安装jdk1.7

方法参考

http://jingyan.baidu.com/article/b24f6c82c989da86bfe5dab2.html

安装完成后，在命令提示符下，执行java –version，来确认是否安装成功

如下所示，即安装成功

Linux安装jdk1.7

方法参考

http://www.cnblogs.com/wuqianling/p/5381895.html

安装完成后，在终端下执行java –version，来确认是否安装成功

如下所示，即安装成功

三．使用方式

假设work_dir=/your_dir/ 配置文件中请填写绝对路径

1.解压文件

unzip ks3up-tool-XXXXXXXX.zip -d ${work_dir}

2.填写配置文件xxx.conf

根据${work_dir}下解压后的sample.conf，创建用户自己新的任务配置文件xxx.conf, 所有的配置参数项前后都不允许有空格 配置文件中，字段具体含义如下

字段	说明	是否必填
srcType	同步源类型，不能为空 (1) 目前只支持选项：local/url/ks3/oss/cos/bos/qiniu/aws	是
srcAccessKey	数据源的AccessKey (1) 如果srcType是local或url，则忽略此选项	否
srcSecretKey	数据源的SecretKey (1) 如果srcType是local或url，则忽略此选项	否
srcDomain	数据源bucket所在区域对应域名，不同区域对应的域名不同。 (1) 请参照https://docs.ksyun.com/directories/1782 (1) 如果srcType是local，则忽略此选项	否
srcBucket	源bucket (1) 如果srcType是local，则忽略此选项	否
srcPrefix	源前缀 (1) 如果srcType=local，则填写本地待同步目录或文件，请注意您需要填写完整的目录或文件路径(linux下路径分隔符为“/”, win下路径分隔符为“/”或“\\”)，路径不能有中文字符 (2) 如果srcPrefix指定的是一个文件，则上传后的objectKey是dstPrefix + “/” + absoluteFileName (3)如果srcType=url，则填写url列表的绝对路径，url列表应当为一个文本文件，并逐行列出需要上传的url地址(支持http和https协议)	否
dstAccessKey	KS3 AccessKey	是
dstSecretKey	KS3 SecretKey	是
dstDomain	bucket所在区域对应域名，不同区域对应的域名不同。 (1) 请参照https://docs.ksyun.com/documents/6761	是
dstBucket	KS3 bucket名称	是
dstPrefix	上传到KS3上时需要添加的前缀名(目录)，当数据源是某个本地目录或公有云目录时，此处须填写与“srcPrefix”完全相同的目录名称，以确保迁移前后文件目录结构不变	否
maxNetThroughput	单位为KB/s，<=0 表示不设限。例：如果限速为10Mb/s，则对应的以MB为单位的限速是10*0.128MB/s=1.28MB/s,对应的maxNetThroughput=1280KB/s	是
threadsNum	并发上传的线程数 (1) 配置的数目不能<=0 (2) 根据实际情况填写,更大的值可能会需要更大的运行内存,并且需要调整java运行的参数	是
cannedAcl	文件权限配置 (1)可选项private/publicread (2) private私密 (3)publicread公开	是
storageType	选择上传文件存储类型 (1)可选项STANDARD/STANDARD_IA (2) STANDARD标准 (3)STANDARD_IA低频	是
filterEnable	过滤器开关 true-打开 false-关闭；过滤器可根据文件名和文件修改时间过滤文件	否
urlRangeDownload	url文件是否使用range下载 true-打开 false-关闭	否
fileNameInclude	文件名称白名单，多个用英文逗号分隔 "filterEnable=true"时配置有效	否
fileNameExclude	文件名称黑名单，多个用英文逗号分隔，可用于过滤前缀相同的文件 "filterEnable=true"时配置有效	否
modifyTimeRange	文件修改时间范围,以#分割，时间格式为yyyy-MM-dd HH:mm:ss，如2005-01-12 00:00:00#2016-01-12 00:00:00 1、不限制开始时间#2016-01-12 00:00:00 2、不限制结束时间2005-01-12 00:00:00# 3、"filterEnable=true"时配置有效	否
singleFileSize	分块上传文件大小阈值，大于该值使用分块上传 ，单位为Byte	否
partSize	分块上传块大小 ，单位为Byte	否
uploadPartPoolSize	单文件分块传输并发数	否

3.执行选项

(1) 启动任务

java -jar ks3up-1.0.0.jar -c xxx.conf start

注意：xxx.conf 配置文件如果不和ks3up-1.0.0.jar在同一个目录下，-c 需要指明配置文件的正确路径。

linux环境下如果想要后台执行，则用如下命令：

nohup java -jar ks3up-1.0.0.jar -c xxx.conf start > nohup.out 2>&1 &

注意：srcBucket, srcPrefix, dstBucket, dstPrefix确定任务的唯一性

(2) 查询任务状态

java -jar ks3up-1.0.0.jar -c xxx.conf stat

(3) 清空任务数据

java -jar ks3up-1.0.0.jar -c xxx.conf clean

注意:

• 若任务正在运行，则不能清空
• 若任务未曾运行过，则会提示任务不存在
• 使用增量上传功能，需保留任务数据

(4) 导出成功文件列表

 java -jar ks3up-1.0.0.jar -c xxx.conf export_ok_list ${export_file}

注意：只有任务退出，该操作才允许被执行

(5) 导出失败文件列表

 java -jar ks3up-1.0.0.jar -c xxx.conf export_fail_list ${export_file}

注意：只有任务退出，该操作才允许被执行

(6) 增量上传 以及 失败重传

等待当前任务退出后，重新执行“启动任务”的命令，要注意，任务的配置文件不要做修改

 java -jar ks3up-1.0.0.jar -c xxx.conf start

注意事项：

1. 执行选项start持续运行，所需最小内存为100MB

4.日志和运行情况

会在${work_dir}下创建logs目录,执行情况可关注statistic.log,如有问题请将info.log,warn.log,error.log发给ks3售前(后)咨询

5.本地目录上传示例

srcType=local

srcPrefix=/dir1/dir2/

dstAccessKey=your_ak

dstSecretKey=your_sk

dstDomain=ks3.ksyun.com

dstBucket=your_bucket

dstPrefix=leve1/level2/

如上所示配置文件，则本地文件/dir1/dir2/dir3/a.txt ，上传完毕后存在ks3的位置是level1/level2/dir3/a.txt

6.url列表上传示例

srcType=url

srcPrefix=/dir/urlList.txt

dstAccessKey=your_ak

dstSecretKey=your_sk

dstDomain=ks3.ksyun.com

dstBucket=your_bucket

dstPrefix=leve1/level2/

urlRangeDownload=true

如上所示配置文件，则当srcType=url时，要确保url对应的文件是公开可读的，srcPrefix填写url列表文件的路径，urlRangeDownload设置是否采用range下载url文件

四．常见问题与注意事项

1. 检查目标空间是否存在，dstDomain设置和目标空间对应关系是否正确
2. 检查dstAccessKey和dstSecretKey是否正确
3. 在windows环境下，srcPrefix目录分隔符用"/"或"\\"，不能用"\"
4. 上传时设置 filterEnable=true fileNameExclude=$ 可满足不上传前缀为$的文件，排除其他格式前缀文件同理。
5. 每上传一个文件，都会在工具目录下生成一个后缀为.db的文件，记录上传信息。如果要重复上传此文件（文件最后修改时间都没有变），将会提示already uploaded错误信息，删除对应的.db文件后，可正常上传。建议这种情况下，用户使用SDK或者KS3Util进行覆盖上传。