MG-02-015 统一文件存储计划

状态：2026-09-27 已确认架构方向，基础存储资源和网关运行配置代码已完成；统一文件接口仍待实施。代码基线为 Media Gateway 83756890b1ff1078225c1cb0d45b446bdce793f0，已本地合并并推送。MG-DEPLOY-02 已注入专用 TOS 凭据、完成真实 S3 验收，并启动 pic-vps 新原生实例；旧实例未切流，跨仓联调仍待完成。

本机原件：coordination/unified-file-storage-plan.md。根目录不是 Git 仓库；可推送版本快照保存在 Media Gateway 的 docs/05-delivery/UNIFIED_FILE_STORAGE_PLAN.md，本次二者内容一致。后续更新须同步；运行配置与验收步骤见同仓 docs/05-delivery/TOS_STORAGE.md。

当前进度（2026-09-27）

用户最新决定：允许为新网关新建桶，现有两个桶保留；直接使用 TOS，不使用本地对象存储。该决定取代初稿“优先映射旧桶、不默认新建三个桶”的资源选择建议。

已确认的生产前提：用户明确说明 uumi 即 Text Gateway，站点正在运行，上传和生成结果都在使用 TOS；new-api-new-oceanway 是旧 Media Gateway，也已有 TOS 桶。旧服务的连接、桶、对象访问域名、签名及生命周期保持。控制台已核查两个旧桶的配置，但具体线上版本、各服务与桶/前缀的映射、写入和清理责任尚未核查；不能从桶名或本地源码推断部署状态。

1. 已确认方向

1. 新平台共享文件的存储桶、Endpoint、区域、存储凭据由原生 Go Media Gateway 的文件模块持有；uumi 保留生产 TOS 配置。首期允许两个存储配置持有者并存，不把撤掉 uumi 配置作为完成条件，也不新增服务或仓库。
2. Core 是客户文件入口，负责已验证的客户归属、授权、上传额度和共享文件引用登记；产品自己的项目、素材库、正式采用和编辑关系仍归产品。
3. Studio、Drama、Commerce、Console、Site 和 Admin 不直接持有存储凭据，不各自维护上传存储实现。Admin 可以提供管理入口，但经 Core 校验员工权限后访问存储管理接口。
4. Media Gateway 只管理物理文件、传输和供应结果，不拥有客户素材库或产品正式 Asset。现有历史 assets 模块可复用技术实现，不能将其中内部用户 ID 当成真实客户身份。
5. 模型生成仍走 Core Worker → text gateway/new-api → media gateway → Provider。文件管理走 Core → Media Gateway 内部文件接口，不经过模型供应路由、不触发模型计费。这是本方案新增的文件控制链路。
6. 新平台“只有一处配置”不等于“只有一个桶”。按用户最新决定，保留两套现有 TOS 资源，为原生 Go Media Gateway 创建三个独立物理桶，分别承担临时、正式、副本角色；不把旧桶填入新配置，不将一个桶填进三个配置项。共享云账户不等于共享桶或生命周期。

范围：用户上传的图片/视频/音频、头像、站点与运营图片、生成结果及其缩略图。数据库备份、日志归档、构建静态文件继续按运维流程管理，不进入用户文件 API。其他文档类型按实际消费者增补契约。

2. 现状与缺口

复用优先：不重写成熟结果下载和恢复机制。S3 新增签名/分片能力使用成熟 SDK；不扩展自写签名协议。新通用上传不会使媒体网关自动获得图片/音频生成能力。

2.1 uumi 复用与边界

• 先区分复用 TOS 云资源、复用上传/读取 API、迁移文件管理责任三个问题。用户已确认 uumi 上传与生成都在使用 TOS；优先适配已有能力，只补跨产品授权、稳定引用和保留协议的缺口。
• 本地 service/media_storage.go 通过 AWS S3 SDK 读取通用 S3 环境变量；asset_library.go、image_output_archive.go、seedance_v2_archive_runtime.go 使用该存储。线上是否采用相同实现及哪些模块已启用，须与部署版本核对。
• 首期 uumi 文件由 uumi 写入、读取和清理，Media Gateway 不接管其桶或删除权限。两服务即使使用同一个 TOS 账户，也不能共同无协调地管理同一对象生命周期。
• 新平台引用 uumi 结果时，必须记录来源服务与稳定结果身份，并验证客户归属。只有支持可靠续签和持久保留/租约时才零拷贝引用；否则由可信后端在链接有效期内校验并复制到新平台正式存储一次。浏览器 URL 不能作为永久资产身份。
• Media Gateway 产生并已持久保存的结果，通过 uumi 时应评估传递稳定来源引用，避免 uumi 再次归档同一份结果。该优化限定新平台链路，不能全局关闭 uumi 现有归档功能。
• 本轮已选定原生 Media Gateway 承载新平台物理文件能力，uumi 保留原有文件能力。继续核查 uumi 的稳定结果引用与保留协议用于互通，不因新桶创建而重复迁移或接管旧文件。跨产品 Core 授权边界保持。
• 旧 Media Gateway 的 TOS 本轮保留，不作为新平台启用前必须接管的资源。后续确需接管或导入时，先核验对象索引、权限、签名、生命周期与原清理器；每个对象命名空间只有一个写入/清理负责人。在途任务按原执行链路收尾，不能因服务更替重新提交模型。
• 现有两个网关如处理同一生成结果，先核对是否已发生二次归档，再为新平台链路约定稳定来源引用；不能仅因为“上传和生成都使用 TOS”就推断数据重复。
• 将 uumi 最终迁入单一存储配置属于独立后续项目，并非本轮既定任务。没有收益或明确需求时，两个基础设施服务长期各管自己的存储也成立；各产品仍只调用统一文件接口。

3. 桶与配置

以下三个新桶已在 Chrome 控制台创建，均为北京 cn-beijing、私有、标准存储、单 AZ、SSE-TOS AES256，对象 ACL 默认私有。目前没有生命周期规则、CORS、版本控制或自动跨桶复制。

S3 Endpoint：https://tos-s3-cn-beijing.volces.com；Region：cn-beijing；GATEWAY_S3_USE_PATH_STYLE=false。真实 Access Key/Secret Key 尚未注入，不能把示例配置当作可用凭据。

旧桶 oceanway-assets-cn 无生命周期规则；oceanway-media-cn 启用了整桶最后修改 7 天后删除。二者配置和数据均保留，不将其用作新平台长期资产桶，也不擅自修改旧清理策略。仅凭目录名无法确认实际服务归属。

正常网关部署配置已去除本地 MinIO 服务与依赖，四个运行进程统一使用外部 S3 环境变量。保留的 compose.smoke.yaml 仅供显式旧容器 fixture，本轮没有运行。结果 spool 是失败恢复用的受限暂存目录，保留既有机制，不作为本地对象存储或最终文件位置。

现有 GATEWAY_S3_TEMPORARY_BUCKET、GATEWAY_S3_PRIMARY_RESULTS_BUCKET、GATEWAY_S3_REPLICA_BUCKET 首期保持；主结果桶扩展存放通用正式文件，不为改名改动环境变量。

新平台桶默认私有。运行凭据仅授予所需桶/前缀操作；浏览器只有某次上传的短期授权。桶已创建；后续通过基础设施流程配置所需权限、凭据和已核实的 CORS/清理规则，Gateway 引用已有资源，不提供对任意云账户自动建桶的能力。uumi 既有桶策略和访问域名保持，不在新平台初始化时覆盖。

新平台首期以服务端环境/Secret 注入为唯一配置源，Admin 展示脱敏配置、健康、容量与失败任务；不再并存“数据库配置覆盖环境变量”的第二套优先级。后续如需要网页编辑，单独改成版本化配置来源。此规则不改写 uumi 当前配置来源。

开发、测试、生产隔离存储资源和凭据。副本桶与主桶同服务商、同账号时，只能称为副本，不能承诺跨故障域灾备；跨区域或跨供应商复制另行实施。

保留时间、读取签名有效期、上传大小与并发额度由服务端用途策略配置。上线前必须给出明确配置，不在各产品源码里新增不一致的常量。正式桶不能配置不检查引用、仅按对象年龄删除的统一 TTL。

4. 数据归属与身份

file_id 是产品持久保存的稳定标识；blob_ref 只在可信服务间传递。Bucket/ObjectKey 与临时签名 URL 不进入产品业务记录。缩略图使用派生文件关联，继承原文件授权。

Core 的 file_binding 保存 opaque 产品对象引用和受控调用身份，不复制产品项目表，也不直接查询产品数据库。同一账户不自动获得所有私有项目文件权限。产品 BFF 必须先用本产品数据库检查项目权限，再经已有可信委托提交限定对象、动作与用户的请求；Core 校验委托作用域和文件关联。不能信任浏览器传来的 owner_user_id、product_id 或项目 ID。

首期不做跨用户内容哈希去重，不因 SHA 相同合并权限。幂等去重限定在可信用户、用途和业务操作身份内。

5. 接口提案

以下均为待新增候选路径，正式挂载前由 Contracts 对齐现有 Core 命名、认证与响应封装，不能声称当前已经存在。

受控产品 BFF 接口另外提供幂等绑定/解绑：PUT/DELETE /api/files/{file_id}/bindings/{binding_id}。普通浏览器不能任意修改产品绑定；新增绑定必须在删除并发控制内确认成功。

Gateway 内部接口为独立 /internal/files/v1 切片，覆盖上传会话创建/封存/查询/取消、blob 查询、结果引用解析、访问签名、保留租约与版本化删除。仅 Core 文件服务身份及经限定授权的内部组件可用，不复用公开模型 Key 或管理 Key。

所有写操作持久幂等：同一键同一输入返回原回执，不同输入返回冲突。公共 file 状态与 Gateway 物理状态分别定义；采用至少 uploading/verifying/ready/failed/deleting/deleted，上传会话另有 expired/cancelled。签名 URL 不落普通日志或审计正文。

第一版大小、类型、用途、校验和、状态、错误、分页、幂等、Range 与认证规则均进入 Contracts；生成 Go/TS 类型与客户端，消费者固定具体制品版本，不复制 DTO。

6. 四条关键流程

6.1 用户上传

1. 产品 BFF 验证用户和产品权限，调用 Core 创建上传会话；Core 预留上传额度，并以自己的操作 ID 调 Gateway。
2. Gateway 分配随机临时对象位置和短期上传授权。浏览器将字节直接传到临时桶，控制请求仍经 Core。产品不设置桶，也不持有永久凭据。
3. 首期采用受限直传协议：对象键固定、有效期有限，按所选 S3 服务实测支持设置长度、类型、校验约束；支持不足时由 Gateway 的受限流式上传适配实现同一会话协议，不能退成任意 Key 的开放上传。
4. 浏览器请求 complete 后，Gateway 校验实际文件大小、内容类型和哈希，将字节封存到正式的不可变对象。不能仅凭浏览器声称上传成功或仅 HEAD 检查就登记为 ready。
5. 封存必须针对同一对象版本或同一受控读取流校验并写入新正式 Key，防止临时授权尚未过期时覆盖内容。正式 Key 不在浏览器写权限范围内。重复 complete 返回同一文件，不产生新对象。
6. Gateway 返回 blob_ref，Core 完成 file 登记和额度核算；超时由持久任务查询原会话补齐，不能重复收费或无界泄露额度预留。只有 ready 可引用。

首批覆盖已有上传用途与大小范围，分片上传仅在明确的大视频需求下纳入后续批次；协议预留状态查询即可，不提前实现全部对象存储功能。

6.2 生成结果采用

1. 保持现有供应执行、下载、主桶与副本转存流程，Gateway 产生稳定 output_ref/blob_ref。
2. Core Worker 从已持久化的客户任务、new-api 任务与媒体任务映射核验来源；不得接受前端随意提供的供应 output_id 来认领文件。
3. Core 幂等申请持久保留租约，登记 file，再向产品交付 file_id。Gateway 保留成功但 Core 回执丢失时以同一操作 ID 恢复，不重复下载结果。
4. 产品选择“保存到项目”时建立业务素材记录和 file_binding。生成结果与正式采用分开记录；未采用结果按明确的任务历史保留策略处理。
5. 文件交付异常进入结果交付恢复，只重试转存/登记/授权，不重新提交模型、不凭此自动退款。存储可用与供应计费终态分别处理。

6.3 读取和生成输入

用户读取经产品 BFF/Core 校验权限，再通过短期签名 GET 或受控流返回。Range/HEAD/Content-Disposition、过期续签、缓存与私有响应不缓存规则均验收。播放器签名时长按实际访问策略确定。

生成请求传 file_id；Core 确认调用者可使用且文件 ready，将其映射成内部受控引用。Gateway 接入 UploadResolver，根据任务范围解析文件；Provider 只得到所需的短期素材访问能力。保留租约覆盖任务等待、执行与结果核对期，不在 Provider 正在读取时过期删除。

稳定内容地址不保证短期授权立即撤销。需要立即撤销的内容使用每次校验的代理读取；普通签名链接的撤销窗口受配置 TTL 限定。公开作品/头像由独立发布授权关联访问，撤回后停止签发新链接，不把整个桶公开。

6.4 引用与删除

产品对绑定和解绑使用本地事务 outbox：建立 Core 绑定成功后再标记本地采用完成；失败时保留 pending，不向用户谎报已保存。删除本地引用后可靠重放解绑，重放操作幂等。创建中断产生的保守绑定由对账修复，不靠超时盲删。

Core 在同一事务中检查零引用并将 file 标记 deleting，同时禁止新绑定。通过 outbox 通知 Gateway 释放相应租约；Gateway 在物理对象锁/版本条件下确认所有租约均已释放、没有在途读取/生成占用后安排删除。若 blob 仍被其他 file 引用，保留物理对象。

删除结果可查询；主对象/派生/副本删除部分失败时保持待重试状态，不报告物理清理完成。GC 仅处理明确过期上传、已释放文件和可证明的孤立对象；Core 不可用、归属未知或对账未完成时保守保留。

7. 各仓工作包与验收

以下 Owner 指责任仓，不代表已分配具体 Agent 或已经开工。每包实施前登记独立任务、Owned Paths 和依赖；新增数据库表的 writer 只有所属仓。

依赖顺序：FS-00 → FS-01 → FS-02 → FS-03 → FS-04 → FS-05 → FS-06/07。物理文件后端已选定为原生 Media Gateway；资源与运行配置准备已先完成，FS-00 的旧链路核查仍只完成部分，不代表文件协议已冻结或旧服务已接管。可在契约冻结后独立准备消费端适配，但切换必须等后端闭环通过。第一交付以文件后端 + Core + Studio 一个完整闭环为界，不先做所有平台设置页。

统一配置页的第一版只展示实际生效来源与健康。最终产品端仅需要现有 Core/BFF 地址与可信身份配置；不增加 Gateway 管理密钥或 S3 配置。

8. 切换与回滚

先区分需要保留的业务文件和可重建测试文件，不默认线上没有数据，也不预先搭建永远保留的兼容系统。

本节切换仅针对接入新平台的消费者。uumi 持续运行并保持其 TOS 配置，不纳入下列批量导入、停写或清理步骤。旧 Media Gateway 的桶接管另有明确交接清单，不能与普通消费者清理混用。

• 无保留数据：在验收环境直接切统一写入和读取，不实现历史双写。
• 有保留数据：用一次性导入任务登记 source_system + source_id/storageKey → file_id；分批读取、实际校验、登记来源与归属，保留失败清单。已有桶对象只有经 Gateway 明确接管、验证访问与保留策略后才允许零拷贝登记；否则复制到新桶。
• 新增记录只经新路径写入；旧读取按记录来源临时保留，禁止按“当前总开关”改变历史文件位置。导入完成且引用替换核对通过后移除旧读适配。
• 原桶/本地文件在验收前不删除。确认回滚窗口结束后再按清单清理，不能直接递归清空。
• 回滚按消费者关闭新上传/采用入口，保留新文件读取与恢复 worker；旧客户端回滚版本必须仍能识别新 file_id，否则只能暂停写入，不能直接回退不兼容版本。禁止自动回退本地写入形成新孤岛。
• uumi 原有业务、新上传和结果归档继续走当前生产链路；新平台上线/回滚不能改变其写入、读取、签名或清理行为。若后续明确决定迁移 uumi，另立包含在途任务与历史链接连续性的专项方案。普通文本请求不应依赖新文件服务 readiness。

9. 验收清单

1. 上传中断、超时重试、重复 complete、临时对象覆盖、大小/MIME/哈希不符、会话到期均有确定状态；不可读取半成品。

2. 两用户、两个产品、项目成员变更、员工不同权限、公开作品撤回均不越权；不能认领别人的生成 output。

3. 一个文件被两个产品引用，解绑一个仍可读取；最后解绑与新绑定并发时不误删；副本也按相同删除授权处理。

4. 生成结果在存储失败、Core 宕机、响应丢失、副本故障下可恢复；同一模型操作不重复提交付费任务。

5. Studio 原图/缩略图、头像、画布和短剧引用、历史刷新、移动端视频 Range、下载与过期续签实际可用。

6. 用选定 S3 兼容实现验证签名、CORS、封存一致性、读取 Range、主/副本和删除；本机 fixture 不能替代这项证据。不发起收费模型生成。

7. 配置切换只改变新对象位置，历史对象依据登记位置读取；凭据轮换不中断既有文件定位。

8. 新平台产品部署与构建产物不含 S3 密钥；新平台 S3 SDK 和真实对象写入集中在批准的文件后端/运维导入路径，uumi 既有实现明确保留。对上传完成时延、失败率、待恢复任务、孤立文件和副本欠账有观测。

9. 各仓按 AGENTS 运行相关测试、类型/静态检查和构建；本地证据通过只标记本地完成，真实存储验证与生产切换单独记录。

10. 新平台切换前后，uumi 原有素材、历史结果链接、归档与清理行为保持；uumi 来源文件有明确的保留保证或已完成单次导入，不能仅保存会过期的 URL。

完成定义：一个新用户在 Studio 上传、引用生成、读取结果、保存到项目、跨授权产品复用、解绑与删除的全过程，新平台只需在 Media Gateway 文件后端配置一次存储；所有文件访问有明确归属，所有未知结果可以查询恢复，各新平台产品不再维护独立存储连接。uumi 的运行与 TOS 配置保持，不以整个系统只剩一套存储凭据作为验收指标。

10. 代码依据

• gateways/oceanway-media-gateway/docs/00-product/CURRENT_BOUNDARY.md
• gateways/oceanway-media-gateway/internal/platform/config/config.go
• gateways/oceanway-media-gateway/internal/platform/objectstore/client.go
• gateways/oceanway-media-gateway/internal/platform/objectstore/buckets.go
• gateways/oceanway-media-gateway/internal/app/media_runtime.go
• gateways/oceanway-media-gateway/internal/video/material/source.go
• gateways/oceanway-media-gateway/internal/video/result/processor.go
• gateways/oceanway-media-gateway/internal/assets/transfer.go
• platform/oceanway-core/docs/media-task-gateway.md
• products/oceanway-studio/web/src/lib/server/object-storage-config.ts
• products/oceanway-studio/web/src/lib/server/local-media-storage.ts
• products/oceanway-studio/web/src/services/server-media-storage.ts
• gateways/oceanway-text-gateway/service/media_storage.go
• gateways/oceanway-text-gateway/service/asset_library.go
• gateways/oceanway-text-gateway/service/image_output_archive.go
• gateways/oceanway-text-gateway/service/seedance_v2_archive_runtime.go
• operations/oceanway-docs/content/docs/architecture/cross-product-flows.mdx