huawei-cloud-obs-stats

华为云 OBS 统计技能

概览

查询华为云 OBS（对象存储服务）统计数据：列出存储桶的容量和对象数量，查询公网／内网下载流量及环比数据，并查询总请求次数及环比数据。

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

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

禁止的操作	API／命令	原因
❌ 删除存储桶	DeleteBucket / obsutil rm -bucket	不可逆；会销毁整个存储桶及其中的所有对象
❌ 删除对象	DeleteObject / obsutil rm	不可逆；删除的对象无法恢复（除非启用了版本控制）
❌ 批量删除对象	DeleteObjects / obsutil rm -r	不可逆；批量删除影响范围广
❌ 清空存储桶	obsutil rm -bucket -r	不可逆；会移除存储桶中的所有对象

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

架构

Huawei Cloud OBS Statistics
├── ListBucketsWithStats  (List buckets with capacity and object counts)
├── GetTraffic           (Query extranet/intranet download traffic with MoM comparison)
└── GetRequests           (Query total requests with MoM comparison)

前置条件

前置条件检查 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（用于列出 OBS 存储桶） hcloud OBS 模块在底层使用 obsutil。列出存储桶需要 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

配置完成后重试。

禁止的操作：

• ❌ 不要要求用户直接在对话中提供 AK/SK
• ❌ 不要从 hcloud 配置文件中提取 AK/SK（凭证已加密，无法直接使用）
• ❌ 执行 OBS 操作前不要跳过凭证检查

⚠️ hcloud 参数格式要求

hcloud（KooCLI）的所有参数都必须使用 --param=value 格式（以等号连接）；不支持以空格分隔的格式。

✅ 正确：hcloud OBS ListBuckets --region=cn-south-1

❌ 错误：hcloud OBS ListBuckets --region cn-south-1

[有条件] CLI User-Agent — hcloud OBS 模块命令可以包含 User-Agent 标头，但 CES 模块不支持此参数：

• ✅ OBS 模块：hcloud obs ls
• ❌ CES 模块：hcloud CES ShowMetricData 不支持 --User-Agent；附加该参数会导致“Invalid parameter: User-Agent”

---

身份验证

前置条件检查：需要华为云凭证

安全规则（必须遵守）：

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

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

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

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

   为了保障账户安全，请勿在对话中直接提供华为云访问密钥 ID 和访问密钥 Secret。
   
   请使用以下安全方式之一配置凭证：
   
   方法 1：交互式配置（推荐）
       hcloud configure
       # 按提示输入 AK/SK；凭证将安全地存储在本地配置文件中
   
   方法 2：配置环境变量
       export HUAWEICLOUD_SDK_AK=<your-access-key-id>
       export HUAWEICLOUD_SDK_SK=<your-access-key-secret>
   
   完成配置后，请重试您的请求。
   

3. 不要继续执行任何华为云操作，直到凭证配置完成

检查 CLI 配置：

   hcloud configure list

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

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

---

IAM 权限策略

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

最低所需权限：

• obs:bucket:list — 列出存储桶
• obs:bucket:get — 获取存储桶属性
• obs:object:get — 读取对象信息
• ces:metric:get — 查询 CES 监控指标（容量、对象数量、流量、请求数量）

---

核心工作流

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

通过 obsutil 列出存储桶，然后通过 CES 查询存储桶容量和对象数量。容量优先使用 CES capacity_total 指标，对象数量优先使用 CES object_num_all 指标（适用于高效批量查询，采集间隔为 30 分钟）。不要使用 GetBucketStorageInfo（hcloud OBS 模块不支持）。

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

任务 2：查询公网／内网下载流量（含环比比较）

通过 CES ShowMetricData 查询下载流量（公网 + 内网），并进行环比比较。

📄 详细步骤 → references/task-query-traffic.md

任务 3：查询总请求数（含环比比较）

通过 CES ShowMetricData 查询总请求数（GET/PUT/POST/DELETE/HEAD 之和），并进行环比比较。

📄 详细步骤 → references/task-query-requests.md

---

核心命令

命令	说明
hcloud obs ls	列出所有存储桶（obsutil 模式）；可通过 grep 按区域筛选
hcloud CES ShowMetricData --region=<R> --namespace=SYS.OBS --metric_name=<M> --dim.0=bucket_name,<B> --period=86400 --filter=<F> --from=<ms> --to=<ms>	查询 CES 指标数据（容量、对象数量、流量、请求）
python3 scripts/obs_traffic_stats.py --region <R> --bucket <B> (--period <P> | --from <D> --to <D>) [--direction download|upload|both]	流量统计及环比变化
python3 scripts/obs_request_stats.py --region <R> --bucket <B> (--period <P> | --from <D> --to <D>) [--include-errors]	请求统计及环比变化

⚠️ CES ShowMetricData 不支持 --User-Agent；追加此参数会导致错误。

常用 CES 指标：

指标	--metric_name	--filter
存储桶容量（推荐）	capacity_total	average
存储桶对象数量（推荐）	object_num_all	average
外网下载流量	download_traffic_extranet	sum
内网下载流量	download_traffic_intranet	sum
GET / PUT / POST / DELETE / HEAD 请求	get_request_count / put_request_count / post_request_count / delete_request_count / head_request_count	sum

---

参数确认

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

参数	必填/可选	说明	默认值
--region	必填	华为云区域（例如 cn-south-1、cn-north-4）；必须由用户明确提供	-
存储桶名称	必填	OBS 存储桶名称；维度格式：--dim.0=bucket_name,<BucketName>	-
时间范围	必填	必须与用户的表述精确对应：“本月” ≠ “过去 30 天”（见下表）	-
obsutil 凭证	必填	执行任何 OBS 操作前，通过 hcloud obs ls -limit=1 检查	-
--direction	可选	流量方向：download / upload / both	download
--include-errors	可选	同时查询 4xx/5xx 错误请求数	false
--compare	可选	显示对比时段及环比变化。默认禁用；仅当用户明确要求对比/环比时启用	false
--metric	可选	以逗号分隔的指标键，仅显示指定行。obs_request_stats.py：total,get,put,post,delete,head,4xx,5xx；obs_traffic_stats.py：extranet,intranet,total。不区分大小写。指定 4xx/5xx 会自动启用错误查询。示例：--metric 4xx,5xx、--metric intranet	-

时间范围消歧：

用户的表述	时间范围
“本月”	当月 1 日 00:00:00 ~ 现在
“过去 30 天” / “过去一个月”	现在 - 30 天 ~ 现在
“上个月”	上个月 1 日 00:00:00 ~ 上个月最后一天 23:59:59
指定日期范围	用户指定的开始和结束时间

---

脚本工具

此技能提供以下 Python 脚本，封装了流量和请求统计的最佳实践：

脚本	描述
obs_traffic_stats.py	下载/上传流量统计，支持环比比较。选项：--direction、--compare、--metric。默认不启用比较。用法请参阅上方的核心命令。
obs_request_stats.py	总请求数统计（GET/PUT/POST/DELETE/HEAD），支持环比比较。选项：--include-errors、--compare、--metric。默认不启用比较。用法请参阅上方的核心命令。

使用示例：

# Traffic: last 30 days download traffic
python3 scripts/obs_traffic_stats.py --region <Region> --bucket <BucketName> --period last_30d

# Traffic: this month download + upload traffic
python3 scripts/obs_traffic_stats.py --region <Region> --bucket <BucketName> --period this_month --direction both

# Requests: last 30 days request count
python3 scripts/obs_request_stats.py --region <Region> --bucket <BucketName> --period last_30d

# Requests: this month request count (with 4xx/5xx error stats)
python3 scripts/obs_request_stats.py --region <Region> --bucket <BucketName> --period this_month --include-errors

# Custom date range
python3 scripts/obs_request_stats.py --region <Region> --bucket <BucketName> --from <FromDate> --to <ToDate>

这些脚本融入了从实践中总结的关键经验：流量与带宽指标、hcloud 维度参数格式、精确匹配时间范围、OBS 缺少单一的 request_count 指标等。

---

验证方法

详情请参阅 references/verification-method.md。

快速验证：

# Check OBS bucket list (using obsutil)
hcloud obs ls -limit=1

# Check obsutil configuration
obsutil ls -limit=1

# Validate traffic stats script
python3 scripts/obs_traffic_stats.py --region <Region> --bucket <BucketName> --period last_30d

# Validate request stats script
python3 scripts/obs_request_stats.py --region <Region> --bucket <BucketName> --period last_30d

---

参考资料

文档	描述
task-list-buckets-with-stats.md	任务 1：列出存储桶及其容量和对象数量
task-query-traffic.md	任务 2：查询下载流量及环比
task-query-requests.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	故障排除和实践经验
obs_traffic_stats.py	流量统计脚本
obs_request_stats.py	请求统计脚本