kdletters
5daeef21bf
前端将完整阿里云OSS generated 地址归一为 legacy path 后走 read-url 换签。 platform-oss 为 generated 私有对象 PostObject 和 PutObject 写入 immutable Cache-Control。 补齐 shared-contracts 与 api-server 直传票据字段映射。 更新后端、运维文档和 Hermes 团队记忆，明确不使用服务端磁盘缓存兜底。
50 lines
3.0 KiB
Markdown
50 lines
3.0 KiB
Markdown
# platform-oss 平台适配 package 说明
|
||
|
||
日期：`2026-04-20`
|
||
|
||
## 1. package 职责
|
||
|
||
`platform-oss` 是 OSS 平台适配 package，后续负责：
|
||
|
||
1. OSS 直传签名、STS、上传策略适配
|
||
2. 对象上传、下载、签名 URL 与 `cdn_url` 解析适配
|
||
3. 对象元数据、标签与内容 hash 适配
|
||
4. 供 `module-assets`、`module-custom-world` 等模块复用的对象存储基础设施能力
|
||
|
||
## 2. 当前阶段说明
|
||
|
||
当前提交已落地最小可用 OSS 基础设施：
|
||
|
||
1. `PostObject` 浏览器直传签名
|
||
2. 旧 `/generated-*` 公开前缀到 OSS `object_key` 的兼容映射
|
||
3. 私有对象短期签名读 URL
|
||
4. 私有对象 `HEAD Object` 探测
|
||
5. 服务端 `PutObject` 上传 helper
|
||
6. `x-oss-meta-*` 元数据归一化与大小限制校验
|
||
7. `content-type`、`content-length-range`、`success_action_status` policy 条件生成
|
||
8. `PostObject` 签名、`GetObject` 读签名、`HEAD Object` 和 `PutObject` 的结构化日志
|
||
9. generated 私有对象上传默认写入 `Cache-Control: public, max-age=31536000, immutable`
|
||
|
||
当前仍未落地的内容：
|
||
|
||
1. `STS` 真实临时授权下发
|
||
2. multipart 分片上传
|
||
3. 内容 hash 自动计算与标签写入
|
||
|
||
补充说明：
|
||
|
||
1. 当前产品口径为服务器上传 AI 生成资源、Web 端只负责读取。
|
||
2. 因此 `STS` 不作为默认上传主链，`api-server` 只暴露禁用式 contract，避免浏览器拿到 OSS 写权限。
|
||
3. 服务端生成资源应优先复用 `OssClient::put_object`，上传成功后再走对象确认链路写入 `asset_object`。
|
||
4. 读签名和 `HEAD Object` 的入参必须直接传 object_key，不要把 bucket 名拼进路径；例如 `generated-square-hole-assets/.../image.png` 才是正确入参，`xushi-dev/...` 这类前缀不属于 object_key。
|
||
5. OSS V4 `x-oss-date` 必须固定为 `yyyyMMdd'T'HHmmss'Z'`，不能依赖 `time::Time::to_string()`；后者在小时小于 10 时可能输出非补零时间，导致签名格式错误。
|
||
6. 结构化日志只记录 `provider`、`operation`、`bucket`、`endpoint`、`object_key` / `key_prefix`、`access`、`content_type`、`content_length`、`status`、`status_class`、`error_kind` 和 `elapsed_ms` 等排障字段；禁止输出 AccessKey、policy、signature、Authorization header 或完整 signed URL。
|
||
7. 完整 OSS URL 不能当作 object key 传入签名接口；前端收到 `https://*.oss-*.aliyuncs.com/generated-*` 时应先归一为 legacy public path，再通过 `/api/assets/read-url` 换取短期 signed URL。
|
||
8. generated 资源缓存的主路径是 OSS 对象头、浏览器 / WebView HTTP 缓存和后续 CDN，不允许改成 api-server 本地磁盘静态资源兜底。
|
||
|
||
## 3. 边界约束
|
||
|
||
1. `platform-oss` 只承接对象存储平台适配，不承接业务实体状态与业务规则。
|
||
2. 资产状态与对象绑定最终由业务模块和 `apps/spacetime-module` 管理，前端接口由 `apps/api-server` 暴露。
|
||
3. 不允许把 OSS SDK、签名逻辑和 URL 策略重新散落到多个业务模块里各自实现。
|