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

对象模型、地域与 RAM 权限

阅读范围与版本

阿里云 OSS 是按对象键访问内容的托管对象存储。本文面向普通 Bucket，使用 Python 3.10+ 与 oss2>=2.19,<3 的 Python SDK V1 合同；它与导入 alibabacloud_oss_v2 的 SDK V2 是不同项目，不能混用构造器和返回类型。依赖范围是教学声明，不是已经解析的锁文件，也不代表最新版本。2026-10-17 只核对官方文档与源码；本轮没有安装 SDK、连接账号、执行示例或创建资源。

学习顺序是本篇、机制、完整 CLI、维护、复习。读者应已理解 HTTP 状态码、Python 文件流与环境变量；没有云账号也能完成所有推演题。将后文自行运行命令视为可选实验，不是本站构建步骤。

Bucket、对象键与地域

OSS Bucket 的名称、地域和 Endpoint 共同确定请求目标；对象键是完整字符串，reports/2026/a.txt 中的斜杠只是命名约定。列举前缀不能替代目录权限，更没有本地文件系统的原子目录重命名。搬移一个前缀通常是逐对象复制并删除，过程中应允许两个位置同时存在，不能把一次列表当作事务快照。

应用数据库应记录 Bucket、key、版本 ID、业务摘要与状态，而不是只存一个会过期的下载链接。地域选错可能导致重定向或签名错误；内网 Endpoint 的可达性与互联网域名不同。示例使用 HTTPS 普通地域 Endpoint，不替读者配置 CDN、跨地域复制或自定义域名。

RAM 与凭据链

OSS RAM 最小权限应拆成桶级列举 oss:ListObjects 与前缀内对象的 oss:GetObject、oss:PutObject；按版本读取、永久删除还需核对 oss:GetObjectVersion、oss:DeleteObjectVersion 等操作。资源范围绑定实验桶及 theory-lab/your-session/*，列举权限结合前缀条件限制；不要给应用 AliyunOSSFullAccess。若启用 KMS，还要独立审查密钥授权，OSS 权限不自动包含 KMS 使用权。

示例的凭据链是显式 EnvironmentVariableCredentialsProvider，读取 OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET 及可选 OSS_SESSION_TOKEN，再由 ProviderAuthV4 签名；它没有自动选择角色的逻辑，也不负责刷新一组导出的 STS 临时值。生产优先工作负载角色与可刷新提供器，示例只演示输入边界。环境文件仅列变量名，不能把真实密钥、临时 token 或签名 URL 提交到仓库。官方 V1 上传示例展示这一 V4 构造方式。

请求、成本与第一道练习

OSS CLI 在本系列中指仓库 examples/oss/object_cli.py，不是 ossutil。它只支持 list、put、get、sign、delete，不创建 Bucket，不修改权限；put 每次产生随机键且限制 1 MiB，delete 必须提供版本 ID。先阅读 python object_cli.py --help 的参数合同即可理解入口，本轮连 help 也未执行。

请求费、存储费、外网下载流量、旧版本容量、归档取回和未完成分片都会构成成本。小文件限制不能限制 list 页数或下载流量，前缀也不是服务端授权；必须结合真实 RAM、预算及人工清理记录。练习：只允许上传图片为何还要限制列举？答案是列举可暴露对象名和业务标识；若业务根本不需要列举，就不要授予此动作。

官方依据

核对来源：OSS SDK 指南、SDK V1 源码、PutObject 中文 API。后续每篇对机制分别给出 API 来源；兼容其他对象存储的工具经验不能代替这些合同。

版本、防覆盖、CRC64 与分片

版本 ID 与删除标记

前置是 Bucket 模型。OSS 版本控制启用后，同键写入产生独立版本，应用必须保存 x-oss-version-id；省略 versionId 的读取取当前版本。普通删除通常添加删除标记，让当前对象表现为不存在，历史内容仍可按版本读取且继续计费。指定版本删除则永久删除该版本；删除标记也有自身 ID，删除它可能重新暴露早先内容。因此“删除成功”“用户看不见”“数据永久销毁”是三个不同结论。官方版本管理指南说明了这些操作。

暂停版本控制不等于回到从未开启状态，null 版本及既有历史版本仍需单独分析。版本控制也不是备份：有权限的主体和生命周期仍能删除历史版本。恢复前列明 key、各版本 ID、时间及删除标记，先按精确版本下载核对摘要，再决定复制旧版本为新当前版本，避免凭“最后修改时间”猜目标。

防覆盖与并发边界

OSS 防覆盖头 x-oss-forbid-overwrite=true 可以在适用的非版本桶阻止同名对象覆盖，冲突返回 409；但在版本已启用或已暂停的目标桶中不生效。它不是 S3 IfNoneMatch 的通用替代，更不是基于 ETag 的任意写入 CAS。先 HEAD 再 PUT 存在竞争窗口；后到写入仍能改变当前版本。此限制见 PutObject 英文 API。

条件 GET 的 If-Match 约束所读取的对象，复制的 x-oss-copy-source-if-match 约束源对象；不能从这些参数推导出目标写入的比较并交换。应用若要发布唯一业务结果，可先上传 UUID 不变对象，再让数据库唯一键或事务更新“当前对象版本”引用。示例随机键只降低碰撞概率，不声称提供业务幂等性；重试生成另一个 UUID 会留下两份对象。CopyObject 合同也区分源条件和目标版本。

CRC64、摘要与读取完整性

OSS CRC64 用于检查传输完整性，V1 enable_crc=True 打开 SDK 校验；上传和完整读取的校验路径与范围读取不同。CRC64 是检错码，不是密码学内容指纹，也不证明上传者身份。MD5、ETag 和 CRC64 不能互换，特别是分片对象不能默认把 ETag 当全文 MD5。业务去重另存 SHA-256 并记录大小，下载完整内容后再比较；失败文件应留作诊断或删除，不能发布给消费者。官方数据校验是这里的 SDK 依据。

V4 签名与短期授权

OSS V4 签名把请求方法、资源、地域和参与签名的请求字段绑定到凭据。sign_url('GET', key, 300) 生成五分钟读取能力，不会检查对象已存在或接收者是否可信。调用者拿到 URL 即可在有效期内使用；临时凭据先失效时 URL 也会提前失效。URL 中的路径编码、查询参数、Host 和签名头被代理更改都可能导致验签失败。不要签完后再拼接业务参数，不要把 URL 写入常规日志。

私有桶也会允许持有有效签名的匿名接收者完成被授权请求。业务下载接口仍需校验用户、对象归属及过期时间；撤销一个分享链接通常需要更上层的访问网关，而不是期待对象 ACL 自动识别接收人。

分片上传与提交

OSS 分片上传经历初始化 uploadId、上传带 partNumber 的分片、提交有序 PartInfo 列表三个阶段。只完成部分分片不会产生完整可读对象，却会保留计费碎片。失败重试必须保留同一个 uploadId、分片大小与内容，提交时不能把不同文件的分片混用；放弃任务要执行 AbortMultipartUpload 或配置碎片生命周期。SDK V1 分片说明提供原生接口。

本系列 CLI 使用小对象普通 PUT，未实现分片调度。练习：进程在提交成功响应前断线，是否立即重新初始化？答案：先以业务记录、对象版本与摘要核对结果；“未收到成功”不等于“服务端未提交”。若重试策略无法判断结果，应让不变对象与数据库引用共同消除误发布风险。