Back to Details

aliyun-oss-ossutil

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Category: tool
分类：工具

OSS (ossutil 2.0) CLI Skill

OSS（ossutil 2.0）CLI技能

Validation

验证

bash
python skills/storage/oss/aliyun-oss-ossutil/scripts/check_ossutil.py --output output/aliyun-oss-ossutil/validate.txt
Pass criteria: command exits 0 and 
output/aliyun-oss-ossutil/validate.txt
is generated.
bash
python skills/storage/oss/aliyun-oss-ossutil/scripts/check_ossutil.py --output output/aliyun-oss-ossutil/validate.txt
通过标准：命令执行退出码为0，且生成
output/aliyun-oss-ossutil/validate.txt
文件。

Output And Evidence

输出与证据

  • Save command outputs, object listings, and sync logs under 
    output/aliyun-oss-ossutil/
    .
  • Keep at least one upload or listing result as evidence.
  • 将命令输出、对象列表和同步日志保存到
    output/aliyun-oss-ossutil/
    目录下。
  • 保留至少一份上传或列表结果作为证据。

Goals

目标

  • Use ossutil 2.0 to manage OSS: upload, download, sync, and resource management.
  • Provide a unified CLI flow for install, config, credentials, and region/endpoint handling.
  • 使用ossutil 2.0管理OSS：上传、下载、同步及资源管理。
  • 提供安装、配置、凭证及区域/端点处理的统一CLI流程。

Quick Start Flow

快速入门流程

  1. Install ossutil 2.0.
  2. Configure AK/SK and default region (
    ossutil config
    or config file).
  3. Run 
    ossutil ls
    to list buckets, then list objects using the bucket region.
  4. Execute upload/download/sync or API-level commands.
  1. 安装ossutil 2.0。
  2. 配置AK/SK和默认区域（使用
    ossutil config
    命令或配置文件）。
  3. 运行
    ossutil ls
    列出存储桶，然后使用存储桶所在区域列出对象。
  4. 执行上传/下载/同步或API级命令。

Install ossutil 2.0

安装ossutil 2.0

  • See 
    references/install.md
    for platform-specific install steps.
  • 查看
    references/install.md
    获取针对不同平台的安装步骤。

Configure ossutil

配置ossutil

  • Interactive configuration:
bash
ossutil config
  • Default config file paths:
    • Linux/macOS：
      ~/.ossutilconfig
    • Windows：
      C:\Users\issuser\.ossutilconfig
Main configuration fields include:
  • AccessKey ID
  • AccessKey Secret
  • Region
    （example default 
    cn-hangzhou
    ; ask the user if the best region is unclear）
  • Endpoint
    （optional; auto-derived from region if omitted）
  • 交互式配置：
bash
ossutil config
  • 默认配置文件路径：
    • Linux/macOS：
      ~/.ossutilconfig
    • Windows：
      C:\Users\issuser\.ossutilconfig
主要配置字段包括：
  • AccessKey ID
  • AccessKey Secret
  • Region
    （示例默认值为
    cn-hangzhou
    ；若不确定最佳区域，请询问用户）
  • Endpoint
    （可选；若省略则从区域自动推导）

AccessKey configuration notes

AccessKey配置注意事项

Use RAM users/roles with least privilege and avoid passing AK in plain text on command line.
Recommended method (environment variables):
bash
export ALIBABACLOUD_ACCESS_KEY_ID="<your-ak>"
export ALIBABACLOUD_ACCESS_KEY_SECRET="<your-sk>"
export ALIBABACLOUD_REGION_ID="cn-beijing"
ALIBABACLOUD_REGION_ID
can be used as default region; if unset choose the most reasonable region, ask user if unclear.
Or use the standard shared credentials file:
~/.alibabacloud/credentials
ini
[default]
type = access_key
access_key_id = <your-ak>
access_key_secret = <your-sk>
使用具有最小权限的RAM用户/角色，避免在命令行中以明文形式传递AK。
推荐方法（环境变量）：
bash
export ALIBABACLOUD_ACCESS_KEY_ID="<your-ak>"
export ALIBABACLOUD_ACCESS_KEY_SECRET="<your-sk>"
export ALIBABACLOUD_REGION_ID="cn-beijing"
ALIBABACLOUD_REGION_ID
可作为默认区域；若未设置，则选择最合理的区域，若不确定请询问用户。
或者使用标准的共享凭证文件：
~/.alibabacloud/credentials
ini
[default]
type = access_key
access_key_id = <your-ak>
access_key_secret = <your-sk>

Command structure (2.0)

命令结构（2.0版本）

  • High-level command example:
    ossutil config
  • API-level command example:
    ossutil api put-bucket-acl
  • 高级命令示例：
    ossutil config
  • API级命令示例：
    ossutil api put-bucket-acl

Common command examples

常用命令示例

bash
ossutil ls
ossutil ls oss://your-bucket -r --short-format --region cn-shanghai -e https://oss-cn-shanghai.aliyuncs.com
ossutil cp ./local.txt oss://your-bucket/path/local.txt
ossutil cp oss://your-bucket/path/remote.txt ./remote.txt
ossutil sync ./local-dir oss://your-bucket/path/ --delete
bash
ossutil ls
ossutil ls oss://your-bucket -r --short-format --region cn-shanghai -e https://oss-cn-shanghai.aliyuncs.com
ossutil cp ./local.txt oss://your-bucket/path/local.txt
ossutil cp oss://your-bucket/path/remote.txt ./remote.txt
ossutil sync ./local-dir oss://your-bucket/path/ --delete

Recommended execution flow (list buckets first, then objects)

推荐执行流程（先列出存储桶，再列出对象）

  1. List all buckets
bash
ossutil ls
  1. Get target bucket region from output (e.g. 
    oss-cn-shanghai
    ) and convert it to 
    --region
    format (
    cn-shanghai
    ).
  2. When listing objects, explicitly set 
    --region
    and 
    -e
    to avoid cross-region signature/endpoint errors.
bash
ossutil ls oss://your-bucket \
  -r --short-format \
  --region cn-shanghai \
  -e https://oss-cn-shanghai.aliyuncs.com
  1. For very large buckets, limit output size first.
bash
ossutil ls oss://your-bucket --limited-num 100
ossutil ls oss://your-bucket/some-prefix/ -r --short-format --region cn-shanghai -e https://oss-cn-shanghai.aliyuncs.com
  1. 列出所有存储桶
bash
ossutil ls
  1. 从输出中获取目标存储桶的区域（例如
    oss-cn-shanghai
    ），并转换为
    --region
    参数格式（
    cn-shanghai
    ）。
  2. 列出对象时，显式设置
    --region
    和
    -e
    参数，以避免跨区域签名/端点错误。
bash
ossutil ls oss://your-bucket \
  -r --short-format \
  --region cn-shanghai \
  -e https://oss-cn-shanghai.aliyuncs.com
  1. 对于超大存储桶，先限制输出大小。
bash
ossutil ls oss://your-bucket --limited-num 100
ossutil ls oss://your-bucket/some-prefix/ -r --short-format --region cn-shanghai -e https://oss-cn-shanghai.aliyuncs.com

Common errors and handling

常见错误及处理方法

  • Error: region must be set in sign version 4.
    • Cause: missing region configuration.
    • Fix: add 
      region
      in config file, or pass 
      --region cn-xxx
      .
  • The bucket you are attempting to access must be addressed using the specified endpoint
    • Cause: request endpoint does not match bucket region.
    • Fix: use endpoint of the bucket region, e.g. 
      -e https://oss-cn-hongkong.aliyuncs.com
      .
  • Invalid signing region in Authorization header
    • Cause: signature region does not match bucket region.
    • Fix: correct both 
      --region
      and 
      -e
      ; both must match bucket region.
  • Error: region must be set in sign version 4.
    • 原因：缺少区域配置。
    • 解决方法：在配置文件中添加
      region
      ，或传递
      --region cn-xxx
      参数。
  • The bucket you are attempting to access must be addressed using the specified endpoint
    • 原因：请求端点与存储桶区域不匹配。
    • 解决方法：使用存储桶所在区域的端点，例如
      -e https://oss-cn-hongkong.aliyuncs.com
      。
  • Invalid signing region in Authorization header
    • 原因：签名区域与存储桶区域不匹配。
    • 解决方法：修正
      --region
      和
      -e
      参数，两者必须与存储桶区域匹配。

Credential and security guidance

凭证与安全指南

  • Prefer RAM user AK for access control.
  • CLI options can override config file, but passing secrets on command line has leakage risk.
  • In production, manage secrets via config files or environment variables.
  • 优先使用RAM用户AK进行访问控制。
  • CLI选项可以覆盖配置文件，但在命令行中传递密钥存在泄露风险。
  • 生产环境中，通过配置文件或环境变量管理密钥。

Clarifying questions (ask when uncertain)

需要澄清的问题（不确定时询问）

  1. Is your target a Bucket or an Object?
  2. Do you need upload/download/sync, or management actions like ACL/lifecycle/CORS?
  3. What are the target region and endpoint?
  4. Are you accessing OSS from ECS in the same region (intranet endpoint may be preferred)?
  1. 您的操作目标是存储桶还是对象？
  2. 您需要进行上传/下载/同步操作，还是ACL/生命周期/CORS等管理操作？
  3. 目标区域和端点是什么？
  4. 您是否从同一区域的ECS访问OSS（可能优先使用内网端点）？

References

参考资料

Prerequisites

前置条件

  • Configure least-privilege Alibaba Cloud credentials before execution.
  • Prefer environment variables: 
    ALIBABACLOUD_ACCESS_KEY_ID
    , 
    ALIBABACLOUD_ACCESS_KEY_SECRET
    , optional 
    ALIBABACLOUD_REGION_ID
    .
  • If region is unclear, ask the user before running mutating operations.
  • 执行前配置具有最小权限的阿里云凭证。
  • 优先使用环境变量：
    ALIBABACLOUD_ACCESS_KEY_ID
    、
    ALIBABACLOUD_ACCESS_KEY_SECRET
    ，可选
    ALIBABACLOUD_REGION_ID
    。
  • 若区域不明确，在执行变更操作前询问用户。

Workflow

工作流程

  1. Confirm user intent, region, identifiers, and whether the operation is read-only or mutating.
  2. Run one minimal read-only query first to verify connectivity and permissions.
  3. Execute the target operation with explicit parameters and bounded scope.
  4. Verify results and save output/evidence files.
  1. 确认用户意图、区域、标识符，以及操作是只读还是变更类型。
  2. 先执行一个最小化的只读查询，验证连通性和权限。
  3. 使用明确的参数和限定范围执行目标操作。
  4. 验证结果并保存输出/证据文件。