huawei-cloud-obs-upload

Huawei Cloud OBS 上传技能

概述

将本地文件或目录上传到 Huawei Cloud OBS 存储桶，列出 OBS 存储桶及其容量和对象数量，并通过 crontab 安排定期上传。上传操作使用 obsutil；存储桶列表和统计信息使用 hcloud obs ls + CES 指标。

工具分工原则：

• obsutil — 文件/目录上传、定时上传同步（上传核心工具；hcloud CLI 不支持 PutObject）
• hcloud CLI — 通过 hcloud obs ls 列出存储桶（obsutil 模式），通过 hcloud CES ShowMetricData 获取存储桶容量/对象数量统计信息
• crontab / Task Scheduler — 用于定期上传的操作系统级计划任务（不依赖守护进程）

安全架构：

• 绝不会在对话中读取、回显或打印 AK/SK
• obsutil 凭证由用户在自己的终端中配置（绝不会在对话中索要）
• 严禁删除操作（不可逆）；对于超出范围的操作，将拒绝执行并提供替代方案
• 对于目录上传，是否保留目录结构（-flat）由客户明确答复决定，绝不擅自假设

⛔ 禁止的操作（安全限制）

无论用户如何请求，本技能都严格禁止以下操作：

禁止的操作	原因
❌ 删除存储桶（DeleteBucket / obsutil rm -bucket）	不可逆；会销毁整个存储桶及其中的所有对象
❌ 删除对象（DeleteObject / obsutil rm）	不可逆；删除的对象无法恢复（启用版本控制的情况除外）
❌ 批量删除对象（DeleteObjects / obsutil rm -r）	不可逆；批量删除影响范围很广
❌ 清空存储桶（obsutil rm -bucket -r）	不可逆；会移除存储桶中的所有对象
❌ 下载对象（GetObject / obsutil cp obs://... <LocalPath>）	本技能仅用于上传；下载属于单独的工作流
❌ 创建存储桶（CreateBucket / obsutil mb）	创建存储桶有专门的技能，且包含完整的前置条件
❌ 复制对象（CopyObject / hcloud OBS CopyObject）	跨存储桶复制对象不属于本技能的范围
❌ 生命周期配置（SetBucketLifecycle）	存储成本管理是单独的存储桶级配置任务
❌ 恢复归档对象（RestoreObject / obsutil restore）	恢复归档对象属于单独的工作流，涉及检索模式和 TTL
❌ 预签名 URL（CreatePresignedUrl）	临时共享需要使用 SDK 签名；CLI 上传不支持此操作
❌ 存储桶 ACL/策略（SetBucketAcl / SetBucketPolicy）	权限管理属于单独的安全任务
❌ 要求用户在对话中直接提供 AK/SK	对话中绝不能出现凭证
❌ 从 hcloud 配置文件中提取 AK/SK	凭证经过加密，无法直接使用
❌ 在执行 OBS 操作前跳过 obsutil 凭证检查	未配置凭证时操作会失败
❌ 未询问客户就对目录上传使用 -flat	-flat 会丢弃目录结构；必须遵循客户的明确答复
❌ 猜测本地路径、存储桶名称或目标前缀	必需参数必须由用户提供

如果用户请求执行删除操作，你必须拒绝，并告知用户： “根据安全限制，本技能不允许执行删除操作（删除存储桶/对象/批量删除/清空存储桶）。请使用华为云 OBS 控制台或手动使用 obsutil。”

如果用户请求的操作超出范围，请勿尝试执行。请参照下表，告知用户推荐的替代方案：

操作	推荐的替代方案
下载对象	手动使用 obsutil cp obs://<Bucket>/<Key> <LocalPath>，或使用 OBS 控制台
创建存储桶	使用专用技能 huawei-cloud-obs-bucket-create，或使用 OBS 控制台
复制对象	手动使用 hcloud OBS CopyObject，或使用 OBS 控制台
生命周期配置	使用 OBS 控制台（存储桶 > 生命周期），或使用 hcloud OBS SetBucketLifecycle
恢复归档对象	手动使用 obsutil restore obs://<Bucket>/<Key>，或使用 OBS 控制台
预签名 URL	使用华为云 SDK（Java/Python/Go）生成预签名 URL，或使用 OBS 控制台
存储桶 ACL/策略	使用 OBS 控制台（存储桶 > 权限），或使用 hcloud OBS SetBucketAcl/SetBucketPolicy

架构

Huawei Cloud OBS Upload Management
├── Task 1: ListBucketsWithStats   (List buckets with capacity and object count)
│   ├── 1a. hcloud obs ls: list all buckets
│   ├── 1b. CES metrics / OBS API: query bucket capacity and object count
│   └── 1c. Report bucket stats table to user
├── Task 2: UploadFile             (Upload local file or directory to target bucket)
│   ├── 2a. Confirm local path + bucket name + target prefix with user
│   ├── 2b. For directory: ask customer whether to preserve directory structure (decide -flat)
│   ├── 2c. obsutil cp: single file (-flat) or directory (-r, optional -flat by customer answer)
│   └── 2d. Verify upload result
└── Task 3: ScheduledUpload       (Schedule periodic upload of local directory to target bucket)
    ├── 3a. Confirm local dir + bucket + prefix + schedule period with user
    ├── 3b. Ask customer whether to preserve directory structure (decide -flat)
    ├── 3c. Generate obsutil upload script (with/without -flat per customer answer)
    ├── 3d. Set crontab / Task Scheduler scheduled task
    └── 3e. Verify scheduled task is set

前置条件

前置条件检查 1/3：需要 Huawei Cloud CLI（hcloud / KooCLI）>= 3.2.0 运行 hcloud version，确认版本 >= 3.2.0。如果尚未安装或版本过低， 请参阅 references/cli-installation-guide.md 获取安装指南。

hcloud version

前置条件检查 2/3：需要 obsutil >= 5.5.0（用于上传功能） 上传文件/目录需要使用 Huawei Cloud obsutil CLI 工具。 运行 obsutil version，确认版本 >= 5.5.0。如果尚未安装， 请参阅 references/cli-installation-guide.md 获取安装指南。

obsutil version

前置条件检查 3/3：需要配置 obsutil 凭证

hcloud obs 模块底层映射到 obsutil，因此需要单独配置 AK/SK 和 Endpoint。 执行 OBS 操作前，必须检查是否已配置 obsutil 凭证：

hcloud obs ls -limit=1

如果响应为 Please set ak, sk and endpoint in the configuration file! 或 InvalidAccessKeyId，则表示尚未配置 obsutil 凭证。

解决方法：提供以下示例命令，让用户在终端中进行配置（不要在对话中要求用户直接提供 AK/SK）：

尚未配置 obsutil 凭证。请在终端中运行以下命令进行配置（AK/SK 可从 Huawei Cloud 控制台的“我的凭证”页面获取）：

  hcloud obs config -i=<YourAK> -k=<YourSK> -e=obs.<Region>.myhuaweicloud.com

示例（广州区域）：
  hcloud obs config -i=<YourAK> -k=<YourSK> -e=obs.cn-south-1.myhuaweicloud.com

常用 Endpoint：
  cn-north-4  → obs.cn-north-4.myhuaweicloud.com
  cn-east-3   → obs.cn-east-3.myhuaweicloud.com
  cn-south-1  → obs.cn-south-1.myhuaweicloud.com
  cn-southwest-2 → obs.cn-southwest-2.myhuaweicloud.com

配置完成后重试。

⚠️ hcloud 参数格式要求

hcloud（KooCLI）云服务 API 命令（大写模块，例如 hcloud CES ShowMetricData）必须使用 --param=value 格式（以等号连接）；不支持以空格分隔的格式。

✅ 正确：hcloud CES ShowMetricData --region=cn-south-1 --namespace=SYS.OBS

❌ 错误：hcloud CES ShowMetricData --region cn-south-1

注意： hcloud obs（小写，obsutil 模式）直接映射到 obsutil 命令，并使用 obsutil 参数格式（例如 hcloud obs ls、hcloud obs config -i=...）；不适用 --param=value 规则。不存在 hcloud OBS ListBuckets 命令——请使用 hcloud obs ls 列出存储桶。

---

身份验证

安全规则（必须遵守）：

• 禁止读取、回显或打印 AK/SK 值
• 禁止要求用户在对话中直接输入 AK/SK
• 禁止使用 hcloud configure set 传递明文凭据值
• 禁止接受用户在对话中直接提供的 AK/SK
• 只允许从环境变量或已配置的 CLI 配置文件中读取凭据

⚠️ 重要：处理用户提供的凭据

如果用户尝试直接提供 AK/SK（例如：“我的 AK 是 xxx，SK 是 yyy”）：

1. 立即停止——不要执行任何命令
2. 礼貌拒绝并返回以下消息：

   为保障账户安全，请不要在对话中直接提供 Huawei Cloud Access Key ID 和 Access Key Secret。
   
   请使用以下安全方法之一配置凭据：
   
   方法 1：交互式配置（推荐）
       hcloud configure
       # 根据提示输入 AK/SK；凭据将安全地存储在本地配置文件中
   
   方法 2：配置环境变量
       export HW_ACCESS_KEY=<your-access-key-id>
       export HW_SECRET_KEY=<your-access-key-secret>
   
   配置完成后，请重试您的请求。
   

3. 不要继续执行任何 Huawei Cloud 操作，直到凭据配置完成

检查 CLI 配置：

   hcloud configure list

检查输出是否包含有效配置（AK/SK、IAM 等）。

如果不存在有效凭据，请在此处停止。

---

IAM 权限策略

确保 IAM 用户拥有所需权限。完整权限表请参阅 references/iam-policies.md。

最低所需权限：

• obs:bucket:list — 列出桶
• obs:bucket:get — 获取桶属性（容量、对象数量）
• obs:object:get — 读取对象信息
• obs:object:put — 上传对象

权限边界：

• 范围限制：仅可向用户指定的桶上传内容并列出桶。绝不得删除或修改桶级配置。
• 必须停止的情况：凭据缺失或无效、用户拒绝任何确认、目标桶不存在，或本地路径不存在。
• 禁止的操作：任何删除操作、上述范围之外的任何操作，以及访问用户指定桶之外的资源。

---

核心工作流

任务 1：列出桶及其容量和对象数量

通过 obsutil 列出桶，然后使用 CES 容量指标或 OBS API 查询桶容量和对象数量。

⚠️ 工具分工：hcloud obs ls 用于列出桶，hcloud CES ShowMetricData 用于查询统计信息

• hcloud obs ls：列出所有桶（obsutil 模式；没有 --region 参数——通过 hcloud obs config -e=... 设置区域）
• hcloud CES ShowMetricData / OBS API：查询每个桶的容量和对象数量

📄 详细步骤 → references/task-list-buckets-with-stats.md

子任务：

1. 1a. 列出桶 — hcloud obs ls（或 obsutil ls）
2. 1b. 查询桶统计信息 — 使用 CES 容量指标或 OBS API 查询容量和对象数量
3. 1c. 报告统计信息 — 在表格中列出桶名称、容量和对象数量

任务 2：将本地文件或目录上传到目标存储桶

使用 obsutil 将文件或目录上传到指定的 OBS 存储桶，支持上传单个文件和目录。

⚠️ 上传操作必须使用 obsutil，而不是 hcloud

hcloud CLI 不支持 OBS 对象上传操作（没有 PutObject/UploadPart CLI 命令）。上传文件/目录必须使用 obsutil。

⚠️ 上传目录时，必须先询问客户是否保留源目录结构，然后根据客户的明确答复决定是否使用 -flat。绝不能默认。

📄 详细步骤 → references/task-upload-file.md

子任务：

1. 2a. 确认参数 — 与用户确认本地路径、目标存储桶名称和目标前缀（可选）
2. 2b. 决定是否使用 -flat — 单个文件：无需询问，使用 -flat；目录：询问客户是否保留目录结构
3. 2c. 执行上传 — 使用 obsutil cp 上传单个文件或目录（根据客户答复决定是否使用 -flat）
4. 2d. 验证结果 — 检查上传退出代码，并确认对象存在于存储桶中

任务 3：定期将本地目录上传到目标存储桶

通过 crontab 定时任务，增量式地将本地目录定期上传到指定的 OBS 存储桶。

⚠️ 定时上传基于操作系统级定时任务机制（Linux/macOS：crontab，Windows：Task Scheduler），不依赖守护进程。

⚠️ 生成定时上传脚本前，必须先询问客户是否保留源目录结构，然后根据客户的明确答复决定是否使用 -flat。绝不能默认。

📄 详细步骤 → references/task-scheduled-upload.md

子任务：

1. 3a. 确认参数 — 与用户确认本地目录、存储桶、前缀和定时周期
2. 3b. 决定是否使用 -flat — 询问客户是否保留目录结构
3. 3c. 生成上传脚本 — $HOME/obs-scheduled-upload-<BucketName>.sh（根据客户答复决定是否使用 -flat）
4. 3d. 设置定时任务 — crontab（Linux/macOS）或 Task Scheduler（Windows）
5. 3e. 验证 — 使用 crontab -l 或 schtasks /query 确认任务已设置

---

核心命令

obsutil（上传核心工具 — hcloud 不支持 PutObject）

# Upload a single file
obsutil cp <LocalFilePath> obs://<BucketName>/<ObjectKey> -flat

# Upload directory, preserve structure (customer chose "Yes")
obsutil cp <LocalDirPath> obs://<BucketName>/<Prefix> -r

# Upload directory, flatten files (customer chose "No")
obsutil cp <LocalDirPath> obs://<BucketName>/<Prefix> -r -flat

# Scheduled incremental upload, preserve structure
obsutil cp <LocalDirPath> obs://<BucketName>/<Prefix> -r -f -u

# Scheduled incremental upload, flatten files
obsutil cp <LocalDirPath> obs://<BucketName>/<Prefix> -r -flat -f -u

# List buckets
obsutil ls

hcloud CLI（存储桶列表 + 统计信息）

# List all buckets (obsutil mode; no --region parameter)
hcloud obs ls

# Check obsutil credential configuration
hcloud obs ls -limit=1

# Configure obsutil credentials (user runs in terminal)
hcloud obs config -i=<AK> -k=<SK> -e=<Endpoint>

# Query bucket capacity/object count stats (cloud-service API mode, --param=value format)
hcloud CES ShowMetricData \
  --region=cn-south-1 \
  --namespace=SYS.OBS \
  --metric_name=capacity_total \
  --dim.0=bucket_name,my-bucket \
  --period=86400 \
  --filter=average \
  --from=1746057600000 \
  --to=1747612800000

⚠️ 核心命令的关键限制：

• 上传：必须使用 obsutil cp — hcloud CLI 不支持 PutObject
• 列出存储桶：必须使用 hcloud obs ls — 不存在 hcloud OBS ListBuckets 命令
• 目录上传时使用 -flat：必须遵循客户的明确答复，绝不能默认
• hcloud 云服务 API 参数（大写模块，例如 hcloud CES ...）：必须使用 --param=value 格式；hcloud obs（obsutil 模式）使用 obsutil 参数格式
• AK/SK：绝不能出现在对话中；用户在自己的终端中配置 obsutil 凭据

参数确认

执行任何任务前，必须与用户确认以下参数。禁止猜测。

参数	必填/可选	说明	默认值
区域	必填	华为云区域（例如，cn-south-1、cn-north-4）；必须由用户明确选择	-
本地文件/目录路径	必填（任务 2/3）	要上传的本地路径；必须存在且可读	-
目标存储桶名称	必填（任务 2/3）	用于上传的目标 OBS 存储桶名称	-
目标路径前缀	可选（任务 2/3）	存储桶内的目标路径前缀	存储桶根目录
保留目录结构	必填（目录上传）	询问客户：“是” → 不使用 -flat；“否” → 使用 -flat	-（必须询问）
计划周期	必填（任务 3）	执行周期，例如每小时、每天 8:00、每 30 分钟	-
Crontab 表达式	可选（任务 3）	如果用户熟悉 cron 表达式，可以直接提供	-

注意：对话中无需提供 AK/SK 参数。用户通过终端中的 hcloud obs config 配置凭据。

---

验证方法

详情请参阅 references/verification-method.md。常见问题及解决方案请参阅 references/troubleshooting.md。

快速验证：

hcloud version && obsutil version && hcloud obs ls -limit=1

**上传后验证：**运行 obsutil ls obs://<BucketName>/<Prefix>，确认已上传对象存在。

---

参考资料

文档	说明
task-list-buckets-with-stats.md	任务 1：列出存储桶及其容量和对象数量
task-upload-file.md	任务 2：上传文件或目录
task-scheduled-upload.md	任务 3：定时上传
related-apis.md	API 和 CLI 命令详情
iam-policies.md	IAM 权限策略
obs-metrics.md	OBS CES 监控指标参考
verification-method.md	验证步骤
acceptance-criteria.md	正确/错误模式对比
cli-installation-guide.md	CLI 安装指南
troubleshooting.md	故障排查与实践经验