141 lines
4.8 KiB
Markdown
141 lines
4.8 KiB
Markdown
# 产品档案与清理运行手册
|
|
|
|
## 1. 服务启动
|
|
|
|
产品档案要求三类持久卷全部存在：
|
|
|
|
```bash
|
|
docker compose up -d --build
|
|
docker compose ps
|
|
docker compose logs --tail=80 backend
|
|
```
|
|
|
|
`docker-compose.yml` 中必须挂载：
|
|
|
|
- `wordcloud_products:/app/service_products`
|
|
- `wordcloud_metadata:/app/service_metadata`
|
|
- `wordcloud_orders:/app/service_orders`
|
|
|
|
首次上线或更新后，先检查健康接口：
|
|
|
|
```bash
|
|
docker compose exec backend curl -fsS http://localhost:8000/api/health
|
|
```
|
|
|
|
## 2. 外部产品同步
|
|
|
|
首期外部系统可以先使用创建/更新产品接口做幂等同步：
|
|
|
|
```http
|
|
POST /api/products
|
|
Authorization: Bearer <生产订单管理口令>
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"source": "external",
|
|
"external_product_id": "PROD-123",
|
|
"name": "产品名称",
|
|
"sku": "SKU-123",
|
|
"specification": "规格"
|
|
}
|
|
```
|
|
|
|
同步以 `(source, external_product_id)` 合并，不按名称合并。后续产品接口字段稳定后，可以在现有模型上补适配层，不必改档案结构。
|
|
|
|
产品列表和详情默认展示产品名称、SKU、规格、状态与归档数量；完整 `product_id` 只在产品详情页的“系统信息”折叠区暴露。
|
|
|
|
## 3. 清理 dry-run
|
|
|
|
物理清理默认关闭。上线后先只看候选，不删除数据：
|
|
|
|
```bash
|
|
docker compose exec backend python -m service.storage_metrics --max-age-days 30
|
|
```
|
|
|
|
输出 JSON 中重点检查：
|
|
|
|
- `archive_protected_job_ids`: 已归档进产品档案的源任务，不会被临时清理。
|
|
- `asset_referenced_job_ids`: 普通画布素材引用，只反映当前引用，不是永久保护。
|
|
- `temporary_jobs`: 成功生成、30 天以上、未被产品档案保护的任务。
|
|
- `pending_product_ids`: 已进入 30 天待清理期的产品。
|
|
- `failed_cleanup` 产品不会出现在 `pending_product_ids`，需要人工检查后恢复或重新排队。
|
|
- `reclaimable_bytes`: 预计可回收空间。
|
|
|
|
服务启动和每 24 小时也会运行一次 `CleanupService.preview()`。没有设置清理开关时，它只计算候选，不删除。
|
|
|
|
## 4. 启用物理清理
|
|
|
|
确认 dry-run 报告没有误删对象后，再在部署环境中显式开启：
|
|
|
|
```bash
|
|
CLEANUP_APPLY_ENABLED=true docker compose up -d --build
|
|
```
|
|
|
|
或在既有运维体系中通过 secret/env manager 提供同名变量。开启后仍必须传入 `--apply` 才会真正删除：
|
|
|
|
```bash
|
|
docker compose exec backend python -m service.storage_metrics --max-age-days 30 --apply
|
|
```
|
|
|
|
同一 API 也可以触发，但必须同时满足：
|
|
|
|
1. `CLEANUP_APPLY_ENABLED=true`
|
|
2. `POST /api/maintenance/cleanup-run` body 为 `{"confirm": true}`
|
|
3. 使用生产订单管理口令鉴权
|
|
|
|
清理规则：
|
|
|
|
- 只清理成功生成、超过 30 天、带位置库、且当前仍不在 `product_wordcloud_archives` 中的任务。
|
|
- 每次执行前会重新检查归档引用；在预览和删除之间新归档的任务会被跳过。
|
|
- 归档保护来自产品词云档案表，不来自普通素材引用。
|
|
- 产品物理清理只在 `purge_after` 到期后发生；到期前可以恢复。
|
|
|
|
## 5. 恢复待清理产品
|
|
|
|
产品进入待清理状态后，30 天内可恢复：
|
|
|
|
```http
|
|
POST /api/products/{product_id}/restore
|
|
Authorization: Bearer <生产订单管理口令>
|
|
```
|
|
|
|
前端产品档案页会显示：
|
|
|
|
```text
|
|
待清理 · 将于 YYYY/MM/DD 删除
|
|
```
|
|
|
|
点击“恢复产品”后，产品回到 `active`，原清理记录标记为 `restored`。
|
|
|
|
删除按钮只是软删除，进入下一个 30 天可恢复窗口；真正的物理删除由清理服务执行。
|
|
|
|
## 6. `failed_cleanup` 处置
|
|
|
|
物理删除失败时，服务不会假装文件仍完整，也不会自动重试。产品进入：
|
|
|
|
```text
|
|
failed_cleanup
|
|
```
|
|
|
|
处置步骤：
|
|
|
|
1. 打开产品档案详情，确认产品状态。
|
|
2. 检查服务器上的产品目录：
|
|
|
|
```bash
|
|
docker compose exec backend sh -lc 'find /app/service_products/<product_id> -maxdepth 2 -type f -printf "%p %s\n"'
|
|
```
|
|
|
|
3. 如果目录完整且可继续使用，调用恢复接口或点击“恢复产品”。
|
|
4. 如果目录不完整，先人工恢复或确认业务上放弃该产品，再恢复后重新软删除。
|
|
5. 不要直接修改 `product_archive.db`，也不要直接把失败状态改成 `pending_cleanup`。
|
|
|
|
已放弃且确认可安全删除的失败记录，应由管理员按上述恢复/重排队流程处理；系统不会自动把它当作完整产品重试。
|
|
|
|
## 7. 回滚与部署注意
|
|
|
|
- 新版本上线前保留现有 `service_products`、`service_metadata`、`service_orders` 卷。
|
|
- 若当前环境曾把产品档案写入旧的未挂载目录，先停写并复制目录到挂载卷，再启动新版本。
|
|
- `CLEANUP_APPLY_ENABLED` 回到 `false` 后，调度器恢复为只 dry-run。
|
|
- 回滚不会自动恢复已物理删除的数据；因此首次启用物理清理必须先审查 dry-run。
|