ai-chatbot/scripts/storage/QINIU_MIGRATION.md

项目旧资源迁移到七牛

这组工具只复制应用代码和当前业务数据库引用的旧资源，不复制整桶。画布、聊天、媒体资产与业务历史记录在范围内；已删除项目的无引用文件，以及管理设置的历史审计备份，不用于扩大迁移范围。源桶保留，不删除源对象。

目标使用数据库中启用且默认的 qiniu-kodo 配置。原 OSS 资源保存在 legacy-oss/demo-sparkai/，PSD 的旧备用 S3 资源保存在 legacy-s3/gongxiangpan/。图片处理查询生成单独的 variants 对象，以保留原有裁剪、缩放结果。过期的 OSS 签名字段不保留。

先复制并验证文件长度及 MD5（流式备用传输验证 SHA256），再替换引用。替换前的配置和业务数据写入仅 root 可读的备份目录；业务更新比较旧值，保留迁移期间用户的并发编辑和画布内容修订时间。URL 形式的对象键与 |||2K 缓存后缀也按规则处理。

执行与复核

从应用根目录运行；密钥来自数据库和 .env.local，不作为命令行参数，也不写入仓库。默认工作目录为 /var/lib/ai-chatbot/aliyun-qiniu-20261014，可以用 MIGRATION_RUN_DIR 指定；MIGRATION_APP_ROOT 可指定应用目录。

1. node scripts/storage/migrate-aliyun-to-qiniu.cjs inventory-all：盘点业务引用。
2. node scripts/storage/inventory-aliyun-qiniu-source.cjs：只读列举源桶，保存所需对象的大小及 ETag，避免每个文件单独请求源站头信息。
3. node scripts/storage/migrate-aliyun-to-qiniu.cjs migrate-settings：迁移含旧 OSS 的当前设置。
4. node scripts/storage/migrate-aliyun-to-qiniu.cjs migrate-psd-extra：补齐 PSD 模板和字体的旧备用 S3 依赖。
5. node scripts/storage/migrate-aliyun-to-qiniu.cjs migrate-all：复制剩余业务引用，校验后替换地址。
6. node scripts/storage/register-aliyun-qiniu-aliases.cjs：把已验证映射登记为现有归档系统的已完成记录。旧客户端再次保存时，可复用既有地址解析逻辑；不创建待处理归档任务，不覆盖既有任务。
7. node scripts/storage/audit-aliyun-qiniu-references.cjs：复核业务引用。完成映射的来源地址是追溯信息，不是读取旧桶的依赖；审计器保留这一差别。

MIGRATION_CONCURRENCY 控制复制并发，最大 96，与模型生图并发无关。已验证对象通过 verified.jsonl 断点续跑。复制失败的对象保持旧地址，进程返回 2，需要核查失败记录；只有复制成功后才替换地址。rewrite-all 可复核已验证地址的替换，MIGRATION_RESCAN=1 会重新盘点业务表。migrate-literals 复制代码里的示例素材；代码地址修改仍需正常构建验证和部署。

migrate-recovery 从 MIGRATION_RESOURCE_FILE 指定的私有恢复清单复制已有备份，只接受配置中登记的存储来源。成功恢复的文件仍要校验。源文件不存在或为空且无有效备份时，保留记录，不能把不存在的数据宣称为迁移成功。

验证：node --test scripts/storage/migrate-aliyun-to-qiniu.test.cjs。实际迁移还验证了数据库并发更新保护、主图/SKU PSD 导出、两站上传与下载分段/CORS，以及旧画布保存时自动解析到七牛。与资源地址无关的模型、上传和聊天代码保持原样。