阿
阿里OSS
作者：鹿Sir开发工具v1
阿里云OSS命令行工具(ossutil 2.0)技能。支持多Bucket配置、凭证管理、自动安装检测、文件上传下载、目录同步、目录结构查看。触发词：OSS、阿里云、对象存储、ossutil、文件上传、文件下载、存储桶管理、目录结构
下载量
381
点赞
96
价格
¥2.99
精选
技能文档
---
name: ali-oss
description: 阿里云OSS命令行工具(ossutil 2.0)技能。支持多Bucket配置、凭证管理、自动安装检测、文件上传下载、目录同步、目录结构查看。触发词：OSS、阿里云、对象存储、ossutil、文件上传、文件下载、存储桶管理、目录结构
title: 阿里OSS
category: 工具
---
# 阿里云 OSS 工具
通过 `oss_cli.py` 统一管理配置和执行 ossutil 命令，支持自动安装、自动加载配置。
## 快速使用
```bash
# 列出存储空间（自动检测安装、自动加载配置）
export PATH=$HOME/bin:$PATH # 如果 ossutil 安装到 ~/bin
python3 scripts/oss_cli.py ls
# 上传文件
python3 scripts/oss_cli.py cp ./local.txt oss://your-bucket/path/local.txt
# 下载文件
python3 scripts/oss_cli.py cp oss://your-bucket/path/remote.txt ./remote.txt
# 同步目录
python3 scripts/oss_cli.py sync ./local-dir oss://your-bucket/path/
# 使用指定 Bucket
python3 scripts/oss_cli.py --env your-bucket ls
```
> 也可以直接使用 `ossutil` 命令（需手动安装）
> 详细参数说明见下方 [常用命令](#常用命令)
## 核心操作
### 智能上传工具（交互式目录选择）
使用 `smart_upload.py` 上传文件，支持**交互式目录选择**：
```bash
# 交互式上传（推荐）- 自动打开目录选择器
# 默认从配置文件 (~/.config/ali-oss/config.json) 读取当前 bucket
python3 scripts/smart_upload.py ./photo.jpg
# 或指定 bucket
python3 scripts/smart_upload.py ./photo.jpg -b oss://your-bucket
# 指定目录上传（跳过交互）
python3 scripts/smart_upload.py ./photo.jpg --dir assets -b oss://your-bucket
```
**工作流程**：
```
1. 验证文件并计算总大小
2. 打开交互式目录选择器（同时显示待上传文件列表）
3. 用户递归浏览目录树（数字选择、返回、确认）
4. 用户确认目标目录（二次确认）
5. 如有冲突文件，终端内询问处理策略（覆盖/跳过/逐个确认）
6. TUI 进度条显示上传进度，每个文件仅显示 ✓/✗ 状态
7. 上传完成后输出 JSON 结果（包含在 <!-- UPLOAD_RESULT_JSON ... --> 标记中）
```
**重要原则**：
- ✅ **所有确认逻辑都在终端中完成**，LLM 无需在对话中询问用户
- ✅ LLM 直接执行上传命令，用户会在终端中看到交互式界面并完成所有确认
- ✅ 上传时不指定 `--dir` 参数，自动打开终端交互式选择器
- ✅ 指定 `--dir` 参数，跳过交互直接上传到指定目录
- ⛔ **LLM 禁止在对话中列出目录选项让用户选择**
- ⛔ **LLM 禁止在对话中询问确认信息**（文件确认、目录选择、冲突处理等都在终端中完成）
### 统一工具（配置管理 + 命令执行）
使用 `oss_cli.py` 统一管理配置和执行命令：
```bash
# 配置管理
python3 scripts/oss_cli.py --init # 交互式配置
python3 scripts/oss_cli.py --list # 列出所有 Bucket
python3 scripts/oss_cli.py --env your-bucket show # 显示 Bucket 配置
python3 scripts/oss_cli.py --env your-bucket test # 测试连接
# 命令执行（自动安装 + 自动加载配置）
python3 scripts/oss_cli.py ls
python3 scripts/oss_cli.py --env your-bucket ls
```
**自动处理**：
- ✅ 检测 ossutil 是否安装
- ✅ 自动安装 ossutil（macOS/Linux）
- ✅ 自动加载配置文件
- ✅ 自动设置环境变量
- ✅ 统一错误处理
- ✅ 5分钟超时保护
### 直接使用 ossutil
如果已手动安装 ossutil，可以直接使用：
```bash
ossutil ls
```
## 首次使用配置
首次使用 OSS 工具时,需要配置 AccessKey 凭证。如果没有配置,执行命令时会提示错误,此时按以下步骤配置。
### 配置方式
**重要说明**: 脚本会自动将配置同步到 `~/.ossutilconfig` 文件,ossutil 直接读取该文件。
#### 方式一：使用配置向导（推荐）
```bash
python3 scripts/oss_cli.py --init
```
按提示输入:
- Bucket 名称 (如: my-bucket)
- AccessKey ID
- AccessKey Secret
- 区域(如:cn-hangzhou)
- Endpoint 类型(1:公网 2:内网 3:加速)
- STS Token(可选)
配置会保存到 `~/.config/ali-oss/config.json`,并在执行命令时自动同步到 `~/.ossutilconfig`。
#### 方式二：手动提供配置信息
按以下格式提供配置信息:
```
Bucket 名称: my-bucket
AccessKey ID: LTAI5t...
AccessKey Secret: abc123...
区域: cn-hangzhou
Endpoint类型: 1（1:公网 2:内网 3:加速）
STS Token: （可选，留空则不填）
```
收到配置信息后,我会自动写入配置文件。
## 配置管理命令
```bash
# 列出所有配置 Bucket
python3 scripts/oss_cli.py --list
# 查看指定 Bucket 配置
python3 scripts/oss_cli.py --env your-bucket show
# 测试连接
python3 scripts/oss_cli.py --env your-bucket test
# 切换当前 Bucket
python3 scripts/oss_cli.py --env your-bucket switch
# 生成环境变量文件
python3 scripts/oss_cli.py --env your-bucket gen-env -o .env
# 使用指定配置文件
python3 scripts/oss_cli.py --config ./my-config.json --list
```
## 安全要求
| Bucket 类型 | 凭证管理方式 | 禁止行为 |
|------|-------------|----------|
| 开发 Bucket | 环境变量或配置文件 | 命令行明文传递密钥 |
| 生产 Bucket | STS 临时凭证或 RAM Role | 使用主账号 AK |
| 所有 Bucket | RAM用户AK最小权限 | 日志输出凭证信息 |
**推荐凭证类型**（按安全性排序）：
1. ✅ **RAM Role / 实例角色**（最安全，无需管理凭证）
2. ✅ **STS 临时凭证**（短期有效，自动过期）
3. ✅ **RAM 子账号 AK**（长期有效，需定期轮换）
4. ❌ **主账号 AK**（禁止使用）
## 自动错误处理
### oss_cli.py 自动处理
| 问题 | 自动处理 |
|------|----------|
| `ossutil` 未安装 | **自动安装**（macOS/Linux） |
| 配置文件不存在 | 提示运行 `oss_config.py --init` |
| 凭证无效 | 显示详细错误信息 |
| 区域不匹配 | 提示正确区域配置 |
| 端点错误 | 显示端点推导规则 |
| 命令超时 | 5分钟超时自动中断 |
### 常见错误
| 错误信息 | 原因 | 解决方法 |
|----------|------|----------|
| `region must be set in sign version 4` | 缺少区域配置 | 运行 `oss_cli.py --init` 配置 |
| `The bucket you are attempting to access must be addressed using the specified endpoint` | 端点不匹配 | 检查 `--region` 和 `-e` 参数 |
| `Invalid signing region in Authorization header` | 签名区域错误 | 修正 `--region` 和 `-e` |
## 脚本说明
### oss_cli.py 参数说明
| 参数 | 说明 | 示例 |
|------|------|------|
| `--init` | **初始化配置**（交互式配置向导） | `--init` |
| `--init-template` | **显示配置模板**（非交互式） | `--init-template` |
| `--list` | 列出所有配置 Bucket | `--list` |
| `--env, -e` | 指定 Bucket 名称 | `--env your-bucket` |
| `--config, -c` | 配置文件路径 | `--config /path/to/config.json` |
| `--output, -o` | 输出文件路径 | `-o .env` |
| `--no-auto-install` | 禁用自动安装 | `--no-auto-install` |
| `--endpoint-type` | Endpoint 类型 (1:公网 2:内网 3:加速) | `--endpoint-type 2` |
| `action` | 操作类型 | `show/test/switch/gen-env` |
| `command` | ossutil 命令及参数 | `ls`, `cp file.txt oss://bucket/` |
**使用示例**：
```bash
# 配置管理
python3 scripts/oss_cli.py --init-template # 非交互式配置
python3 scripts/oss_cli.py --list # 列出所有 Bucket
python3 scripts/oss_cli.py --env your-bucket show # 显示 Bucket 配置
python3 scripts/oss_cli.py --env your-bucket test # 测试连接
python3 scripts/oss_cli.py --env your-bucket switch # 切换 Bucket
python3 scripts/oss_cli.py --env your-bucket gen-env -o .env # 生成环境变量文件
# 命令执行（自动安装 + 自动加载配置）
python3 scripts/oss_cli.py ls # 列出存储空间
python3 scripts/oss_cli.py cp ./file.txt oss://bucket/path/ # 上传文件
python3 scripts/oss_cli.py sync ./dir oss://bucket/path/ # 同步目录
python3 scripts/oss_cli.py --env your-bucket ls # 使用指定 Bucket
```
## 命令结构(2.0版本)
- 高级命令示例：`ossutil config`
- API级别命令示例：`ossutil api put-bucket-acl`
## 常用命令
> 以下命令可以使用 `oss_cli.py` 代理执行（推荐），也可以直接使用 `ossutil`
### 列出存储空间
```bash
# 使用代理脚本（推荐）
python3 scripts/oss_cli.py ls
# 直接使用 ossutil
ossutil ls
```
### 上传/下载/同步
```bash
# 上传文件
python3 scripts/oss_cli.py cp ./local.txt oss://your-bucket/path/local.txt
# 下载文件
python3 scripts/oss_cli.py cp oss://your-bucket/path/remote.txt ./remote.txt
# 同步目录
python3 scripts/oss_cli.py sync ./local-dir oss://your-bucket/path/
```
### 列出对象
```bash
# 列出存储空间对象（需要指定区域）
python3 scripts/oss_cli.py ls oss://your-bucket \
-r --short-format \
--region cn-shanghai \
-e https://oss-cn-shanghai.aliyuncs.com
# 限制输出数量
python3 scripts/oss_cli.py ls oss://your-bucket --limited-num 100
```
### 查看 Bucket 目录结构
#### 方式一：快速查看一级目录（推荐）
使用 `quick_list_dirs.sh` 快速查看 bucket 的一级目录列表（**秒级响应**）：
```bash
# 快速查看一级目录（自动从配置文件读取 bucket）
bash scripts/quick_list_dirs.sh
# 使用自定义 bucket
OSS_BUCKET=oss://your-bucket bash scripts/quick_list_dirs.sh
```
**特点**：
- ⚡ **快速**：使用 `ossutil -d` 参数，直接获取目录前缀，无需递归扫描
- 📊 **清晰**：表格化展示，自动分类目录用途
- 🎯 **准确**：只列出一级目录，避免信息过载
- 💡 **智能**：根据目录名称自动推测用途（应用/图片/前端/数据等）
**输出示例**：
```
✅ 找到 N 个一级目录
┌──────┬──────────────────────────────┬──────────────────────────────────────┐
│ 序号 │ 目录名称 │ 说明 │
├──────┼──────────────────────────────┼──────────────────────────────────────┤
│ 1 │ app/ │ │
│ 2 │ assets/ │ │
│ 3 │ dist/ │ │
│ ... │ ... │ ... │
└──────┴──────────────────────────────┴──────────────────────────────────────┘
```
#### 方式二：多级目录树（分层查询）
使用 `list_dirs_tree.sh` 查看多级目录结构（**推荐 2-3 层**）：
```bash
# 查看 2 层目录（默认）
bash scripts/list_dirs_tree.sh 2
# 查看 3 层目录
bash scripts/list_dirs_tree.sh 3
# 使用自定义 bucket
OSS_BUCKET=oss://your-bucket bash scripts/list_dirs_tree.sh 2
```
```bash
# 查看 bucket 根目录
export ALICLOUD_ACCESS_KEY_ID="<your-ak>"
export ALICLOUD_ACCESS_KEY_SECRET="<your-sk>"
export ALICLOUD_REGION_ID="<region>"
ossutil ls oss://your-bucket/ --region <region> -e https://oss-<region>.aliyuncs.com -d
# 查看特定目录
ossutil ls oss://your-bucket/images/ --region <region> -e https://oss-<region>.aliyuncs.com -d
```
**目录结构示例表格**：
| 目录路径 | 类型 | 说明 | 典型内容 |
|---------|------|------|----------|
| `assets/` | 目录 | 资源文件 | 图片(`.jpg`, `.png`)、视频(`.mp4`) |
| `images/` | 目录 | 图片资源 | 用户上传的图片文件 |
| `uploads/` | 目录 | 上传文件 | 用户提交的文件 |
| `data/` | 目录 | 数据文件 | `.csv`, `.json`, `.xlsx` |
| 根目录 | 文件 | 配置文件 | `.txt`, `.json`, 配置文件 |
## 推荐执行流程
### 查看目录结构
1. **快速查看一级目录**（推荐）
```bash
bash scripts/quick_list_dirs.sh
```
2. **查看特定目录的子目录**
```bash
bash scripts/list_dirs_tree.sh 2 # 查看2层
```
### 文件操作流程
#### 单个文件上传
1. 使用交互式上传（推荐）
```bash
python3 scripts/smart_upload.py ./文件路径
```
- 自动显示文件信息
- 打开交互式目录选择器
- 用户选择并确认目录
- 自动上传
2. 或直接上传到指定目录（跳过交互）
```bash
python3 scripts/smart_upload.py ./文件路径 --dir 目录名 -b oss://bucket名
```
#### 多个文件上传（批量）
**支持交互式选择目录！所有确认在终端中完成！**
1. 交互式批量上传（推荐）
```bash
# 上传多个文件，终端中会自动显示文件列表并询问确认
# 然后打开目录选择器，用户在其中选择目标目录
python3 scripts/smart_upload.py ./file1.jpg ./file2.png ./file3.jpg
```
**终端中的工作流程**（LLM 无需干预）：
```
======================================================================
📦 OSS 交互式目录选择器
======================================================================
📤 准备上传 3 个文件：
──────────────────────────────────────────────────────────────────────
1. file1.jpg (1.2 MB)
2. file2.png (856 KB)
3. file3.jpg (2.3 MB)
──────────────────────────────────────────────────────────────────────
总计: 3 个文件, 4.3 MB
📂 当前位置: 根目录 (oss://your-bucket/)
┌────────────────────────────────────────────────────────────┐
│ 输入编号进入子目录，b=返回, c=确认, q=取消 │
└────────────────────────────────────────────────────────────┘
1) 📁 app
2) 📁 assets
3) 📁 images
...
共 72 个目录
请选择: [用户输入]
[1/3] 上传: file1.jpg
✓ 上传成功!
[2/3] 上传: file2.png
✓ 上传成功!
[3/3] 上传: file3.jpg
✓ 上传成功!
============================================================
✅ 全部上传成功 (3/3)
============================================================
```
2. 指定目录批量上传（跳过交互）
```bash
python3 scripts/smart_upload.py ./file1.jpg ./file2.png --dir assets/images
```
#### 批量文件/目录上传
**重要：LLM 必须通过 smart_upload.py 执行上传，禁止直接调用 ossutil！**
当用户要求上传文件/目录时，LLM 必须：
1. 找到要上传的所有文件路径
2. **直接调用** `smart_upload.py` 执行上传（无需在对话中询问确认）
3. **所有确认逻辑都会在终端中自动展示**，用户会自行完成文件确认、目录选择、冲突处理
```bash
# LLM 应该这样执行（直接列出所有文件，无需询问）
python3 scripts/smart_upload.py ./file1.jpg ./file2.png ./file3.jpg
```
**禁止行为**：
- ❌ LLM 禁止直接调用 `ossutil cp` 或 `ossutil cp -r`
- ❌ LLM 禁止在对话中列出目录选项让用户选择
- ❌ LLM 禁止在对话中询问确认信息（文件列表确认、目录选择、冲突处理等）
- ❌ LLM 禁止自己决定上传目录
- ✅ LLM 必须通过 smart_upload.py 触发终端交互式选择器
- ✅ 所有用户交互都在终端中完成，LLM 只需执行命令
## 常见错误及处理方法
- `Error: region must be set in sign version 4.`
- 原因：缺少区域配置
- 解决：运行 `python3 scripts/oss_cli.py --init` 配置区域
- `The bucket you are attempting to access must be addressed using the specified endpoint`
- 原因：请求端点与存储空间区域不匹配
- 解决：检查配置文件中的 endpoint 设置
- `Invalid signing region in Authorization header`
- 原因：签名区域与存储空间区域不匹配
- 解决：修正配置文件中的 region 和 endpoint
## 实践经验
### 快速查询目录结构
**最佳实践**：
1. **使用 `quick_list_dirs.sh` 快速查看一级目录**（推荐）
```bash
bash scripts/quick_list_dirs.sh
```
- ✅ **速度快**：0.4秒，直接获取目录列表
- ✅ **准确**：包含空目录
- ✅ **资源消耗低**：API 调用次数少
2. **使用 `list_dirs_tree.sh` 查看多级目录**
```bash
bash scripts/list_dirs_tree.sh 2 # 2层，约3秒
bash scripts/list_dirs_tree.sh 3 # 3层，约10-30秒
```
3. **避免使用递归扫描**
```bash
# ❌ 慢：递归扫描所有文件（大 bucket 可能需要数分钟）
ossutil ls oss://bucket/ -r --limited-num 10000
```
### 凭证管理
**推荐方式**（按优先级）：
1. ✅ **环境变量**（最安全，适合脚本）
```bash
export ALICLOUD_ACCESS_KEY_ID="your-ak"
export ALICLOUD_ACCESS_KEY_SECRET="your-sk"
```
2. ✅ **配置文件**（适合多环境管理）
```bash
python3 scripts/oss_cli.py --init
```
3. ❌ **避免**：命令行明文传递密钥
### 常见错误处理
**错误 1**：`region must be set in sign version 4`
```bash
# 解决：确保配置文件中设置了 region
python3 scripts/oss_cli.py --init
```
## 安全建议
1. **禁止**在代码中硬编码 AccessKey，使用配置文件或环境变量
2. **使用** RAM 子账号并遵循最小权限原则
3. **禁止**使用主账号 AK
4. **不要**在日志中输出凭证信息
5. 生产环境**建议**使用 STS 临时凭证或实例 RAM 角色
6. **定期轮换** AccessKey（建议 90 天）
7. **启用** OSS 操作日志审计
## 工作流
1. 确认用户意图、区域、标识符，以及操作是只读还是变更
2. 首先运行最小只读查询验证连接性和权限（`ossutil ls`）
3. 使用显式参数和限定范围执行目标操作
4. 验证结果并确认操作成功
## 参考资料
- OSSUTIL 2.0 概览及安装/配置：
- https://help.aliyun.com/zh/oss/developer-reference/ossutil-overview使用说明
# 阿里OSS工具
阿里云对象存储 (OSS) 自动化管理技能，基于 ossutil 2.0 提供文件上传下载、目录同步、凭证管理等功能。
## 核心功能
- **文件管理**：上传/下载文件、目录同步、批量操作
- **凭证管理**：多 Bucket 配置、自动加载、安全存储
- **智能安装**：自动检测并安装 ossutil 工具
- **目录浏览**：快速查看 bucket 目录结构和文件列表
## 快速开始
### 1. 首次使用（配置凭证）
```bash
python3 scripts/oss_cli.py --init
```
### 2. 常用命令
```bash
# 查看文件列表
python3 scripts/oss_cli.py ls oss://bucket-name/
# 上传文件
python3 scripts/oss_cli.py cp ./local-file.txt oss://bucket-name/path/
# 下载文件
python3 scripts/oss_cli.py cp oss://bucket-name/path/file.txt ./
# 同步目录
python3 scripts/oss_cli.py sync ./local-dir/ oss://bucket-name/path/
# 查看目录结构
python3 scripts/oss_cli.py ls oss://bucket-name/path/ --limited-num 50
```
## 配置管理
配置文件位于 `~/.config/ali-oss/config.json`，支持多 Bucket 配置：
```json
{
"bucket": "your-bucket",
"your-bucket": {
"access_key_id": "...",
"access_key_secret": "...",
"region": "cn-shenzhen",
"endpoint": "https://oss-cn-shenzhen.aliyuncs.com"
}
}
```
```bash
python3 scripts/oss_cli.py --list # 列出所有 Bucket
python3 scripts/oss_cli.py --env your-bucket test # 测试连接
python3 scripts/oss_cli.py --env your-bucket switch # 切换 Bucket
```
## 技术特性
- ✅ 自动安装 ossutil（macOS/Linux）
- ✅ 5 分钟超时保护
- ✅ 统一错误处理
- ✅ 环境变量自动注入
- ✅ 支持自定义配置路径（`OSSKIT_CONFIG`）
## 文档
- [SKILL.md](SKILL.md) - 技能使用说明
- [references/install.md](references/install.md) - 安装指南
- [references/sources.md](references/sources.md) - 参考资料支持平台：Qoder · QoderWork · Claude · Codex 等 AI 编程助手