R524809
128 lines
5.1 KiB
Markdown
128 lines
5.1 KiB
Markdown
# 对象存储入门：为什么数据库保存 `object_key`
|
||
|
||
> 面向 Atlas Seller Kit 的学习文档。本文解释对象存储、`object_key`、来源 URL 与预签名 URL 的不同，以及本项目应如何保存和访问商品素材。
|
||
|
||
## 1. 一句话结论
|
||
|
||
**对象存储 URL 是“此刻如何访问文件”，`object_key` 是“文件在存储桶中的稳定身份”。**
|
||
|
||
Atlas 的数据库以 `storage_provider + bucket + object_key` 标识已转存的文件；不以 URL 作为文件主数据，也不长期保存带授权参数的访问 URL。
|
||
|
||
## 2. 用一张商品图片理解三个概念
|
||
|
||
同一张商品原图在生产环境可能保存为：
|
||
|
||
```text
|
||
storage_provider: qiniu_kodo
|
||
bucket: atlas-prod-assets
|
||
object_key: workspaces/ws_123/products/p_456/original/asset_789.jpg
|
||
```
|
||
|
||
它在不同环境、不同时间可以生成不同 URL：
|
||
|
||
```text
|
||
本地 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 的正确资产记录
|
||
|
||
```text
|
||
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：临时生成，不长期保存
|
||
|
||
用户预览或下载私有素材时：
|
||
|
||
```text
|
||
浏览器请求素材
|
||
→ 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. 上传和转存流程
|
||
|
||
### 用户手动上传
|
||
|
||
```text
|
||
前端请求上传
|
||
→ API 创建 asset ID 和 object_key
|
||
→ API 签发短时上传 URL
|
||
→ 浏览器直传 MinIO/Kodo
|
||
→ API/Worker 校验 MIME、大小、哈希和图片尺寸
|
||
→ media_assets 状态变为 ready
|
||
```
|
||
|
||
浏览器不保存 MinIO/Kodo 的永久密钥。
|
||
|
||
### 浏览器插件采集
|
||
|
||
```text
|
||
插件上报 source_url 和采集证据
|
||
→ Worker 下载来源文件
|
||
→ 校验并计算哈希
|
||
→ 上传 MinIO/Kodo
|
||
→ 写入 storage_provider + bucket + object_key
|
||
→ 建立商品/SKU 媒体关联
|
||
```
|
||
|
||
## 6. 为什么不能把 URL 当主数据
|
||
|
||
1. 本地 MinIO 切换到生产七牛 Kodo 时，域名与 URL 结构不同；`object_key` 不变，不需要批量改业务数据。
|
||
2. 更换 CDN、绑定新域名或调整私有访问策略时，不需要重写数据库。
|
||
3. 预签名 URL 到期后可重新生成；若保存它，只会积累失效链接。
|
||
4. 私有原图不必永久公开，访问权限可按工作空间、商品和 SKU 动态校验。
|
||
5. 去重、删除检查、生命周期清理都围绕稳定资产 ID、哈希和 `object_key` 进行。
|
||
|
||
## 7. 本项目的边界
|
||
|
||
- 本地开发使用 MinIO；共享测试与生产使用七牛 Kodo。
|
||
- Bucket 默认私有；原图、水印、AI 图和导入文件不长期公开。
|
||
- `object_key` 本身不是访问凭据，但也不应作为绕过权限校验的下载入口。
|
||
- 对象删除前必须确认没有有效数据库引用；软删除或保留期结束后再由后台任务物理清理。
|
||
|
||
相关文档：[技术栈、异步任务与部署方案](../architecture/technology-and-deployment.md)、[浏览器采集插件需求](../requirements/collector-browser-extension.md)、[商品与 SKU 数据模型](../product/data-model.md)。
|