ossutil 实用指南

阿里云 OSS 自带 Web 控制台，但凡涉及批量上传、断点续传、跨地域同步，鼠标点几下就显得力不从心——这种场景下 ossutil 几乎是唯一选择。

ossutil 是 OSS 官方命令行工具，跨平台单二进制发行，没有 Python/Java 运行时依赖，CI/CD 流水线里直接 curl 拉下来就能用。2026 年官方主推 ossutil 2.0，最新稳定版迭代到 2.3.x，与 1.0 的差别比单纯版本号要大得多：底层签名升到 V4 强制要求 region、命令树彻底重构、连二进制名都从 ossutil64 改成了 ossutil。这些变化在动手前都值得过一遍。

安装与初始化配置

v2 的安装包按 OS × 架构组合发布在 gosspublic.alicdn.com/ossutil/v2/<版本>/ 下。Linux 与 macOS 一般直接 curl 拉 zip 解压，把可执行文件丢进 /usr/local/bin/；Windows 解压后把目录加进 Path 环境变量。装完跑 ossutil version 确认能调起来，老脚本里如果还写着 ossutil64，要么改名、要么先建个符号链接过渡再批量替换。

初始化走 ossutil config 进交互向导，依次问 Endpoint、Region、AccessKey ID、AccessKey Secret、可选的 STSToken。v2 把 region 提到必填位置是因为底层签名算法升到了 V4——这一步偷懒置空，会在第一次实际操作时被 InvalidArgument 直接打回来。Endpoint 可以不填，给了 region 之后默认走 oss-<region>.aliyuncs.com 的公网域名；同地域内网访问要手动写成 oss-<region>-internal.aliyuncs.com，省下来的是真金白银的公网带宽费。

配置文件默认落在 ~/.ossutilconfig，是 INI 格式，按 section 分多个 profile。日常单账号够用，但凡涉及”测试 bucket 与生产 bucket 在不同账号下”或”国内 + 海外两套 AK”的场景，多 profile 就成刚需，用 --profile <name> 切换比改环境变量优雅得多。配置优先级从高到低是命令行参数（-i/-k/-e）→ 环境变量（OSS_ACCESS_KEY_ID 等）→ 配置文件，CI 脚本一般用环境变量注入，本地交互式操作用配置文件。

不要把 AccessKey 写进命令行

ossutil -i AK -k SK ls oss://... 这种写法虽然能跑，但 shell history、CI 日志、ps 输出都会留底。生产凭证只走环境变量或配置文件，临时调试可以用 --profile 切到只读的子账号身份，比图省事更安全。

日常操作：cp / ls / rm / mv

通用语法是 ossutil <命令> <源> <目的>，OSS 路径以 oss://bucket/key 形式表达，本地路径可相对可绝对。贯穿所有命令的三个旗标是 -r（递归，处理目录必带）、-f（跳过覆盖确认，脚本里几乎必带）、-u（增量模式，按修改时间和大小判断要不要重传）。多线程靠 -j N 控制并发数，默认 5，传大文件夹时拉到 16 甚至 32 都没问题，瓶颈一般是出口带宽不是 CPU。

列举操作里，ossutil ls 不带参数列出当前账号所有 bucket，ossutil ls oss://my-bucket 列对象，带前缀的 ossutil ls oss://my-bucket/logs/ 等价于 prefix 查询。看单个对象的元信息用 ossutil stat oss://bucket/key，能拿到 size、ETag、storage class、修改时间，排查”为啥这个文件下载下来不对”经常从这一步开始。

上传下载都是 cp，方向完全由路径决定：

ossutil cp ./local-dir oss://my-bucket/backup/ -rf -j 16    # 上传整目录
ossutil cp oss://my-bucket/backup/ ./local-dir -rf -j 16    # 反过来下载
ossutil cp oss://src-bucket/a.zip oss://dst-bucket/b.zip    # OSS 之间直接拷贝，不落本地

OSS 之间的拷贝走内部网络，速度比”先下载再上传”快一两个数量级，跨账号迁移时尤其香。删除用 rm，-r 递归、-f 跳过确认，ossutil rm -rf oss://bucket/path/ 直接清掉整个前缀下的对象——这条命令没有回收站，跑之前一定再确认一遍 path 后缀的斜杠位置。mv 在 OSS 里本质上是 server-side copy + delete，没有真正的”移动”原语，对超大对象会瞬时计费两份存储，但耗时只取决于 metadata 操作，不需要重传数据。

sync：v2 真正值得用的新命令

老版本里”增量上传同步”是靠 cp -ru 模拟的，对比逻辑只看修改时间，删源不删目的端。v2 引入了独立的 sync 命令，行为更接近 rsync，把双向状态对齐做成了一等公民：

ossutil sync ./local-dir oss://my-bucket/backup/ --delete -j 16    # 镜像同步，目的端多余对象会被删
ossutil sync oss://src/ oss://dst/ --snapshot-path ./snap.db       # 用本地快照加速二次同步

--delete 让目的端镜像源端，多余对象会被删除——这是 cp -ru 做不到的。--snapshot-path 把上一次同步的状态写进本地快照文件，第二次跑时直接对比快照而不是回查 OSS，对象量大的目录能省下大量 list 请求成本。大文件超过 100 MB 自动走断点续传，checkpoint 存在 .ossutil_checkpoint/ 目录，跑一半被 Ctrl+C 掐掉，重跑就从中断点继续，不会从头再来。

性能调优的关键是分清 --job 和 --parallel：前者控制同时处理多少个对象，后者控制单个大文件的分片并发。海量小文件场景把 --job 调高（32-64），少量大文件场景把 --parallel 调高（16+），混合场景两个都拉满。带宽打不满之前，瓶颈往往就在这两个数值上而不是网络本身。

单次同步上限

带 --delete 的 sync 单次最多处理 100 万个对象，超过会报 over max sync numbers 1000000。超大目录要按前缀分批跑，或者改走 OSS 服务端的批量操作 API。

v2 的其他几项新能力

命令树拆成了高级命令（cp/ls/rm/sync 这些贴近用户意图的封装）和 API 级命令（ossutil api put-bucket-acl、ossutil api get-object-meta 这类直通底层 REST API 的形式）。前者用着舒服但抽象掉了细节，后者参数与官方 API 文档一一对应，写跨语言迁移脚本、或者排查”高级命令为啥这么响应”时更可控。辅助命令则覆盖配置文件管理、版本检查这些杂事。

--output-format json / yaml / xml 能把任意命令的输出切到结构化格式，配合 --output-query 像 JMESPath 一样筛字段，几乎不用再起 awk/grep 拼管道：

ossutil ls oss://my-bucket --output-format json \
  --output-query "objects[?size > '1048576'].{key:key, size:size}"

过滤器也是 v2 的发力点，cp/ls/rm 全都支持 --include/--exclude 通配，还能按大小、按修改时间、按对象元数据筛。“删掉超过 30 天没访问过、且大于 100 MB 的 log 文件”这种过去要写小脚本的需求，现在一条命令就能表达。--dry-run 在 v2 也是一等公民，所有写操作都能空跑一遍看影响范围，配合 --output-format json 还能把”将要发生什么”序列化下来当审计日志，生产环境第一次跑 --delete 同步之前过一遍 --dry-run 永远不亏。

返回码也做了标准化，非零返回码按出错阶段编码，CI 脚本里据此分支处理比 grep stderr 文本可靠得多。客户端时钟与服务端偏差超过 15 分钟时会触发 RequestTimeTooSkewed，v2 检测到后会自动校时再重试，这对 CI runner 这种 clock 经常飘的环境算是一个隐形的好处。

几个容易踩的点

OSS 路径区分大小写：oss://bucket/Photo.jpg 和 oss://bucket/photo.jpg 是两个对象，从 Linux 大小写敏感文件系统迁移的数据要特别小心，从 Windows 上传则反过来可能在源端就把大小写信息丢了。路径里不需要引号，但目录写法要带斜杠——oss://bucket/dir 是个对象 key，oss://bucket/dir/ 才是前缀，这对 ls 列出来的结果和 rm -r 的删除范围都有决定性影响。

v1 二进制名带 64 后缀，v2 改成了平台无关的 ossutil，老脚本升级时别只换版本不换命令名，否则一跑就是 command not found。Region 必填这点在第一次切到 v2 时是最常见的卡点，新建 bucket 时把所在地域记下来，配置时一次填好，省得后面每条命令都报签名错误。

ossutil config                                # 进配置向导
ossutil ls oss://bucket                       # 列对象
ossutil cp ./dir oss://bucket/ -rf -j 16      # 上传目录
ossutil cp oss://bucket/ ./dir -rf -j 16      # 下载目录
ossutil sync ./dir oss://bucket/ --delete     # 双向同步（镜像）
ossutil rm oss://bucket/path/ -rf             # 递归删除前缀
ossutil stat oss://bucket/key                 # 查对象元信息

日常 80% 的工作量都在 cp、ls、rm、sync 四个命令上，记住 -r/-f/-u/-j 四个旗标和 --profile 切账号，剩下的复杂度在 ossutil --help 与 ossutil <cmd> --help 里现查现用即可。

• -r / --recursive 递归
• -f / --force 强制覆盖、无需确认
• -u / --update 更新模式（只传新文件）
• -j N / --parallel N 并发线程数

全面指南

一、基础介绍

ossutil 是阿里云官方OSS命令行工具，支持Windows/macOS/Linux，用于上传、下载、列举、删除、权限管理、批量同步、分片上传等操作。 配置文件默认路径：

• Linux/macOS root用户：/root/.ossutilconfig
• 普通用户：~/.ossutilconfig

配置文件格式（多profile区分多账号）

[profile default]
endpoint = oss-cn-shanghai.aliyuncs.com
accessKeyID = LTAIxxxx
accessKeySecret = xxxxxxxx
language = CH
 
[profile mm-group-image]
endpoint = oss-cn-xxx.aliyuncs.com
accessKeyID = LTAIxxxx
accessKeySecret = xxxxxxxx
language = CH

• [profile xxx]：独立账号分组，操作时用 --profile xxx 指定切换账号
• default：不指定--profile时默认使用的账号配置

安全规范

配置文件密钥不可对外可读，必须限制权限：

chmod 600 /root/.ossutilconfig

二、安装与初始化

1. 初始化配置（交互式生成config）

# 生成default账号
ossutil config
# 生成自定义profile账号
ossutil config --profile mm-group-image

按提示依次输入：Endpoint、AccessKeyID、AccessKeySecret。

2. 查看所有已配置账号

ossutil config list-profiles

3. 直接读取指定配置文件（非默认路径）

ossutil ls oss://bucket -c /xxx/ossconfig --profile mm-group-image

三、全局通用参数（所有命令均可携带）

参数	作用
--profile xxx	指定使用配置里的账号分组（核心，你当前mm-group-image必用）
-c /path/config	自定义配置文件路径
--language CH/EN	输出中文/英文日志
--retry-times N	失败重试次数，默认3
--quiet	静默输出，只打印错误
--force	覆盖文件、强制删除不弹窗确认

四、桶(Bucket)管理操作

1. 列出当前账号下全部Bucket

ossutil ls --profile mm-group-image

2. 创建Bucket

ossutil mb oss://new-bucket --profile mm-group-image

3. 删除空Bucket（桶内必须无文件）

ossutil rb oss://new-bucket --profile mm-group-image

4. 查看Bucket基础信息

ossutil stat oss://mm-group-image --profile mm-group-image

5. 获取Bucket ACL（桶公开权限，你之前执行过）

ossutil api get-bucket-acl --bucket mm-group-image --profile mm-group-image

返回三种状态：

• private：私有，仅AK可访问（当前你的桶状态）
• public-read：所有人可读，仅AK可写
• public-read-write：全公开读写，极度危险

6. 设置Bucket ACL

# 设为私有
ossutil api put-bucket-acl --bucket mm-group-image --acl private --profile mm-group-image

7. 查看/修改桶访问策略 Bucket Policy

# 获取Policy
ossutil bucket-policy --method get oss://mm-group-image --profile mm-group-image
# 设置Policy（传入本地json文件）
ossutil bucket-policy --method put oss://mm-group-image policy.json --profile mm-group-image
# 删除Policy
ossutil bucket-policy --method delete oss://mm-group-image --profile mm-group-image

五、列举文件/文件夹 ls（高频核心命令）

基础语法：ossutil ls oss://bucket/路径 [参数] --profile xxx

常用参数

• -r：递归遍历所有子目录
• -d：只展示文件夹，过滤普通文件（你需求用到）
• -l：长列表，展示文件大小、修改时间、存储类型
• --marker "前缀"：分页查询，跳过前面内容
• --limit N：限制单次输出数量

示例

1. 只看桶根一级文件夹

ossutil ls oss://mm-group-image -d --profile mm-group-image

2. 递归所有层级文件夹

ossutil ls oss://mm-group-image -d -r --profile mm-group-image

3. 过滤文件夹名称≤15字符

ossutil ls oss://mm-group-image -d -r --profile mm-group-image | awk -F '/' '{sub(/\/$/,"",$NF);if(length($NF) <= 15) print $0}'

4. 导出全部文件清单到本地文本

ossutil ls oss://mm-group-image -r -l --profile mm-group-image > oss_list.txt

六、文件上传 cp

语法：ossutil cp 本地路径 oss://bucket/oss路径 [参数]

常用参数

• -r：上传文件夹（批量）
• --check-md5：上传前校验本地md5，避免传错
• --parallel N：并发线程，大文件加速
• --meta key=val：自定义文件元数据

示例

1. 单个文件上传

ossutil cp test.jpg oss://mm-group-image/img/ --profile mm-group-image

2. 整个本地文件夹批量上传

ossutil cp /workspace/images oss://mm-group-image/img/ -r --profile mm-group-image

3. 强制覆盖已存在文件

ossutil cp test.jpg oss://mm-group-image/img/ --force --profile mm-group-image

七、文件下载 cp

语法：ossutil cp oss://bucket/oss路径 本地路径 [参数]

示例

1. 单文件下载

ossutil cp oss://mm-group-image/img/a.jpg ./local/ --profile mm-group-image

2. 下载整个OSS目录到本地

ossutil cp oss://mm-group-image/img/ ./local_img/ -r --profile mm-group-image

八、同步同步 sync（增量同步，只传新增/修改文件）

适合大规模数据集、模型权重同步，对比本地与OSS文件差异，跳过相同文件。

本地 → OSS

ossutil sync /workspace/ckpt oss://mm-group-image/ckpt/ --profile mm-group-image

OSS → 本地

ossutil sync oss://mm-group-image/ckpt/ ./local_ckpt --profile mm-group-image

九、删除文件/文件夹 rm

参数

• -r：递归删除目录
• --force：不弹窗确认，直接删除（生产慎用）

示例

1. 删除单个文件

ossutil rm oss://mm-group-image/test.tmp --profile mm-group-image

2. 清空整个文件夹

ossutil rm oss://mm-group-image/tmp/ -r --force --profile mm-group-image

十、文件元数据、权限管理

1. 查看单个文件详情

ossutil stat oss://mm-group-image/img/a.jpg --profile mm-group-image

2. 设置单个文件公开读权限

ossutil set-acl oss://mm-group-image/img/a.jpg public-read --profile mm-group-image

3. 文件私有（默认）

ossutil set-acl oss://mm-group-image/img/a.jpg private --profile mm-group-image

十一、分片上传（超大文件 >100MB 自动分片）

ossutil cp/sync 默认自动分片，无需手动操作；手动分片命令：

# 生成分片任务
ossutil multipart-init oss://mm-group-image/large.zip --profile mm-group-image
# 列出未完成分片
ossutil multipart-list oss://mm-group-image/large.zip --profile mm-group-image
# 清理失败残留分片（释放存储空间）
ossutil multipart-abort oss://mm-group-image/large.zip --profile mm-group-image

十二、文件拷贝/跨桶移动

同桶内复制文件

ossutil cp oss://mm-group-image/a.jpg oss://mm-group-image/bak/a.jpg --profile mm-group-image

移动文件（剪切）

ossutil mv oss://mm-group-image/tmp/a.jpg oss://mm-group-image/img/ --profile mm-group-image

十三、生成临时访问URL（私有文件外网临时下载）

私有桶文件无法直接外网访问，生成带时效签名链接：

# 有效期3600秒（1小时）
ossutil sign oss://mm-group-image/img/a.jpg 3600 --profile mm-group-image

十四、批量过滤高级用法（搭配管道awk/grep）

1. 只展示jpg图片

ossutil ls oss://mm-group-image/img -r --profile mm-group-image | grep ".jpg"

2. 筛选路径包含train的文件夹

ossutil ls oss://mm-group-image -d -r --profile mm-group-image | grep "train"

3. 删除所有tmp临时文件

ossutil ls oss://mm-group-image/tmp -r --profile mm-group-image | awk '{print $1}' | xargs -I {} ossutil rm {} --force --profile mm-group-image

十五、权限分层完整说明（重点区分）

1. Bucket ACL（桶公开权限，get-bucket-acl查询）

控制匿名游客能否访问桶，当前你的桶为private，外网无AK完全无法访问。

2. RAM账号权限（AK所属子账号/主账号）

决定你mm-group-image这个profile的AK能执行哪些操作：ls/cp/rm/修改policy等。 ossutil无法直接查看RAM后台策略，只能通过命令自测权限：

• 能ls=具备ListObjects读列表权限
• 能cp上传=具备PutObject写权限
• 能rm删除=具备DeleteObject权限
• get-bucket-policy报错=无桶策略管理权限 完整RAM策略只能登录阿里云RAM网页控制台查看。

3. Bucket Policy

桶侧二次精细化授权，可限制其他账号/IP访问本桶。

十六、常见报错排查

1. NoSuchProfile：配置文件不存在mm-group-image，执行config list-profiles核对名称
2. AccessDenied：RAM账号无对应操作权限，或AK密钥错误
3. NoSuchBucket：桶名拼写错误，或当前账号无该桶访问权限
4. 配置文件权限告警：执行chmod 600 /root/.ossutilconfig
5. 文件无法覆盖：缺少--force参数