qiniu-suits (qsuits)

qiniu-suits-java 是一个多线程的云存储 api tools (base-qiniu)，通过设计的前缀并发算法能够高效并发列举 云存储空间的资源列表(支持七牛云/阿里云/腾讯云/AWS S3/又拍云/华为云/百度云等，支持 S3 接口的均可以通过 S3 数据源的方式来导出)，同时支持对包含 资源列表的本地数据源并发进行批量处理，处理功能主要包括对七牛云存储资源进行增/删/改/查/转码、以及云存储迁移和公网资源内容审核等，以及本地数据源下大规模 文件上传或者导出文件列表，非常适合大量文件处理和存储空间资源直接管理的场景，同时也支持交互模式和单行模式 （直接调用接口处理命令行的一次输入）运行。该 tools 基于 Java8 编写，可基于 jdk8（及以上）环境在命令行或 ide 中运行，命令行运行推荐使用执行器 qsuits）。

功能列表：

• [x] 云存储资源列举，支持并发、过滤及指定前缀、开始及最大结束文件名或 marker 等参数
• [x] 文件迁移/备份，针对不同数据源（云存储空间、http 链接列表）向七牛存储空间导入文件
• [x] 资源文件过滤，按照日期范围、文件名(前缀、后缀、包含)、mime 类型等字段正向及反向筛选目标文件
• [x] 检查云存储资源文件后缀名 ext 和 mime-type 类型是否匹配 check，过滤可疑文件列表
• [x] 上传文件到存储空间 qupload 配置
• [x] 同步 url 内容直传到存储空间 syncupload 配置
• [x] 删除空间资源 delete 配置
• [x] 复制资源到指定空间 copy 配置
• [x] 移动资源到指定空间 move 配置
• [x] 对空间资源进行重命名 rename 配置
• [x] 查询空间资源的元信息 stat 配置
• [x] 修改空间资源的存储类型（低频/标准/归档）type 配置
• [x] 对空间的归档文件进行解冻 restorear 配置
• [x] 修改空间资源的状态（启用/禁用）status 配置
• [x] 修改空间资源的生命周期 lifecycle 配置
• [x] 对设置了镜像源的空间资源进行镜像更新或拉取 mirror 配置
• [x] 异步抓取资源到指定空间 asyncfetch 配置
• [x] 同步抓取资源到指定空间 fetch 配置
• [x] 查询资源的 hash & size qhash 配置
• [x] 查询空间资源的视频元信息 avinfo 配置
• [x] 根据音视频资源的 avinfo 信息来生成转码指令 pfopcmd 配置
• [x] 对空间资源执行 pfop 请求 pfop 配置
• [x] 通过 persistentId 查询 pfop 的结果 pfopresult 配置
• [x] 对私有空间资源进行签名，导出私有 url privateurl 配置
• [x] 对资源生成 url，导出公开 url 或添加参数 publicurl 配置
• [x] 对 m3u8 的 http 资源进行读取导出其中的 ts 文件列表 exportts 配置
• [x] 通过 http 下载资源到本地 download 配置
• [x] 图片类型资源内容审核 imagecensor 配置
• [x] 视频类型资源内容审核 videocensor 配置
• [x] 内容审核结果查询 censorresult 配置
• [x] 修改资源的 mimeType mime 配置
• [x] 修改资源的 metadata metadata 配置
• [x] CDN 资源提交刷新、提交预取的操作 cdn 提交刷新预取操作配置
• [x] CDN 查询刷新、查询预取结果的操作 cdn 查询刷新预取操作配置
• [x] 查询七牛存储空间绑定的域名 domainsofbucket 操作配置

【部分 process 属于危险操作（如文件删除/禁用等），需要在启动后根据提示输入 y/yes 确认，如果不希望进行 verify 验证则需要在命令行加入 -f 参数】

支持特性：

• [x] 多数据源账户密钥（加密）设置：账号设置
• [x] 多种模式运行：程序运行过程
• [x] 中间状态保持：断点续操作
• [x] 手动分布式执行任务：分布式任务方案
• [x] 按照时间计划延迟或周期性暂停任务执行：时间计划

账号设置

（7.73 及以上版本）支持预先设置好账号的密钥（经过加密），在后续执行中只需使用 account name 即可读取对应账号密钥进行操作，定义不同的 account name 则可设置多对密钥，亦可设置不同数据源的账号密钥，同一数据源的账号名相同时会覆盖该账号的历史密钥，命令行操作如下所示（配置文件也可以进行账户设置和使用， 去掉命令行参数开头的 - 符号且每项参数成一行即可，与后面程序运行方式的配置文件用法相同），密钥参数名参考各存储数据源配置参数。

1、设置 account：

命令格式：`-account=

- -

-id= -

-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=设置 AWS/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=<已存在的账号名> -d` 可以修改默认账号。

2、使用 account 账号：

-a=test 表示使用 test 账号，数据源会自动根据 path 参数判断
-d 表示使用默认的账号，数据源会自动根据 path 参数判断

3、查询 account 账号：

命令格式：`-getaccount=

- [-dis] [-d]，默认只显示 id 的明文而隐藏 secret，-dis参数表示选择明文显示 secret，如：-getaccount -d表示查询设置的默认账号的密钥-getaccount=test -dis表示查询设置的所有账号名为 test 的密钥，并显示 secret 的明文-getaccount=s3-test表示查询设置的 S3 账号名为 test 的密钥-getaccount=ten-test表示查询设置的腾讯账号名为 test 的密钥-getaccount=qiniu-test` 表示查询设置的七牛账号名为 test 的密钥

4、删除 account 账号：

命令格式：`-delaccount=

-，删除账号只允许一次删除一条，如：-delaccount=s3-test表示删除设置的 S3 账号名为 test 的密钥-delaccount=ten-test表示删除设置的腾讯账号名为 test 的密钥-delaccount=test/qiniu-test` 表示删除设置的七牛账号名为 test 的密钥

1 程序运行过程

（1）批处理模式：[读取数据源] => [选择过滤器] => [数据处理过程] => [结果持久化]

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

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

2 运行方式

提供命令行运行工具 qsuits（或可执行 jar 包）和 maven artifact，使用时建议直接使用或者更新到最新版本。 以下的 x.x.x 表示版本号，最新版本见 Release

命令行直接运行 jar 包

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

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

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

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

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

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

备注3：7.72 及以下版本中命令行参数与配置文件参数不可同时使用，指定 -config=

命令行执行器 qsuits

由于 qsuits-java 基于 java 编写，命令行运行时需要使用 java -jar 命令，为了简化操作运行方式及增加环境和版本管理，提供直接的命令行可执行工具 qsuits 执行器（使用 golang 编写和编译）来代理 qsuits-java 的功能，支持 qsuits-java 所有参数配置，命令和配置文件用法完全相同，工具下载地址如下：

操作系统	程序名	地址
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.jar 的最新版本再运行，其他选项参考 qsuits-exec-go 的文档：https://github.com/NigelWu95/qsuits-exec-go

程序依赖 jar

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

<dependency>
  <groupId>com.qiniu</groupId>
  <artifactId>qsuits</artifactId>
  <version>x.x.x</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=<path> 表示从本地目录（或文件）中读取资源列表，参考本地文件数据源示例
未设置数据源时则默认从七牛空间进行列举，数据源详细参数配置和说明及可能涉及的高级用法见：数据源配置，配置文件示例可参考配置模板

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(可不设置)使用简称，参考华为 Region|
|baidu |bai-id=

bai-secret=

region=bj/gz/su...| 密钥对为百度云账号的 AccessKeyId 和 SecretAccessKey

region(可不设置)使用简称，参考百度 Region|

file 本地文件读取

本地文件数据源分为两种情况：（1）读取文件内容为数据列表按行输入（2）读取路径下的文件本身，包括目录遍历，得到文件信息作为输入
1、第一种情况，文件内容为资源列表，可按行读取输入文件的内容获取资源列表，文件行解析参数如下：
parse=tab/json 表示输入行的格式
separator=\t 表示输入行的格式分隔符（非 json 时可能需要）
add-keyPrefix= 数据源中每一行的文件名添加前缀
rm-keyPrefix= 数据源中每一行的文件名去除前缀
uris= 设置数据源路径下需要读取的文件名列表，以 , 号分割文件名，不设置默认读取 path 下全部文本文件
uri-config= 数据源文件路径及对应文本读取的起始行配置
数据源详细参数配置和说明及可能涉及的高级用法见：数据源配置

2、第二种情况，读取文件本身，用于导出本地的文件列表，也可以进行文件上传，解析参数如下：
parse=file 表示进行文件信息解析格式
directories= 设置数据源路径下需要读取的目录列表，以 , 号分割目录名，不设置默认读取 path 下全部目录下的文件
directory-config= 数据源文件目录及对应已上传的文件名配置，配置中记录已上传的文件在 path 中的位置标识
（1）该数据源导出文件列表时默认只包含 filepath 和 key 信息，如果需要 size、date 等其他信息，请参考 数据源配置。
（2）用于上传文件的操作时，设置 process=qupload 会自动生效，从 path 中读取所有文件（除隐藏文件外）执行上传操作，具体配置可参考 qupload 配置。

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> 格式为：yyyy-MM-DD HH:MM:SS，如 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-strict-error= true/false，是否使用严格错误模式，默认为 false，为 true 表示对基础字段过滤到不匹配的行抛出异常或记录为 not_match 的结果（filter_not_match_xxx.txt）

关于 f-type

存储源	type 参数类型	具体值
七牛	整型	0 表示标准存储；1 表示低频存储；2 表示归档存储
其他	字符串	如：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

根据资源的字段关系选择某个特征下的文件，目前支持 ext-mime 检查，程序内置的默认特征配置见：check 默认配置，运行 参数选项如下：
f-check=ext-mime 表示进行后缀名 ext 和 mimeType（即 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 详细配置可见[f