open(4)ossutil oss-cli

Posted on 2025-04-25 Edited on 2025-04-26 Views:

ossutil 是阿里云提供的命令行工具，用于 管理阿里云 OSS（对象存储服务）资源，支持文件的上传、下载、删除、同步、签名 URL 等操作。

offical-site

https://github.com/aliyun/ossutil

官方使用文档（中文）： https://help.aliyun.com/document_detail/50452.html

1.功能介绍

ossutil 是基于 **Go 编写的 CLI 工具(对cos操作)**，支持以下功能：

功能	描述
上传 / 下载	文件、文件夹的上传和下载
同步	本地与 OSS 之间同步
列出	查看 Bucket 中的文件和子目录
删除	删除文件、文件夹、Bucket
创建 / 删除 Bucket	管理 Bucket 资源
设置权限	设置 Bucket / Object 的 ACL
获取签名 URL	获取可分享的临时访问链接
配置管理	支持多账号配置，快速切换
元信息操作	支持 object 的 meta 修改、查看等操作

2.编译方法

阿里云官方提供了预编译好的版本，一般不需要自己编译，直接下载使用即可。但如果你想从源码编译（例如你在开发或做二次开发），可以按如下步骤：

2.1.克隆源码

1 2	git clone https://github.com/aliyun/ossutil.git cd ossutil

2.2.安装 Go 环境

确保你的系统中已经安装 Go（推荐 Go 1.16+）
你可以用 go version 检查。

1	go version

如果未安装，可以从 https://golang.org/dl/ 下载并安装。

2.3. 编译

1	go build -o ossutil main/ossutil.go

编译后会在当前目录生成 ossutil 可执行文件（Windows下是 ossutil.exe）

3.使用方法

3.1下载预编译版本（推荐）

官方下载页面：
🔗 https://help.aliyun.com/document_detail/50452.html

选择你的系统版本（Linux/Mac/Windows），下载后解压。

3.2. 配置账号

1	./ossutil config

它会提示你输入以下信息：

Endpoint：OSS 的访问域名（如：oss-cn-hangzhou.aliyuncs.com）
AccessKeyId：你的阿里云 AccessKey ID
AccessKeySecret：你的 Secret
是否设置为默认配置

生成的配置保存在 ~/.ossutilconfig 文件中。

3.3. 常用命令

上传文件

1	./ossutil cp localfile.txt oss://your-bucket/path/to/file.txt

下载文件

1	./ossutil cp oss://your-bucket/path/to/file.txt localfile.txt

同步目录

1	./ossutil sync /local/dir/ oss://your-bucket/dir/

删除文件

1	./ossutil rm oss://your-bucket/file.txt

列出 Bucket 内容

1	./ossutil ls oss://your-bucket/

获取签名 URL（临时访问链接）

1	./ossutil sign oss://your-bucket/file.txt --timeout 3600

4.help

mvpbang@mvpbang ~ % ossutil –version
ossutil version: v1.7.19

4.1.ossutil 参数

mvpbang@mvpbang ~ % ossutil --help
Usage of ossutil:

Options:
  -k, --access-key-secret=  访问oss使用的AccessKeySecret（该选项值会覆盖配置文件中的相应设置）。
  -d, --directory           返回当前目录下的文件和子目录，而非递归显示所有子目录下的所有object。
  --ecs-role-name=          表示角色名，主要用于EcsRamRole模式
  --upmode=                 表示上传模式,缺省值为normal,取值为:normal|append|multipart,分别表示正常上传、追加上传、分块上传,主要在命令probe中使用
  --trafic-limit=           http请求限速,单位:bit/s,缺省值为0(不受限制),用于sign命令
  --local-host=             工具的ip地址,比如 127.0.0.1
  -r, --recursive           递归进行操作。对于支持该选项的命令，当指定该选项时，命令会对bucket下所有符合条件的objects进行操作，否则只对url中指定的单个object进行操作。
  --sse-algorithm=          表示服务端加密算法，取值为KMS或者AES256
  --probe-item=             表示probe命令的探测项目, 取值可为upload-speed, download-speed, cycle-symlink
  -f, --force               强制操作，不进行询问提示。
  --delete                  删除操作
  --payer=                  请求的支付方式，如果为请求者付费模式，可以将该值设置成"requester"
  -p, --password            表示从键盘输入accessKeySecret参数
  --ua=                     指定http请求中的user agent, 会在缺省值后面加上指定值
  --cloudbox-id=            云盒的id，缺省值为空，适用于云盒场景
  -a, --all-type            指定操作的对象为bucket中的object和未完成的Multipart事件。
  --range=                  下载文件时，指定文件下载的范围，格式为：3-9或3-或-9
  --query-param=            设置请求的query参数
  --method=                 表示命令的操作类型,取值为PUT、GET、DELETE、LIST等
  --only-current-dir        表示仅操作当前目录下的文件或者object, 忽略子目录
  --sign-version=           http请求使用的签名算法版本, 缺省为空, 表示v1版本
  --output-dir=             指定输出文件所在的目录，输出文件目前包含：cp命令批量拷贝文件出错时所产生的report文件（关于report文件更多信息，请参考cp命令帮助）。默认值为：当前目录下的ossutil_output目录。
  --object=                 表示oss中对象的名称,主要在命令probe中使用
  --bucketname=             表示bucket的名称,主要在命令probe中使用
  --disable-empty-referer   表示不允许referer字段为空,主要在referer命令中使用
  --proxy-pwd=              网络代理服务器的密码,默认为空
  -B, --block-size=         表示du命令字节显示的单位,取值可以为KB, MB, GB, TB
  --meta=                   设置object的meta为[header:value#header:value...]，如：Cache-Control:no-cache#Content-Encoding:gzip
  --maxupspeed=             最大上传速度,单位:KB/s,缺省值为0(不受限制)
  --disable-dir-object      表示上传文件时不为目录生成oss对象,主要用于cp命令
  --item=                   表示命令的功能类型，取值为LOCATION、PROGRESS等
  --region=                 bucket所在的地区, 比如cn-hangzhou, 缺省值为空, 如果使用v4签名则必须传入
  -j, --jobs=               多文件操作时的并发任务数，默认值：3，取值范围：1-10000
  --addr=                   表示一个网络地址,通常为域名,主要在命令probe中使用
  --kms-masterkey-id=       表示kms秘钥托管服务中的主秘钥id
  --end-time=               结束时间,为linux/Unix系统里面的时间戳,既从1970年1月1日(UTC/GMT的午夜)开始所经过的秒数
  -s, --short-format        显示精简格式，如果未指定该选项，默认显示长格式。
  -m, --multipart           指定操作的对象为bucket中未完成的Multipart事件，而非默认情况下的object。
  --loglevel=               日志级别，默认为空,表示不输出日志文件,可选值为:info|debug,info输出提示信息日志,debug输出详细信息日志(包括http请求和响应信息)
  --connect-timeout=        表示客户端连接超时的时间，单位为秒, 缺省值为120
  --kms-data-encryption=    表示kms秘钥托管服务使用的加密算法,目前取值仅支持为SM4, 或者为空
  --acr-headers=            表示http header Access-Control-Request-Headers的值,主要用于cors-options命令
  --role-session-name=      表示会话名字，主要用于RamRoleArn模式
  --skip-verify-cert        表示不校验服务端的数字证书
  --parallel=               单文件内部操作的并发任务数，取值范围：1-10000, 默认将由ossutil根据操作类型和文件大小自行决定。
  --maxdownspeed=           最大下载速度,单位:KB/s,缺省值为0(不受限制)
  --disable-encode-slash    表示不对url path中的'/'进行编码, 主要用于sign命令
  --bigfile-threshold=      开启大文件断点续传的文件大小阈值，默认值:100M，取值范围：0B-9223372036854775807B
  --partition-download=     分区下载使用,一个ossutil命令下载一个分区,其值格式为"分区编号:总分区数",比如1:5,表示当前ossutil下载分区1,总共有5个分区;分区号从1开始编号,objects的分区规则由工具内部算法决定;利用该选项,待下载的objects分成多个区,可以由多个ossutil命令一起下载完成,每个ossutil命令下载各自的分区,多个ossutil命令可以并行在不同机器上执行
  --runtime=                设置命令的持续的运行时间
  -v, --version             显示ossutil的版本（v1.7.19）并退出。
  --url=                    表示一个url地址,主要在命令probe中使用
  --enable-symlink-dir      表示允许上传链接子目录下的文件,默认不上传; probe命令可以探测是否存在死循环链接文件或者目录
  --type=                   计算的类型, 默认值：crc64, 取值范围: crc64/md5
  --marker=                 列举Buckets时的marker，或列举objects或Multipart Uploads时的key marker, 或者其他有需要marker的地方。
  --snapshot-path=          该选项用于在某些场景下加速增量上传批量文件或者增量下载批量object。在cp上传文件或者下载object时使用该选项，ossutil在指定的目录下生成快照文件，记录文件上传或者object下载的快照信息，在下一次指定该选项上传或下载时，ossutil会读取指定目录下的快照信息进行增量上传或者下载。用户指定的snapshot目录必须为本地文件系统上的可写目录，若该目录不存在，ossutil会创建该文件用于记录快照信息，如果该目录已存在，ossutil会读取里面的快照信息，根据快照信息进行增量上传（只上传上次未成功上传的文件和本地进行过修改的文件）或者增量下载（只下载上次未成功下载的object和修改过的object），并更新快照信息。注意：该选项在本地记录了成功上传的文件的本地lastModifiedTime或者记录了下载object的lastModifiedTime，从而在下次上传或者下载时通过比较lastModifiedTime来决定是否跳过相同文件的上传或者跳过相同的object下载。当使用该选项上传时，请确保两次上传期间没有其他用户更改了oss上的对应object。当不满足该场景时，如果想要增量上传批量文件，请使用--update选项。ossutil不会主动删除snapshot-path下的快照信息，当用户确定快照信息无用时，请用户及时自行删除snapshot-path。
  --redundancy-type=        表示bucket的数据容灾类型, 取值可为LRS, ZRS. LRS为默认值,表示本地容灾, ZRS表示更高可用的同城多可用区容灾(3AZ)
  --backup-dir=             sync命令使用的备份文件的目录
  --token-timeout=          表示token的有效时间，单位为秒, 缺省值为3600，主要用于RamRoleArn模式下的AssumeRole参数
  --read-timeout=           表示客户端读超时的时间，单位为秒, 缺省值为1200
  --version-id-marker=      表示列举objects所有版本的version id marker
  --proxy-user=             网络代理服务器的用户名,默认为空
  -u, --update              更新操作
  --acr-method=             表示http header Access-Control-Request-Method的值,主要用于cors-options命令
  --disable-all-symlink     表示不允许上传目录下的链接文件以及链接目录, 缺省值为false
  --start-time=             起始时间,为linux/Unix系统里面的时间戳,既从1970年1月1日(UTC/GMT的午夜)开始所经过的秒数
  --tagging=                设置object的tagging,取值格式如["TagA=A&TagB=B..."]
  -c, --config-file=        ossutil工具的配置文件路径，ossutil启动时从配置文件读取配置，在config命令中，ossutil将配置写入该文件。
  --origin=                 表示http请求头origin字段的值
  --acl=                    acl信息的配置。
  --version-id=             表示object的版本id
  --limited-num=            返回结果的最大个数。
  --upload                  表示上传到oss,主要在命令probe中使用
  --sts-region=             指定sts endpoint的地区，比如cn-shenzhen，其中，cn指代的是国家，shenzhen指代的是地区，用于构造sts endpoint，该选项缺省时，sts endpoint为sts.aliyuncs.com，主要用于RamRoleArn模式
  --storage-class=          设置对象的存储方式，默认值：Standard，取值范围：Standard/IA/Archive/ColdArchive。
  --checkpoint-dir=         checkpoint目录的路径(默认值为:.ossutil_checkpoint)，断点续传时，操作失败ossutil会自动创建该目录，并在该目录下记录checkpoint信息，操作成功会删除该目录。如果指定了该选项，请确保所指定的目录可以被删除。
  --encoding-type=          输入或者输出的object名或文件名的编码方式，目前只支持url encode，即指定该选项时，取值范围为：url，如果不指定该选项，则表示object名或文件名未经过编码。bucket名不支持url encode。注意，如果指定了该选项，则形如oss://bucket/object的cloud_url，输入形式为：oss://bucket/url_encode(object)，其中oss://bucket/字符串不需要编码。
  --upload-id-marker=       列举Multipart Uploads时的uploadID marker。
  --ram-role-arn=           表示RAM角色的ARN，主要用于RamRoleArn模式
  -e, --endpoint=           ossutil工具的基本endpoint配置（该选项值会覆盖配置文件中的相应设置），注意其必须为一个二级域名。
  --disable-ignore-error    批量操作时候不忽略错误, 缺省值为false
  --mode=                   表示鉴权模式，取值可以为AK，StsToken，RamRoleArn，EcsRamRole，缺省值为空
  --retry-times=            当错误发生时的重试次数，默认值：10，取值范围：1-500
  --disable-crc64           该选项关闭crc64，默认情况下，ossutil进行数据传输都打开crc64校验。
  --object-file=            表示所有待处理的objects，取值为一个存在的文件路径
  -L, --language=           设置ossutil工具的语言，默认值：CH，取值范围：CH/EN，若设置成"CH"，请确保您的系统编码为UTF-8。
  --exclude=                不包含对象匹配模式，如：*.txt
  -i, --access-key-id=      访问oss使用的AccessKeyID（该选项值会覆盖配置文件中的相应设置）。
  --all-versions            表示object所有版本
  --proxy-host=             网络代理服务器的url地址,支持http/https/socks5,比如 https://120.79.128.211:3128, socks5://120.79.128.211:1080
  --force-path-style        使用 path style 访问方式
  --part-size=              分片大小，单位为Byte，默认情况下ossutil根据文件大小自行计算合适的分片大小值。如果有特殊需求或者需要性能调优，可以设置该值，取值范围：1-9223372036854775807(Byte)
  --include=                包含对象匹配模式，如：*.jpg
  -t, --sts-token=          访问oss使用的STSToken（该选项值会覆盖配置文件中的相应设置），非必须设置项。
  -b, --bucket              对bucket进行操作，该选项用于确认操作作用于bucket
  --download                表示从oss下载,主要在命令probe中使用
  --timeout=                签名url的超时时间，单位为秒，默认值为：60，取值范围：0-9223372036854775807
  -h, --help                Show usage message
  --version                 Show version

4.2.ossutil 支持命令

mvpbang@mvpbang ~ % ossutil help
用法: ossutil [command] [args...] [options...]
请使用ossutil help command来显示command命令的帮助

Commands:
  mb                cloud_url [options]
        创建Bucket
  ls                [cloud_url] [options]
        列举Buckets或者Objects
  rm                cloud_url [options]
        删除Bucket或Objects
  stat              cloud_url [options]
        显示bucket或者object的描述信息
  set-acl           cloud_url [acl] [options]
        设置bucket或者objects的acl
  set-meta          cloud_url [meta] [options]
        设置已上传的objects的元信息
  cp                src_url dest_url [options]
        上传，下载或拷贝Objects
  restore           cloud_url [local_xml_file] [options]
        恢复冷冻状态的Objects为可读状态
  create-symlink    cloud_url target_url [options]
        创建符号链接
  read-symlink      cloud_url [options]
        读取符号链接文件的描述信息
  sign              cloud_url [meta] [options]
        生成object下载链接
  probe             file_name [options]
        探测命令,支持多种功能探测
  mkdir             dir_name [options]
        创建一个目录,在oss中目录名字有后缀字符'/'
  cors              bucket_url [local_xml_file] [options]
        设置、查询或者删除bucket的cors配置
  logging           src_bucket_url target_bucket_url [options]
        设置、查询或者删除bucket的log配置
  referer           bucket_url referer [options]
        设置、查询或者删除bucket的referer配置
  listpart          oss_object uploadid [options]
        列出没有完成分块上传的object的分块信息
  getallpartsize    bucket_url [options]
        获取bucket所有未完成上传的multipart object的分块大小以及总和
  appendfromfile    local_file_name oss_object [options]
        将本地文件内容以append上传方式上传到oss中的appendable object中
  cat               object [options]
        将文件内容输出到标准输出
  bucket-tagging    bucket_url [tag_parameter] [options]
        设置、查询或者删除bucket的tag配置
  bucket-encryption bucket_url [options]
        设置、查询或者删除bucket的encryption配置
  cors-options      oss_url [options]
        向oss发送http options请求,用于CORS检测
  style             bucket_url [local_xml_file] [style_name] [options]
        添加、查询、删除或者列举bucket的图片样式
  lifecycle         bucket_url local_xml_file [options]
        设置、查询或者删除bucket的lifecycle配置
  website           bucket_url local_xml_file [options]
        设置、查询或者删除bucket的website配置
  bucket-qos        bucket_url [local_xml_file] [options]
        设置、查询或者删除bucket的qos配置
  user-qos          [local_file] [options]
        查询用户的qos配置
  bucket-versioning bucket_url [versioning_parameter] [options]
        设置、查询bucket的versioning配置
  du                bucket_url [options]
        获取bucket或者指定前缀(目录)所占的存储空间大小
  bucket-policy     bucket_url [local_json_file] [options]
        设置、查询或者删除bucket的policy配置
  request-payment   bucket_url [payment_parameter] [options]
        设置、查询bucket的访问者付费配置
  object-tagging    cloud_url [tag_parameter] [options]
        设置、查询或者删除object的tag配置
  inventory         bucket_url [local_xml_file] [id] [options]
        添加、查询、删除或者列举bucket的清单配置
  revert-versioning cloud_url [options]
        将object从删除状态恢复成最近的多版本状态
  sync              src dest [options]
        将本地文件目录或者oss prefix从源端同步到目的端
  worm              command_name bucket_url [days] [wormId] [options]
        设置、删除、修改、提交bucket的Worm配置
  lrb               [conf_file] [options]
        列举某个region下的Buckets
  replication       bucket_url [local_xml_file|ruleID] [options]
        bucket的跨区域同步配置管理
  bucket-cname      bucket_url [options]
        管理bucket cname以及cname token配置
  lcb               [options]
        列举云盒信息
  access-monitor    bucket_url local_xml_file [options]
        设置、查询bucket的access monitor配置
  resource-group    bucket_url local_xml_file [options]
        设置、查询bucket的resource group配置


Additional Commands:
  help              [command]
        获取命令的帮助文档
  config            [options]
        创建配置文件用以存储配置项
  hash              file_url [options]
        计算本地文件的crc64或md5
  update            [options]
        更新ossutil