最近更新时间: 2026-04-10 10:38:05

简介

Qshell 是利用七牛文档上公开的API实现的一个方便开发者测试和使用七牛API服务的命令行工具。该工具设计和开发的主要目的就是帮助开发者快速解决问题。目前该工具融合了七牛存储，CDN，以及其他的一些七牛服务中经常使用到的方法对应的便捷命令，比如b64decode，就是用来解码七牛的URL安全的Base64编码用的，所以这是一个面向开发者的工具，任何新的被认为适合加到该工具中的命令需求，都可以在ISSUE列表里面提出来，我们会尽快评估实现，以帮助大家更好地使用七牛服务。

Github 代码地址

下载

该工具使用 Go 语言编写而成，当然为了方便不熟悉 Go 或者急于使用工具来解决问题的开发者，我们提供了预先编译好的各主流操作系统平台的二进制文件供大家下载使用，由于平台的多样性，我们把这些二进制打包放到一个文件里面，请大家根据下面的说明各自需要选择支持合适平台来使用。

更新日志 查看，强烈建议使用 v2.8.0 及以上版本.

安装

该工具由于是命令行工具，所以只需要从上面的下载链接下载后即可执行使用。

Linux和Mac平台

（1）权限 如果在Linux或者Mac系统上遇到Permission Denied的错误，请使用命令chmod +x qshell来为文件添加可执行权限。这里的qshell是上面文件重命名之后的简写。

（2）任何位置运行 对于Linux或者Mac，如果希望能够在任何位置都可以执行，那么可以把qshell所在的目录加入到环境变量$PATH中去。假设qshell命令被解压到路径/home/jemy/tools目录下面，那么我们可以把如下的命令写入到你所使用的bash所对应的配置文件中，如果是/bin/bash，那么就是~/.bashrc文件，如果是/bin/zsh，那么就是~/.zshrc文件中。写入的内容为：

export PATH=$PATH:/home/jemy/tools

保存完毕之后，可以通过两种方式立即生效，其一为输入source ~/.zshrc或者source ~/.bashrc来使配置立即生效，或者完全关闭命令行，然后重新打开一个即可，接下来就可以在任何位置使用qshell命令了。

Windows平台

（1）闪退问题 本工具是一个命令行工具，在Windows下面请先打开命令行终端，然后输入工具名称执行，不要双击打开，否则会出现闪退现象。

（2）任何位置运行 如果你希望可以在任意目录下使用qshell，请将qshell工具可执行文件所在目录添加到系统的环境变量中。由于Windows系统是图形界面，所以方便一点。假设qshell.exe命令被解压到路径E:\jemy\tools目录下面，那么我们把这个目录放到系统的环境变量PATH里面。

（3）文本编码问题

当使用 qupload 等需要配置文件的命令时，不要使用 Notepad++ 等编辑器来编写配置文件，在本地右键默认新建一个文本文档来进行编写。

（4） Windows 平台文件路径和字符

Windows 平台下的文件路径需要写为\\的写法，如C:\\Users\\li\\Downloads。

在使用命令和配置文件时，需要使用 “” 双引号,不能使用单引号。

密钥设置

该工具有两类命令，一类需要鉴权，另一类不需要。

需要鉴权的命令都需要依赖七牛账号下的 AccessKey 和 SecretKey。所以这类命令运行之前，需要使用 account 命令来设置下 AccessKey ，SecretKey 。

$ qshell account ak sk name

其中name表示该账号的名称, 如果ak, sk, name首字母是"-", 需要使用如下的方式添加账号, 这样避免把该项识别成命令行选项:

$ qshell account -- ak sk name

可以连续使用qshell account 添加账号ak, sk, name信息，qshell会保存这些账号的信息， 可以使用qshell user命令列举账号信息，在各个账号之间切换, 删除账号等

账户管理

使用qshell user 子命令可以用来管理记录的多账户信息。

1. qshell user ls可以列举账户下所有的账户信息
2. qshell user cu <userName>可以用来切换账户
3. qshell user cu 不携带<userName>的话会切换到最近的上个账户；比如我在A账户做完操作后，使用qshell user cu B到了B 账户，那么使用qshell user cu可以切回到A账户.

开启命令的自动补全

linux上，使用bash

在centos上，需要安装bash-completion包，默认该包没有安装

$ yum install bash-completion -y

给当前的bash加入自动补全， 运行命令

$ source <(qshell completion bash)

也可以把这个配置加入bash的启动文件中，这样到bash启动的时候，会自动加载qshell的补全配置：

$ echo "source <(qshell completion bash)" >> ~/.bashrc

Mac上，使用zsh 把如下代码加入zsh的启动文件中~/.zshrc

if [ $commands[qshell] ]; then
  source <(qshell completion zsh)
fi

命令选项

该工具还有一些有用的选项参数如下：

配置文件

1. 配置文件格式支持 json，用户可按需进行配置，配置文件分两层：

• 全局配置：需要在家目录下创建文件名为 .qshell.json 的 json 文件，此配置对 qshell 中的所有账号生效（qshell 当前账号可以通过 qshell user cu 命令进行切换）。
• 账号配置：在 qshell 用户目录下（ ${家目录}/.qshell/users/${qshell 账号名}/ ）创建文件名为 .qshell.json 的 json 文件，此配置仅对当前目录所属的 qshell 账号生效；账号配置优先级大于全局配置。

2. 配置文件可以配置 use_https 和 host 相关信息：

• use_https：qshell 请求是否使用 https。
• host 配置：如 io host, up host, uc host, api host, rs host, rsf host；除 uc host 外，其他 host 要么不配置，要么全配置。
  • 公有云可以不配置 host；
  • 私有云：如果私有云支持 uc 查询 bucket 所在区域信息（/query api），那么仅配置 uc host 即可；如果不支持则必须配置所有 host。

注： qshell 某些命令的配置和文件的配置会有重合，此时优先级如下：

qshell 命令配置 > 账号配置 > 全局配置

通过 -C/-L 选项指定配置文件，实际是指定账号配置。

配置例子：

默认官方的列举空间的文件使用的是rs.qiniu.com域名，如果因为某种原因，比如私有存储，需要替换使用rs-test.qiniu.com这个域名的话，那么只需要 在家目录下创建文件名字为.qshell.json的配置文件，文件内容为

{
    "hosts": {
        "rs": "rs-test.qiniu.com"
    }
}

如果想要更改io host为io-test.qiniu.com的话，只需要继续在上面的hosts中添加，如下：

{
    "hosts": {
        "rs": "rs-test.qiniu.com",
        "io": "io-test.qiniu.com"
    }
}

同理如果全部修改的话

{
    "hosts": {
        "rs": "rs-test.qiniu.com",
        "io": "io-test.qiniu.com",
        "api": "",
        "rsf": ""
    }
}

命令列表

• v2.7.0 及以上版本，命令列表及命令使用文档说明，可直接使用 qshell 自助查看。
  • qshell -h，显示支持命令列表
  • qshell <子命令> --doc 查看详细命令使用说明
• 以下列表内使用文档链接适用于 v2.3.0 —— v2.6.3 版本
• 查看工具版本号请使用命令 qshell -v

账号设置命令

存储相关命令

CDN 相关的命令

|命令|描述|详细| |------|------------|----------|--------| |cdnrefresh|批量刷新cdn的访问外链或目录|文档| |cdnprefetch|批量预取cdn的访问外链|文档|

工具类命令

音视频处理相关命令

签名类命令

第三方存储类工具

问题反馈

如果您有任何问题，请写在ISSUE列表里面，我们会尽快回复您。