Skip to content
云存储数据导出及处理高效率并发框架与工具(jdk 8)https://search.maven.org/search?q=a:qsuits
Java
Branch: master
Clone or download

README.md

Maven Central License

qiniu-suits (qsuits)

云存储 API (base-qiniu) tool(工具方式推荐使用命令行执行器 qsuits),通过设计并优化的算法 能够高效并发列举云存储空间的大量资源列表(支持阿里云/腾讯云/七牛云/AWS/又拍云/华为云/百度云等),同时支持对 LocalFile 中的资源列表并发进 行批量处理,主要包括对七牛云存储资源进行增/删/改/查/迁移/转码/内容审核等。基于 Java8 编写,可基于 JDK 环境在命令行或 IDE 中运行。

高级功能列表(所有操作均支持批量并发处理):

【部分 process 属于危险操作,需要在启动后根据提示输入 y/yes 确认,如果不想进行 verify 验证则在命令行加入 -f 参数】

1 程序运行过程

账号设置(7.73 及以上版本)

预先设置好账号的密钥,在后续执行中只需使用 account name 即可读取对应密钥进行操作,定义不同的 account name 则可设置多对密钥,亦可设置不同数据源 的账号密钥,账号名相同时会覆盖该账号的历史密钥,操作如下:
设置 account:

-account=<source>-<name> -<source>-id= -<source>-secret= [-d]

-account=test/qiniu-test -ak= -sk= 设置七牛账号,账号名为 test,没有数据源标识时默认设置七牛账号
-account=ten-test -ten-id= -ten-secret= 设置腾讯云账号,账号名为 test
-account=ali-test -ali-id= -ali-secret= 设置阿里云账号,账号名为 test
-account=s3-test -s3-id= -s3-secret= 设置 S3 账号,账号名为 test
-account=up-test -up-id= -up-secret= 设置又拍云账号,账号名为 test
-account=hua-test -hua-id= -hua-secret= 设置华为云账号,账号名为 test
-account=bai-test -bai-id= -bai-secret= 设置百度云账号,账号名为 test
-d 表示默认账号选项,此时设置的账号将会成为全局默认账号,执行操作时 -d 选项将调取该默认账号
使用 account 账号:
-a=test 表示使用 test 账号,数据源会自动根据 path 参数判断
-d 表示使用默认的账号,数据源会自动根据 path 参数判断

(1)批处理模式

[读取数据源] => [选择过滤器] => [数据源结果持久化] => [数据处理过程]

(2)交互模式

从命令行输入数据时,process 支持交互模式运行:一次启动,可无限次命令行输入 data,输入一次处理一次并返回结果。

(3)单行模式

从命令行输入数据时,process 支持单行模式运行:一次启动,指定 data 参数,直接一次处理并返回结果。

2 运行方式

qsuits 提供命令行运行工具(或可执行 jar 包)和 maven artifact,使用时建议直接使用最新版本或者更新到最新版本。如下的 x.xx 替换成版本号,最新版 本见 Release

1. 命令行直接运行 jar 包

Release 页面下载最新 jar 包(maven 仓库中的 <version>.jar 包 不支持命令行运行,请下载 <version>-jar-with-dependencies.jar 包),使用命令行参数 [-config=] 指定 配置文件路径,运行命令形如:

java -jar qsuits-x.x.jar -config=config.txt

配置文件中可设置形如<属性名>=<属性值>,每行一个参数:

source=qiniu
bucket=
ak=
sk=

备注1:可以通过默认路径的配置文件来设置参数值,默认配置文件路径为 resources/application.configresources/application.properties, properties 方式需要遵循 java 的转义规则,两个文件存在任意一个均可作为默认配置文件来设置参数(优先使用 resources/application.properties), 此时则不需要通过 -config= 指定配置文件路径,指定 -config= 时则默认文件路径无效。
备注2:直接使用命令行传入参数(较繁琐),不使用配置文件的情况下全部所需参数可以完全从命令行指定,形式为:-<key>=<value>请务必在参 数前加上 -,如果参数值中间包含空格,请使用 -<key>="<value>" 或者 -<key>='<value>'

java -jar qsuits-x.x.jar -path=qiniu://<bucket> -ak=<ak> -sk=<sk>

备注2:7.72 及以下版本中命令行参数与配置文件参数不可同时使用,指定 -config= 或使用默认配置配置文件路径时,需要将所有参数设置在配置文件 中,而在 7.73 开始的版本中命令行参数与配置文件参数可同时使用,参数名相同时命令行参数值会覆盖配置文件参数值,且为默认原则。

2. 命令行执行器 qsuits(by golang)

由于 qsuits-java 基于 java 编写,命令行运行时需要提供 java -jar 命令,为了简化操作运行方式及增加环境和版本管理,提供直接的二进制可执行文件用 来代理 qsuits-java 的功能,即 qsuits 执行器(基于 golang 编写和编译):

操作系统 程序名 地址
windows 32 位 qsuits_windows_386.exe 下载
windows 64 位 qsuits_windows_amd64.exe 下载
linux 32 位 qsuits_linux_386 下载
linux 64 位 qsuits_linux_amd64 下载
mac 32 位 qsuits_darwin_386 下载
mac 64 位 qsuits_darwin_amd64 下载

下载执行器后可直接以 qsuits <parameters> 方式运行,支持所有 qsuits-java 提供的处理参数,且用法一致。如:

qsuits -config=config.txt

qsuits -path=qiniu://<bucket> -ak=<ak> -sk=<sk>

注意:qsuits 执行器依然依赖 java 环境(8 或以上),但是执行器会去检测本地 java 环境,在无匹配的 java 环境时会提示推荐的安装方法。并且该执行 器在运行时默认会选择最新的 qsuits-java 版本,其他选项参考 qsuits-exec-go 的文档:https://github.com/NigelWu95/qsuits-exec-go

3. 程序依赖 jar

引入 jar 包(下载 jar 包或者 使用 maven 仓库), 可以重写或新增 processor 接口实现类进行自定义功能,maven:

<dependency>
  <groupId>com.qiniu</groupId>
  <artifactId>qsuits</artifactId>
  <version>x.xx</version>
</dependency>

3 数据源

数据源分为两种类型:云存储列举(storage)、文本文件行读取(file),可以通过 **path= 来指定数据源地址:
path=qiniu://<bucket> 表示从七牛存储空间列举出资源列表,参考七牛数据源示例
path=tencent://<bucket> 表示从腾讯存储空间列举出资源列表,参考腾讯数据源示例
path=aliyun://<bucket> 表示从阿里存储空间列举出资源列表,参考阿里数据源示例
path=s3://<bucket> 表示从 aws/s3 存储空间列举出资源列表,参考S3数据源示例
path=upyun://<bucket> 表示从又拍云存储空间列举出资源列表,参考又拍数据源示例
path=huawei://<bucket> 表示从华为云存储空间列举出资源列表,参考华为数据源示例
path=baidu://<bucket> 表示从百度云存储空间列举出资源列表,参考百度数据源示例
path=<filepath> 表示从本地目录(或文件)中读取资源列表,参考本地文件数据源示例
未设置数据源时则默认从七牛空间进行列举,数据源详细参数配置和说明及可能涉及的高级用法见:数据源配置,配置文件示例可参考 配置模板

storage 云存储列举

支持从不同的云存储上列举出空间文件,默认线程数(threads 参数)为 50,千万以内文件数量通可以不增加线程,建议阅读并发列举 参考参数设置优化列举效率,通常云存储空间列举的必须参数包括密钥、空间名(通过 path 或 bucket 设置)及空间所在区域(通过 region 设置,允许不设置的情 况下表明支持自动查询):

storage 源 密钥和 region 字段 对应关系和描述
qiniu ak=
sk=
region=z0/z1/z2/...
密钥对为七牛云账号的 AccessKey 和 SecretKey
region使用简称(可不设置),参考七牛 Region
tencent ten-id=
ten-secret=
region=ap-beijing/...
密钥对为腾讯云账号的 SecretId 和 SecretKey
region使用简称(可不设置),参考腾讯 Region
aliyun ali-id=
ali-secret=
region=oss-cn-hangzhou/...
密钥对为阿里云账号的 AccessKeyId 和 AccessKeySecret
region使用简称(可不设置),参考阿里 Region
aws/s3 s3-id=
s3-secret=
region=ap-east-1/...
密钥对为 aws/s3 api 账号的 AccessKeyId 和 SecretKey
region使用简称(可不设置),参考AWS Region
upyun up-id=
up-secret=
密钥对为又拍云存储空间授权的操作员和其密码,又拍云存储目前没有 region 概念
huawei hua-id=
hua-secret=
region=cn-north-1/...
密钥对为华为云账号的 AccessKeyId 和 SecretAccessKey
region(可不设置)使用简称,参考华为 Endpoint
baidu bai-id=
bai-secret=
region=bj/gz/su...
密钥对为百度云账号的 AccessKeyId 和 SecretAccessKey
region(可不设置)使用简称,参考百度 Endpoint

file 文本文件行读取

文件内容为资源列表,可按行读取输入文件的内容获取资源列表,文件行解析参数如下:
parse=tab/json 表示输入行的格式
separator=\t 表示输入行的格式分隔符(非 json 时可能需要)
add-keyPrefix= 数据源中每一行的文件名添加前缀
rm-keyPrefix= 数据源中每一行的文件名去除前缀
line-config= 数据源路径即对应文本读取的起始行配置
数据源详细参数配置和说明及可能涉及的高级用法见:数据源配置

4 过滤器功能

从数据源输入的数据通常可能存在过滤需求,如过滤指定规则的文件名、过滤时间点或者过滤存储类型等,可通过配置选项设置一些过滤条件,目前支持两种过滤条件: 1.基本字段过滤和2.特殊特征匹配过滤

基本字段过滤

根据设置的字段条件进行筛选,多个条件时需同时满足才保留,若存在记录不包该字段信息时则正向规则下不保留,反正规则下保留,字段包含:
f-prefix= 表示选择文件名符合该前缀的文件
f-suffix= 表示选择文件名符合该后缀的文件
f-inner= 表示选择文件名包含该部分字符的文件
f-regex= 表示选择文件名符合该正则表达式的文件,所填内容必须为正则表达式
f-mime= 表示选择符合该 mime 类型的文件
f-type= 表示选择符合该存储类型的文件,参下述关于 f-type|
f-status= 表示选择符合该存储状态的文件, 为 0(启用) 或 1(禁用)
f-date-scale 设置过滤的时间范围,格式为 [<date1>,<date2>],<date> 格式为:2018-08-01 00:00:00,如 f-date-scale="[0,2018-08-01 12:30:00]" 特殊规则
f-anti-prefix= 表示排除文件名符合该前缀的文件
f-anti-suffix= 表示排除文件名符合该后缀的文件
f-anti-inner= 表示排除文件名包含该部分字符的文件
f-anti-regex= 表示排除文件名符合该正则表达式的文件,所填内容必须为正则表达式
f-anti-mime= 表示排除该 mime 类型的文件

关于 f-type

存储源 type 参数类型 具体值
七牛 整型 0 表示标准存储;1 表示低频存储
其他 字符串 如:Standard 表示标准存储

特殊字符

特殊字符包括: , \ = 如有参数值本身包含特殊字符需要进行转义:\, \\ \=

f-date-scale

<date> 中的 00:00:00 为默认值可省略,无起始时间则可填 [0,<date2>],结束时间支持 now 和 max,分别表示到当前时间为结束或无结束时间。由于 date 值日期和时刻中间含有空格分隔符,故在设置时需要使用引号 ' 或者 ",如 f-date-scale="[0,2018-08-01 12:30:00]"

特殊特征匹配过滤 f-check[-x]

根据资源的字段关系选择某个特征下的文件,目前支持 "ext-mime" 检查,程序内置的默认特征配置见:check 默认配置,运行 参数选项如下:
f-check=ext-mime 表示进行后缀名 extmimeType(即 content-type)匹配性检查,不符合规范的疑似异常文件将被筛选出来
f-check-config 自定义资源字段规范对应关系列表的配置文件,格式为 json,自定义规范配置 key 字段必填,其元素类型为列表 [], 否则无效,如 "ext-mime" 配置时后缀名和 mimeType 用 ":" 组合成字符串成为一组对应关系,写法如下:

{
  "ext-mime": [
    "mp5:video/mp5"
  ]
}

配置举例:check-config 配置
f-check-rewrite 是否覆盖默认的特征配置,为 false(默认)表示将自定义的规范对应关系列表和默认的列表进行叠加,否则程序内置的规范对应关系将失效, 只检查自定义的规范列表。
设置了过滤条件的情况下,后续的处理过程会选择满足过滤条件的记录来进行,或者对于数据源的输入进行过滤后的记录可以直接持久化保存结果,如通过 qiniu 源获 取文件列表过滤后进行保存,可设置 save-total=true/false 来选择是否将列举到的完整记录进行保存。
filter 详细配置可见filter 配置说明

5 处理过程

处理过程表示对由数据源输入的每一条记录进行处理,所有处理结果保存在 save-path 路径下,具体处理过程由处理类型参数指定,如 process=type/status /lifecycle/copy (命令行方式则指定为 -process=xxx) 等,同时 process 操作支持设置公共参数:
retry-times= 操作失败(可重试的异常情况下,如请求超时)需要进行的重试次数,默认为 5 次
batch-size= 支持 batch 操作时设置的一次批量操作的文件个数(支持 batch 操作:type/status/lifecycle/delete/copy/move/rename/stat, 其他操作请勿设置 batchSize 或者设置为 0),当响应结果较多 429/573 状态码时需要降低 batch-size,或者直接使用非 batch 方式:batch-size=0/1
处理操作类型:
process=type 表示修改空间资源的存储类型(低频/标准)type 配置
process=status 表示修改空间资源的状态(启用/禁用)status 配置
process=lifecycle 表示修改空间资源的生命周期 lifecycle 配置
process=delete 表示删除空间资源 delete 配置
process=copy 表示复制资源到指定空间 copy 配置
process=move 表示移动资源到指定空间 move 配置
process=rename 表示对指定空间的资源进行重命名 rename 配置
process=asyncfetch 表示异步抓取资源到指定空间 asyncfetch 配置
process=pfop 表示对空间资源执行 pfop 请求 pfop 配置
process=pfopresult 表示通过 persistentId 查询 pfop 的结果 pfopresult 配置
process=stat 表示查询空间资源的元信息 stat 配置
process=mirror 表示对设置了镜像源的空间资源进行镜像更新 mirror 配置
process=avinfo 表示查询空间资源的视频元信息 avinfo 配置
process=qhash 表示查询资源的 qhash qhash 配置
process=privateurl 表示对私有空间资源进行私有签名 privateurl 配置
process=pfopcmd 表示根据音视频资源的 avinfo 信息来生成转码指令 pfopcmd 配置
process=exportts 表示对 m3u8 的资源进行读取导出其中的 ts 文件列表 exportts 配置

6 结果持久化

对数据源输出(列举)结果进行持久化操作(目前支持写入到本地文件),持久化选项:
save-path= 表示保存结果的文件路径
save-format= 结果保存格式(json/tab),默认为 tab
save-separator= 结果保存分隔符,结合 save-format=tab 默认使用 "\t" 分隔
save-total= 是否保存数据源的完整输出结果,用于在设置过滤器的情况下选择是否保留原始数据,如 bucket 的 list 操作需要在列举出结果之后再针对字段 进行过滤,save-total=true 则表示保存列举出来的完整数据,而过滤的结果会单独保存,如果只需要过滤之后的数据,则设置 save-total=false。
默认情况:
(1)本地文件数据源时默认如果存在 process 或者 filter 则设置 save-total=false,反之则设置 save-total=true(说明可能是单纯格式转换)。
(2)云存储数据源时默认设置 save-total=true。
(3)保存结果的路径 默认(save-path)使用 (云存储数据源情况下)名称或者 -result 来创建目录
详细配置说明见 持久化配置
-- 持数据源久化结果的文件名为 "<source-name>_success_<order>.txt",例如:
(1)qiniu 存储数据源 =》 "qiniu_success_<order>.txt"
(2)local 列表数据源 =》 "local_success_<order>.txt"
如果设置了过滤选项或者处理过程,则过滤到的结果文件名为 "filter_success/error_<order>.txt",process 过程保存的结果为文件为 "<process>_success/error_<order>.txt"。
-- process 结果的文件名为:<process>_success/error_<order>.txt 及 <process>_need_retry_<order>.txt,error 的结果表明无法成功 处理,可能需要确认所有错误数据和原因,need_retry 的结果为需要重试的记录,包含错误信息。
-- rm-fields 可选择去除某些字段,未设置的情况下保留所有原始字段,数据源导出的每一行信息以目标格式保存在 save-path 的文件中。

7 超时设置

多数数据源或者操作涉及网络请求,因此提供超时时间设置,默认的超时时间一般能够满足要求,特殊需要的情况下可以修改各超时时间:
connect-timeout=60 网络连接超时时间,程序默认 60s
read-timeout=120 socket 读取超时时间,程序默认 120s
request-timeout=60 网络请求超时时间,程序默认 60s

8 错误及异常

  1. 一般情况下,终端输出异常信息如 socket timeout 超时为正常现象,如:
list prefix:<prefix> retrying...
...
java.net.SocketTimeoutException: timeout

程序会自动重试,如果比较频繁则可以修改超时配置重新运行程序,超过重试次数或者其他非预期异常发生时程序会退出,可以将异常信息反馈在 ISSUE列表 中。
2. 常见错误信息:
(1)java.lang.OutOfMemoryError: GC overhead limit exceeded
表示内存中加载了过多的资源导致 java 的 gc 内存溢出,需要关闭程序重新运行,降低线程数 threads 或者 unit-len。
(2)java.lang.OutOfMemoryError: unable to create new native thread
与(1)类似,内存溢出导致无法继续创建更多线程或对象。
(3)java.lang.UnsupportedClassVersionError: Unsupported major.minor version ...
请使用 java 8 或以上版本的 jdk(jre) 环境来运行该程序。

9 程序日志

7.7 版本引入了 slf4j+log4j2 来记录运行日志,主要记录信息为:
(1) 数据源位置记录信息 => procedure.log,记录格式为 json,数据源读取位置打点数据,每一行都是一次数据源位置记录,最后一行即为最后记录下的位置信 息,如果信息为 {} 表明程序运行完整,没有断点需要再次运行,如果信息中包含具体的字符串,说明这是程序留下的断点,则该行信息可以取出作为断点操作的配置 内容,具体参考:断点操作
(2) 程序运行过程输出及异常信息,通过终端 Console 和 qsuits.log 输出。

10 断点续操作

7.1 版本开始支持断点记录,在程序运行后出现异常导致终止或部分数据源路径错误或者是 INT 信号(命令行 Ctrl+C 中断执行)终止程序时,会记录数据导出中断的 位置,记录的信息可用于下次直接从未完成处继续导出数据,而不需要全部重新开始。尤其在对云存储空间列举文件列表时,特大量文件列表导出耗时可能会比较长,可能 存在断点续操作的需求,续操作说明:

  1. 如果存在续操作的需要,程序终止时会输出续操作的记录信息路径,如存储空间文件列举操作终止时可能输出:
    please check the prefixes breakpoint in <filename>.json, it can be used for one more time listing remained files.
    表示在 .json 文件(json 格式)中记录了断点信息,断点文件位于 save-path 同级路径中, 表示文件名。
  2. 对于云存储文件列表列举操作记录的断点可以直接作为下次续操作的操作来使用完成后续列举,如断点文件为 .json,则在下次列举时使用断点文件作 为前缀配置文件: prefix-config=<breakpoint_filepath> 即可,参见:prefix-config 配置
  3. 对于 file 数据源产生的断点文件记录了读取的文本行,亦可以直接作为下次续操作的操作来使用完成后续列举,如断点文件为 .json,则在下次继 续读 file 数据源操作时使用断点文件作为行配置文件: line-config=<breakpoint_filepath> 即可,参见:line-config 配置
  4. 断点续操作时建议修改下 save-path,便于和上一次保存的结果做区分(7.72 及以下版本中断点参数请和其他参数保持一致放在命令行或配置文件中,7.72 以上 版本无此限制,只要提供断点参数无论是否与其他参数同在命令行或配置文件中均可生效)。

注意:如果是系统宕机、断电或者强制关机或者进程强行 kill 等情况,无法得到输出的断点提示,因此只能通过<位置记录日志>来查看最后的断 点信息,取出 procedure.log 日志的最后一行并创建断点配置文件,从而按照上述方式进行断点运行。

11 分布式任务方案

对于不同账号或空间可以直接在不同的机器上执行任务,对于单个空间资源数量太大无法在合适条件下使用单台机器完成作业时,可分机器进行作业,如对一个空间列举完 整文件列表时,可以按照连续的前缀字符分割成多段分别执行各个机器的任务,建议的前缀列表为:
!\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz,将该列表任意分成 n 段,如:

prefixes=!,\,",#,$,%,&,',(,),*,+,\,,-,.,/,0,1
prefixes=2,3,4,5,6,7,8,9,:,;
prefixes=<,=,>,?,@,A,B,C,D,E,F,G,H,I,J,K,L,M,N,O
prefixes=P,Q,R,S,T,U,V,W,X,Y,Z,[,\\,\\,],^,_,`
prefixes=a,b,c,d,e,f,g,h,i,j,k,l,m
prefixes=n,o,p,q,r,s,t,u,v,w,x,y,z

,\ 需要转义)将前缀分为上述几段后,设置 prefixes 参数可以分做六台机器执行,同时因为需要列举空间全部文件,需要分别在第一段 prefixes 设置 prefix-left=true,在最后一段 prefixes 设置 prefix-right=true(其他段 prefixes 不能同时设置 prefix-left 或 prefix-right, 且仅能第一段设置 prefix-left 和最后一段设置 prefix-right,参数描述见数据源完备性

You can’t perform that action at this time.