OBS：对象身份、权限与版本机制

原生对象桶、Endpoint 与 IAM

适用范围与版本

本文面向华为云 OBS 普通对象桶，使用 Python 3.10+，依赖分发名 esdk-obs-python==3.24.3、Python 导入名 obs 的 3.x SDK 合同。为明确 TLS 内部字段布局，此示例固定小版本；不代表所有传递依赖已锁定。华为云其他服务的统一 SDK、OBS 原生 SDK 与 Boto3 的 API 不是同一套接口；不能拿一个客户端改 Endpoint 就认为错误码、签名和参数完全兼容。2026-10-17 只核对官方中文、英文 SDK 文档和官方源码，没有安装或宣称最新。所有示例未执行，没有连接账号或启动服务。

前置是 HTTP 状态码、Python 文件与环境变量。路线为本篇、机制、CLI 阅读项目、维护、复习。本系列不覆盖并行文件系统、POSIX 语义或企业私有部署，不把其他形态的桶功能套给对象桶。

桶、对象键和 Endpoint

OBS 对象桶以 bucket 与 objectKey 定位对象，docs/a.txt 是对象名而非本地目录。prefix 列举只是名称过滤；复制再删除不是跨对象原子重命名，不能保证迁移过程中读者只看到一个位置。地域 Endpoint 决定请求去向，自定义域名、内网连接和区域能力需要另外核对。客户端 server 应填服务 Endpoint，不能误填某个对象的完整下载 URL。

业务数据库记录桶名、key、版本号、大小和业务摘要，比只记录短期签名 URL 更可靠。相同 key 的后续上传可能改变当前内容；若报告必须重现历史结果，应保存精确版本 ID。前缀检查有助防止误操作，但它不是租户隔离的安全边界。

IAM、临时凭据与签名模式

OBS IAM 最小权限应区分桶级 obs:bucket:ListBucket 与对象级 obs:object:GetObject、obs:object:PutObject；按版本读取和删除时再核对相应版本动作与桶策略授权。IAM 策略的动作写法和桶策略动作表达并不相同，不能复制 AWS 的 s3:* 前缀。应用只获得实验桶和实验前缀所需能力，不应为方便授予 OBS Administrator。涉及 KMS 的桶还需审查密钥授权。

示例显式读取 OBS_ACCESS_KEY_ID、OBS_SECRET_ACCESS_KEY 和可选 OBS_SECURITY_TOKEN 并传入 ObsClient；这不是自动角色凭据链，导出的临时三元组过期后程序不会自动刷新。生产应选择受控工作负载身份和 SDK 支持的提供器，并核对目标 SDK 的能力。示例 signature='obs' 使用原生签名模式，不宣称 AWS SigV4 适用于每个 OBS 接口。官方 SDK 使用前须知与官方源码是版本依据。

入口、返回值和费用

OBS CLI 指仓库 examples/obs/object_cli.py，包含 list、put、get、sign、delete 五个入口，不是 obsutil 的包装器。与 Boto3 常见的 ClientError 不同，原生 ObsClient 的许多操作返回 status、errorCode、requestId；收到一个响应对象并不表示成功，必须先检查 status 小于 300。网络或本地解析问题仍可能抛异常，两类错误都要处理。

小文件上传限定 1 MiB、每次用 UUID key；list 会遍历全部匹配页，get 没有总下载量限制，费用仍取决于请求量、存储、流量、历史版本和归档取回。练习：status=403 且未抛异常应退出成功吗？答案：不应，CLI 的 checked 函数应转为失败退出并记录 requestId，禁止继续访问成功响应字段。

官方阅读入口

核对：文本上传英文说明、列举对象中文说明、分发包声明。后文代码与这些原生接口一致，但未做远端行为验证。

版本、条件语义与分段上传

多版本与删除

前置是 原生桶模型。OBS 多版本开启后，同名上传保留不同版本，新版本成为当前版本；普通删除添加删除标记使无版本读取表现为不存在。指定 versionId 删除会永久移除该版本，删除标记也有自己的版本标识。暂停多版本不等于清空既有历史，null 版本也需按状态理解。普通 listObjects 不是版本清单，不能凭它证明旧内容已清除。官方多版本介绍是这套语义的依据。

恢复前保存桶、key、版本号、修改时间与是否删除标记，按明确版本读取旧内容并校验业务摘要，然后决定复制为新当前版本。删除当前标记可能重新暴露旧内容，不能当作无风险撤销；指定版本已永久删除时，多版本本身无法重建字节。多版本也不替代独立备份或业务审计。

条件请求与并发写入

OBS 条件请求必须按操作核对：GET 的 if_match 可以约束所读对象 ETag，复制的源条件约束复制来源；它们不能自动变成目标 PUT 的比较并交换。原生 SDK 的参数名、请求头和支持范围要查对应接口，不能照抄 S3 IfMatch 或 GCS generation 参数。先 HEAD 再 PUT 同样有竞争窗口；“检查不存在后上传”不是原子只创建。CopyObject SDK 文档明确源条件字段。

本 CLI 不宣称实现任意条件覆盖，而是生成 UUID key 来减少同名写入；随后让数据库唯一键或事务保护业务发布引用。随机名不是幂等键，重复执行会产生另一个对象。版本控制允许保留并发结果，但不能保证当前版本符合某个业务编辑顺序，应用仍需记录具体版本和冲突处理结果。

MD5、ETag 与下载流

OBS 校验要区分请求 Content-MD5、SDK 特定完整性功能与业务摘要。Content-MD5 通常是原始 MD5 字节的 Base64，不能把十六进制摘要直接塞进去；ETag 不应不加条件地解释为整个文件 MD5，分段上传、加密和接口路径尤其需要查文档。3.x SDK 不同小版本的 CRC64 功能不完全相同，本示例没有启用或声称已验证 CRC64。读者若增加相关选项，应先固定版本并核对原生模型字段。官方 SDK 变更与源码提供实现依据。

业务可独立保存 SHA-256 与长度，下载读到 EOF 后核验再发布。流未读完或网络中断要关闭 response，不能只让垃圾回收器最终释放连接。CLI 中途失败可能留下本地部分文件，这种文件不应被后续任务当成有效完成结果。

原生签名 URL

OBS 签名通过原生 createSignedUrl 生成短期能力，方法、对象路径、过期时间及所签字段要与真正请求一致。临时凭据有效期可以使 URL 早于设定时间失效；代理改写 Host、路径编码或签名参数也会导致失败。签名本身不读取对象，生成成功并不代表目标存在或权限足够。官方带授权 URL说明方法参数。

与 SDK 远端调用返回的 status 对象不同，createSignedUrl 返回签名结果对象，不能一律经过 checked。持有 URL 的人可执行被授权请求；私有桶也不等于“只有登录用户能使用该链接”。必须先做业务归属校验，日志和工单应删除敏感 query。

分段上传与完成边界

OBS 分段上传需要初始化任务、按分段号传输、保留各段 ETag，最后按顺序完成合并。uploadId 是任务身份，ETag 列表必须对应同一份文件；进程重启后没有检查点就不能盲目续传。未完成的段会占存储，放弃任务须中止或由生命周期清理。官方生命周期规则明确包含碎片治理。

CLI 限制普通上传，不演示分段并发和检查点文件。练习：合并超时是否意味着可以删除所有段重新开始？答案：不能先假定失败，应查询当前对象版本和业务状态，辨认服务端是否已完成。不同产品拥有类似阶段，不意味着它们的字段、校验算法和条件写合同相同。