对象存储入门：为什么数据库保存 `object_key`

面向 Atlas Seller Kit 的学习文档。本文解释对象存储、object_key、来源 URL 与预签名 URL 的不同，以及本项目应如何保存和访问商品素材。

1. 一句话结论

对象存储 URL 是“此刻如何访问文件”，object_key 是“文件在存储桶中的稳定身份”。

Atlas 的数据库以 storage_provider + bucket + object_key 标识已转存的文件；不以 URL 作为文件主数据，也不长期保存带授权参数的访问 URL。

2. 用一张商品图片理解三个概念

同一张商品原图在生产环境可能保存为：

storage_provider: qiniu_kodo
bucket:           atlas-prod-assets
object_key:       workspaces/ws_123/products/p_456/original/asset_789.jpg

它在不同环境、不同时间可以生成不同 URL：

本地 MinIO URL：
http://localhost:9000/atlas-dev-assets/workspaces/ws_123/...

七牛分发 URL：
https://cdn.example.com/workspaces/ws_123/...

短时私有访问 URL：
https://cdn.example.com/workspaces/ws_123/...?
e=1780000000&token=temporary-signature

这些 URL 可能随环境、域名、CDN、签名和过期时间而变化；稳定不变的是存储桶和 object_key。

项目	对象存储 URL	`object_key`
含义	当前通过网络读取/写入文件的地址	Bucket 内文件的唯一定位键
示例	`https://cdn.example.com/a.jpg?token=...`	`workspaces/ws_123/.../a.jpg`
稳定性	域名、CDN、签名、环境变化时会变化	由 Atlas 生成并管理，作为长期主标识
是否自带读取权限	可能带有预签名授权	不带授权，只是定位信息
是否作为数据库主字段	否	是

3. Atlas 的正确资产记录

media_assets
- id
- workspace_id
- storage_provider   # local_minio / qiniu_kodo
- bucket
- object_key
- checksum_sha256
- content_type
- byte_size
- width / height
- created_at

图片、视频、水印模板和 AI 生成文件都遵循这个规则。SKU 与媒体的关联保存 media_asset.id，而不是图片名称、来源 URL 或对象存储 URL。

4. 不同 URL 分别应保存在哪里

4.1 来源 URL：可以保存，但只是采集证据

采集 1688、淘宝、天猫、Ozon 公开页时得到的图片链接是 source_url。它可能过期、防盗链、重定向或失效，因此只应与采集时间、来源页面、解析器版本一起保存在采集证据中。Worker 下载并转存成功后，正式素材身份切换为 object_key。

4.2 Atlas 访问 URL：临时生成，不长期保存

用户预览或下载私有素材时：

浏览器请求素材
  → NestJS 验证当前用户是否有该 asset 的权限
  → 根据 storage_provider + bucket + object_key 签发短时 GET URL
  → 浏览器用该 URL 显示或下载文件

短时 URL 会过期，包含签名时还代表临时授权，不能存到商品表、素材表、日志或前端长期缓存。

4.3 平台发布 URL：发布时派生并记录在快照

Ozon 导入要求图片为 HTTPS 公网可访问 URL。发布适配器可以从 Atlas 的 object_key 派生一个让 Ozon 可拉取的受控分发 URL；该 URL 仅用于这次平台请求，并与请求/响应一起保存在发布快照中，不能反过来替代素材的 object_key。

5. 上传和转存流程

用户手动上传

前端请求上传
  → API 创建 asset ID 和 object_key
  → API 签发短时上传 URL
  → 浏览器直传 MinIO/Kodo
  → API/Worker 校验 MIME、大小、哈希和图片尺寸
  → media_assets 状态变为 ready

浏览器不保存 MinIO/Kodo 的永久密钥。

浏览器插件采集

插件上报 source_url 和采集证据
  → Worker 下载来源文件
  → 校验并计算哈希
  → 上传 MinIO/Kodo
  → 写入 storage_provider + bucket + object_key
  → 建立商品/SKU 媒体关联

6. 为什么不能把 URL 当主数据

本地 MinIO 切换到生产七牛 Kodo 时，域名与 URL 结构不同；object_key 不变，不需要批量改业务数据。
更换 CDN、绑定新域名或调整私有访问策略时，不需要重写数据库。
预签名 URL 到期后可重新生成；若保存它，只会积累失效链接。
私有原图不必永久公开，访问权限可按工作空间、商品和 SKU 动态校验。
去重、删除检查、生命周期清理都围绕稳定资产 ID、哈希和 object_key 进行。

7. 本项目的边界

本地开发使用 MinIO；共享测试与生产使用七牛 Kodo。
Bucket 默认私有；原图、水印、AI 图和导入文件不长期公开。
object_key 本身不是访问凭据，但也不应作为绕过权限校验的下载入口。
对象删除前必须确认没有有效数据库引用；软删除或保留期结束后再由后台任务物理清理。

5.1 KiB Raw Blame History Unescape Escape

对象存储入门：为什么数据库保存 object_key