OSS/S3 Object Versioning vs Content-Addressable Key

Tipsy Studio workspace 文件存储方案评估 2026-03-30

背景

Tipsy Studio 使用 Manifest + Object Store 模型管理 workspace 文件版本。当前实现依赖 S3 Object Versioning（同一文件覆写同一 key，靠 VersionId 区分版本）。本文评估是否有必要继续依赖该特性，以及替代方案的优劣。

	S3 Object Versioning（当前）	Content-Addressable Key（推荐）
文件 key	`projects/{pid}/files/{path}` — 固定 key，反复覆写	`projects/{pid}/objects/{sha256[:2]}/{sha256}` — 每份内容一个唯一 key
版本区分	S3 返回的 VersionId	key 本身包含内容哈希，天然唯一
读取方式	`get_object(Key=..., VersionId=...)`	`get_object(Key=...)` — 无需额外参数
写入幂等性	每次 put 都产生新版本	相同内容 = 相同 key = 天然幂等
内容去重	无 — 内容相同也会产生新版本	自动去重 — 相同 sha256 只存一份

结论：Content-Addressable 只依赖最基础的 S3 API（put_object / get_object），兼容所有 S3 兼容存储。

	Object Versioning	Content-Addressable
存储	旧版本持续占空间，需 lifecycle policy 清理	相同内容只存一份，天然节省
请求	每次写入都产生新版本对象	可在写入前检查 key 是否存在，跳过重复写入
管理	需要配置 lifecycle 规则防止版本膨胀	需要 GC 机制清理无引用对象（可选，不紧急）
估算差异	高频编辑场景下存储量 ≈ 2-5x（取决于 lifecycle）	去重后存储量最优

	Object Versioning	Content-Addressable
写入代码	`put_object` → 必须捕获 `VersionId` 并存入 manifest	`sha256` → 构造 key → `put_object`（已有 sha256 计算逻辑）
读取代码	必须传 `VersionId`，漏传读到最新版（静默错误）	只传 key，不可能读错
Bucket 配置	必须开启 Versioning，忘了开 = 运行时 crash	无特殊配置要求
GC / 清理	需要 S3 Lifecycle Policy	需要应用层 GC（扫描未引用的 object key）
调试	同一 key 下多个版本，S3 控制台不直观	每个对象独立 key，清晰可审计

	Object Versioning	Content-Addressable
误删保护	S3 versioning 自带：删除只加 delete marker，数据仍在	需要靠 manifest 引用链保护；未引用对象可被 GC
数据完整性	依赖 S3 内部一致性	sha256 = 内容校验码，读取后可验证完整性
审计	S3 版本历史	manifest 链 + 不可变对象

文件	改动	复杂度
`workspace_store.py`	`file_object_key()` 改用 sha256 生成 key；删除 `_require_version_id()`；`get_object_bytes()` 移除 VersionId 参数	低
`workspace_store.py`	`get_s3_client()` 新增 R2 provider，删除 OSS 特殊处理	低
`workspace_versions.py`	`apply_workspace_change` / `publish_run_state` 中 version_id 参数适配	低
`r2_client.py`	删除，功能合并到 `workspace_store.py`	低
`config.py`	删除 `workspace_storage_provider`，简化为单一 S3 兼容配置	低
`models.py`	无改动 — `manifest_s3_version_id` 字段保留，新记录填空	无

维度	胜出方
供应商无关性	Content-Addressable
存储成本	Content-Addressable（去重）
代码简洁性	Content-Addressable（无需管理 VersionId）
数据安全	各有优劣，整体持平
迁移成本	Object Versioning（维持现状无需迁移）
长期维护	Content-Addressable（无 lifecycle 配置，无供应商限制）

推荐：迁移到 Content-Addressable Key 模式。当前代码已经计算 sha256，改动量小，收益明确——解除供应商锁定、降低存储成本、简化代码。