feat: upload mdy stagging to qiniu beta

2026-06-28 22:19:02 +08:00
parent cc4607725c
commit 5f182db148
7 changed files with 1004 additions and 0 deletions
--- a/docs/mdy_plate_order_staging_qiniu_image_upload_command_2026-06-28.md
+++ b/docs/mdy_plate_order_staging_qiniu_image_upload_command_2026-06-28.md
@@ -0,0 +1,127 @@
+# 明道云开版暂存开版图上传七牛命令
+
+日期：2026-06-28
+
+## 目标
+
+将 `api_v1.MDYPlateOrderStaging.raw` 中明道云“开版图”字段的原始图片 URL 上传到七牛云，并把上传结果记录到独立审计表：
+
+- 暂存表：`api_mdy_plate_order_staging`
+- 审计表：`api_mdy_plate_order_staging_qiniu_image_upload_audit`
+- 处理字段：`raw["62d52f4b8d2972284492dd27"]`
+- URL 优先级：`original_file_full_path`、`original_file_path`、`DownloadUrl`、`download_url`、`downloadUrl`
+- 目标域名：`image.yuwen.cloud`
+
+命令不会回填或修改 `MDYPlateOrderStaging.raw`。
+
+## 命令
+
+```bash
+python manage.py upload_mdy_plate_order_staging_images_to_qiniu
+```
+
+建议先在生产/测试副本环境做只读扫描：
+
+```bash
+python manage.py upload_mdy_plate_order_staging_images_to_qiniu --dry-run
+```
+
+`--dry-run` 不写数据库、不下载、不上传，只统计会处理和会跳过的图片。
+
+## 推荐发布后执行方式
+
+先小批量执行：
+
+```bash
+python manage.py upload_mdy_plate_order_staging_images_to_qiniu --limit 100 --qps 1
+```
+
+确认审计表中的 `success/failed` 分布和七牛 URL 正常后，再放大运行：
+
+```bash
+python manage.py upload_mdy_plate_order_staging_images_to_qiniu --qps 2
+```
+
+## 重要参数
+
+- `--limit N`：最多处理 N 张候选图片，用于灰度运行。
+- `--start-id ID`：只扫描 `MDYPlateOrderStaging.id >= ID` 的记录。
+- `--qps N`：限制下载/上传速率；默认读取 `MDY_PLATE_ORDER_STAGING_QINIU_UPLOAD_QPS`，没有配置时为 `2`。传 `0` 表示不限速。
+- `--retry-failed`：重试已经明确失败的审计记录。
+- `--retry-stale-processing`：重试长时间停在 `processing` 的审计记录。
+- `--stale-after-minutes N`：配合 `--retry-stale-processing`，默认 `120` 分钟。
+- `--max-attempts N`：单张图最多尝试次数，默认 `3`；传 `0` 表示不限制。
+- `--max-image-size-mb N`：单张图最大下载大小，默认 `100MB`。
+- `--spool-max-size-mb N`：单张图内存缓冲上限，默认 `8MB`；超过后自动使用临时文件。
+- `--download-chunk-size-mb N`：流式下载块大小，默认 `1MB`。
+- `--db-chunk-size N`：Django `iterator()` 每批读取 staging 行数，默认 `500`。
+- `--timeout N`：单次下载超时时间，默认 `30` 秒。
+
+## 中断与恢复
+
+审计表就是任务游标：
+
+- `success`：已成功，有 `qiniu_key` 和 `qiniu_url`，后续默认跳过。
+- `failed`：明确失败，默认跳过；需要传 `--retry-failed` 才会重试。
+- `processing`：命令中断可能留下的处理中状态，默认跳过；需要传 `--retry-stale-processing` 才会按陈旧时间重试。
+- `skipped`：例如原始 URL 已经是七牛域名，默认跳过。
+
+重试所有明确失败：
+
+```bash
+python manage.py upload_mdy_plate_order_staging_images_to_qiniu --retry-failed --qps 1
+```
+
+重试中断留下的陈旧 `processing`：
+
+```bash
+python manage.py upload_mdy_plate_order_staging_images_to_qiniu --retry-stale-processing --stale-after-minutes 120 --qps 1
+```
+
+## 资源占用策略
+
+命令按 staging 行使用 `iterator()` 分批读取，不会一次性加载全表。
+
+每张图片独立处理：
+
+1. 创建或读取一条图片审计记录。
+2. 将状态置为 `processing` 并递增 `attempts`。
+3. 先查找同 `original_url` 的成功审计；如存在，直接复用已有七牛 URL，不重复下载上传。
+4. 如无可复用记录，则流式下载原图。
+5. 使用 `SpooledTemporaryFile`：小文件留在内存，超过 `--spool-max-size-mb` 自动落临时文件。
+6. 上传到七牛后关闭响应和临时文件。
+7. 单张图成功或失败都立即落库，不开启长事务。
+
+因此命令的内存占用主要受 `--spool-max-size-mb`、`--download-chunk-size-mb` 和单张图片大小影响，不随总记录量线性增长。
+
+## 数据核查 SQL
+
+查看状态分布：
+
+```sql
+select status, count(*)
+from api_mdy_plate_order_staging_qiniu_image_upload_audit
+group by status
+order by status;
+```
+
+查看最近失败：
+
+```sql
+select id, staging_id, mdy_rowid, attachment_index, attempts, original_url, error, updated_at
+from api_mdy_plate_order_staging_qiniu_image_upload_audit
+where status = 'failed'
+order by updated_at desc
+limit 50;
+```
+
+查看成功但 URL 非目标域名的异常记录：
+
+```sql
+select id, staging_id, mdy_rowid, qiniu_url
+from api_mdy_plate_order_staging_qiniu_image_upload_audit
+where status = 'success'
+  and qiniu_url not like 'http://image.yuwen.cloud/%'
+  and qiniu_url not like 'https://image.yuwen.cloud/%'
+limit 50;
+```