数据客户端-命令行 GDC-CLI
1 客户端安装和配置
1.1 安装
从官网下载的gdc-cli客户端为tar.gz (mac/linux)或 zip(windows)格式的压缩包,解压后即可:
linux/mac os 用户使用setup.sh脚本执行安装操作
windows 用户使用setup.exe程序执行安装操作 (使用管理员身份执行)
以linux/mac为例,安装时会请求root权限,提示输入密码
打印当前的版本信息,gdc安装成功。
客户端安装完成后,可直接使用 gdc <command> [option]
执行相应的命令(须重启/重新登录终端)
注: 部分生产的机器无法获取root权限,可以直接使用gdc-launcher可执行文件执行gdc命令,不影响正常使用,但无法使用自动更新和命令行补全功能。将来会提供针对此类用户的优化。
1.2 配置认证信息(config)
gdc对数据的所有操作均需验证当前用户的权限,用户可以使用非交互式命令或者交互式命令配置认证信息,用户信息会加密存储在本地。
- 非交互式配置:
gdc config -e <endpiont> -i <Access ID> -k <Access Key>
- 交互式配置
2 文件传输
2.1 文件上传(upload)
普通传输操作
gdc 的文件上传支持将本地文件按照原有的目录结构上传到远端指定目录下,若云端不存在该目录,会自动创建。传输 Demo目录到云端 ~/20180330目录下
本地目录结构如下
数据传输完成提示
云端目录结构如下
覆盖上传
当云端已存在同名的文件时,无论状态如何,在非断点续传的状态下,gdc的文件上传均会跳过该文件,若需强制覆盖,可使用 –force (-f) 参数进行操作。
断点续传
gdc上传文件时会在
pwd
路径(执行gdc命令时所在的位置)中的_gdcu
文件夹中缓存文件和记录传输进度,上传成功后会自动删除。若传输未成功,缓存不会自动删除,待下次上传时可以自动断点续传,所以当文件较大时,断点续传减少了传输时间;
需要注意的是:(1) 断点续传时不能切换上次的工作目录
pwd
,也不能删除_gdcu目录下相应文件的缓存
(2) 断点续传时不能修改分块大小
(3) 如果希望重新上传,可以使用 -f/–force 参数强制取消断点续传控制并行的上传任务数 task | thread
- –thread 设置单个文件内部处理的并发数,一般是在传输fastq文件中使用
- –task 设置文件传输任务的并发数
一般地,如果追求单个文件的快速传完,那么–thread设大、–task设小;
如果希望整批文件快速传完,那么将–task设置大一些,–thread根据自己系统资源的情况进行设置。
因为单个文件的校验是线性的,增大–task的配额可以减小等待IO对资源利用的影响、增大–thread可以在单位时间内尽可能地利用cpu的资源。根据测试的一些经验,在传输较大的fastq文件的情况下, –task 4 –thread 8 基本占满一台四核八G计算机的资源。
上传结果统计报告
gdc上传下载时,会将每个文件的传输状态记录在传输报告中,上传结束时如果想查看详细的报告,可以在~/gd-transfer-report/
中找到
相应的报告文件:
- user_home
- gd-transfer-report
- upload
- upload-result-yyyy-mm-dd-HHMMSS.gdc
2.2 文件下载(download)
gdc下载操作与上传操作的参数及界面提示基本相同
- 文件跳过(本地文件存在)文件下载失败(云端文件不可用)
- 强制覆盖本地文件
3 文件操作
3.1 列举文件(list)
- 列出指定路径下的文件
- 列出指定路径下的文件(带颜色)
- 树形打印目录结构
list操作的附加选项可以支持简写:
gdc ls 输出文件名(目录会以"/"结尾)
gdc ls -lc | ls -l -c 输出带颜色的详细信息
gdc ls -l 输出不带颜色的信息
gdc ls -t 树形打印(不带颜色)
gdc ls -tc | ls -t -c 树形打印(带颜色)
gdc ls -t -l 树形打印(同时输出文件大小)
3.2 移动/重命名(mv)
mv操作和linux的风格相同,不支持跨账号移动
- 重命名文件/目录
- 移动文件/目录
mv操作的情况如下:
1. /path/to/a -> /path/to/b src(a) 为文件, dst(b)不存在:
src重命名为dst: /path/to/b
2. /path/to/a -> /path/to/b/ src(a) 为文件, dst(b)存在且为目录:
src移动到dst目录下: /path/to/b/a
3. /path/to/a -> /path/to/b src(a) 为目录, dst(b)不存在:
src重命名为dst: /path/to/b/
4. /path/to/a -> /path/to/b src(a) 为目录, dst(b)存在且为目录:
src移动到dst目录下 /path/to/b/a/
5. /path/to/a -> /path/to/b/ src(a) 为目录, dst(b)存在且为目录:
src移动到dst目录下 /path/to/b/a/
6. 目标路径为目录且不存在,提示用户创建目录
7. 目标路径为文件,提示用户文件已存在
3.3 删除(rm)
删除文件或目录,当目录不为空时需使用 –recursive (-r)参数递归删除整个目录
- 删除文件
- 删除目录
3.4 创建目录(mkdir)
创建目录说明
- 创建单个目录
- 创建多级目录
3.5 冷备(archive)
将文件从标准存储归档低频访问的存储类型,转换完成后状态由 archiving 转为 archived。冷备后的文件无法直接下载,暂不支持对目录操作
3.6 恢复(restore)
将冷备的文件暂时恢复(24小时),恢复后的文件状态为 restored,文件过期后自动转为archived状态。
4 FAQ
- 关于上传时磁盘的要求
上传时会缓存文件,需要本地磁盘有足够的空间,否则无法正常传输。
文件缓存地址在{pwd}/_gdcu
,pwd
为gdc执行的目录。 - 关于冲突文件处理
数据传输时,为了防止用户同时传输同一个文件导致相互覆盖,碰到任何状态的已存在的数据都会跳过并提示用户;
文件状态为uploading时,gdc会先检查当前工作目录(执行gdc命令的工作目录)下是否存在该文件上次传输的缓存,若存在才判断为续传,否则视为冲突文件。出现冲突文件时,由于不是上传失败,退出码仍然为0。
图形化客户端操作指南
功能描述
- 支持使用账号名密码或者 AccessID/AccessKey 登录。
- 使用安全码快捷登录。
- 支持自定义服务地址。
- 数据的浏览和管理(包括上传、下载、文件目录管理、冷备、恢复、移动和删除等)。
- 授权数据浏览和管理。
- 数据模糊搜索。
- 支持多域切换。
使用说明
1. 客户端下载
访问GeneDock帮助中心 ,选择适配您操作系统的图形化客户端。
2. 客户端安装(以Mac安装为例)
下载完成后,双击安装文件,按照操作提示完成客户端安装。
3. 客户端登录
GDC 支持使用“账号名+用户名+密码”方式登录;同时也支持“Access ID + Access Key”方式登录。
3.1 使用账号名登录
程序启动默认使用账号名密码方式登录,默认 为admin 用户。如果是子用户登录,需要选择普通用户, 然后填写子用户名。如图:
3.2 使用Access ID 和 Access Key 登录
在账号名登录界面点击“切换到 Access Key 登录”按钮后,程序切换到 Access ID + Access Key 方式登录界面,输入相应信息后,点击登录按钮即可。
注意:==不是您的登录名和密码==。
(Access ID 和 Access Key 需要在 www.genedock.com 登录后,点击“进入后台”、“设置”、 “AccessKey”页面获取)。
3.3 使用安全码登录
再次启动时,无需再次输入账号信息,可凭安全码登录后使用,如图 所示。选择跳过则下次启动时,需要再次输入账号信息登录。
点击“切换用户”按钮可以返回账号信息登录界面,此时旧安全码已经失效。
4. 数据浏览
4.1 数据展示
数据列表包含数据名称、大小、状态和最后更新时间。通过名称前的图标可区分文件夹与文件。数据状态包括上传中、校验中、可用、已冷备、暂恢复等。
双击文件夹即可进入相应目录。在数据列表上方展示了当前所在路径,如下图所示。路径展示框左侧可以前后切换历史访问路径,支持最大记录 20 条。如果数据名称过长将展示尾部最大可见长度。将鼠标悬停此条目,即可查看完整名称。
4.2 访问授权账号数据
程序主页面左侧为账号和项目面板。可通过Account 列表切换账号访问授权账号数据。如下图:
4.3 搜索
在搜索框中输入关键字,敲击“回车”键,即可通过数据名称模糊搜索。搜索范围为当前目录及其子目录下所有文件或文件夹。如下图所示。
搜索结果中会展示每条数据所在目录地址,点击所在目录,可以跳转到所在目录地址。点击搜索框最右侧“x”按钮,可退出搜索结果。
5 数据传输
数据列表面板下方为数据传输面板,传输面板包括上传面板、下载面板和日志面板。数据传输面板默认为收缩状态,点击传输面板顶栏右侧箭头,即可展开或收缩传输面板。
当有程序退出时,如果有传输任务未结束,程序将会提示并请求退出确定。退出时自动记录传输列表信息。下次使用安全码登录后,继续进行未完成的传输任务。
数据上传下载均支持断点续传功能。
5.1 上传
点击上传按钮后,选择需要上传的数据并确定。程序即将上传所选择的数据,并自动展示上传面板。
上传面板包含上传控制和上传列表两部分。上传控制包含暂停、取消、全部开始、全部暂停、全部取消和清空已完成功能。其中暂停和取消需要先在上传列表选择需要操作的条目才可使用。默认为不可点击状态。上传列表包含数据本地路径、数据大小、进度状态、暂停和取消操作。
传输面板顶栏实时显示上传网络速度。
5.2 下载
在数据浏览列表选择数据后,点击“下载”按钮并选择目录地址后,程序将开始下载所选择的数据,并自动展示下载面板。
下载面板包含下载控制和下载列表两部分。下载控制包含暂停、取消、全部开始、全部暂停、全部取消和清空已完成功能。其中暂停和取消需要先在下载列表选择需要操作的条目才可使用。默认为不可点击状态。下载列表包含数据源数据路径、数据大小、进度状态、暂停和取消操作。
传输面板顶栏实时显示下载网络速度。
6 数据管理
除了数据传输,GeneDock GDC还提供、创建文件夹、移动、冷备、恢复、重命名和删除等常见数据操作。
6.1 创建文件夹
点击工具栏“新建文件夹”按钮,即可在当前路径创建新文件夹。输入数据名称点击确认即可,如下图所示。如果创建失败,可能是文件或文件夹已存在,文件夹名称不符合规定等。
6.2 移动
选择需要操作数据,点击工具栏“移动”按钮,并选择目的地址。可以移动数据。如下图 所示。数据移动窗口只展示文件夹,需要移动的文件夹不可选为目的地址。注意,如果移动上传或下载中的数据将可能导致上传或下载失败。另外,如果该数据为授权过的数据,会导致授权失效,需要重新授权。
6.3 冷备和恢复
仅状态为“可用”的数据支持冷备,状态为“已冷备”的数据支持恢复。当没选择或选择数据为非“可用”状态时,冷备按钮不可点击;当选择的数据为“已冷备”状态,“恢复”按钮变为可点击状态。如下图所示。
冷备和恢复操作后,数据状态相应变成“冷备中”和“恢复中”状态。
6.4 重命名
选中需要操作数据,点击工具栏中“重命名”按钮,即可重新编辑数据名称。不支持批量重命名。当选择多个条目时,重命名按钮变为不可点击状态
6.5 删除
选择需要操作数据,点击删除按钮并确认删除即可。支持批量删除。开始删除时,程序会提示当前删除状态(总需删除条目数和已删除数,如下图所示。
7 设置
点击“设置”按钮打开设置窗口。设置内容包括上传和下载的并发任务数和并发线程数设置,以及网络路线选择。网络路线仅支持普通网络和VPC专线网络(VPC 专线网络是指阿里云OSS专线网络)。
缓存路径用于数据上传时存储缓存数据,默认为当前用户目录,可手动输入或通过右侧“更改”按钮选择后更改路径,如下图所示。
8 日志
日志面板包含日志工具栏和日志输出面板两部分。日志工具栏包括打开日志文件夹和清空日志面板功能。日志输出面板包含错误精简日志信息,详细信息需要在本地日志文件夹下的 gd.log 文件中查看,如下图所示。
9 FAQ
- 使用数据客户端的推荐资源需求
Mac : 2015年后生产的即可
Windows: win10 和 win7 推荐4核8G以上配置 - 关于上传时磁盘的要求
上传时会文件缓存等操作,需要本地磁盘有足够的空间,否则无法正常传输。对于Windows用户,如C盘分区较小,可以在上传缓存路径,见 7 设置。