4.4 KiB
内容图片存储与本次迁移
内容图片存放于现有 RustFS（S3 兼容）prompt bucket；PostgreSQL assets 保存媒体 ID、对象键、SHA-256、大小与尺寸。代码只保留引用及必要的矢量设计源稿。
迁移结果（2026-10-29）
- 从 Git 工作树移除 603 个 PNG 路径，共 38,085,328 字节（约 36.3 MiB）。全部路径及逐文件校验信息见
apps/waterfall-wiki/src/content/managed-media.json。 - 内容寻址去重后为 572 个 S3 对象，键为
repository-media/sha256/<sha256>.png。全部上传后逐个 GET 读回并校验原始字节，再在数据库事务中登记元数据；未覆盖或删除现有媒体。 - 通过现有生产管理员认证包装器，经
/api/media/{id}再次读回全部 572 个对象，内容类型、字节数与 SHA-256 均通过。 - 清单 SHA-256：
1e13d87e204de5c4483944f381823e539bf194d124a2e5b3e1ac98c08abddb35。 - 两份 Studio 模板 JSON 的 334 处 Base64 图片均对应已迁移对象，改为媒体 ID 引用。SVG 导出时从认证媒体 API 读取并临时嵌入，下载的 SVG 仍自包含。
- 保留
public/brand-mark.svg（品牌图形）与public/learning-skills/cover.svg（可编辑设计源稿）；测试中少量合成图片字符串及运行时图片编码逻辑属于必要代码，不是业务素材副本。 - 本次直接迁移数据；未构建、未部署、未运行 CI/CD，未改写 Git 历史。旧提交仍含图片，当前线上镜像仍有原来的文件，均未破坏性清理。
按目录说明移除范围
| 路径 | 文件数 | 用途与替代 |
|---|---|---|
apps/waterfall-wiki/seed/characters/reference/*.png |
15 | 参考人物素材，导入器改从媒体 API 取原图并校验 |
apps/waterfall-wiki/seed/characters/original/*.png |
4 | 新生成人物素材，同上 |
apps/waterfall-wiki/public/skills/**/*.png |
4 | 技能参考与示例图，旧路径映射至媒体 API |
apps/waterfall-wiki/public/learning-skills/cover.png |
1 | 学习系列封面，发布器读取 S3，旧 URL 保留兼容 |
content/layout-reference/assets/**/*.png |
573 | 版式源图、构件、蒙版、标注和重建图，作者工具读取外部缓存或媒体 API |
docs/wiki-saas/screenshots/*.png |
6 | 验收截图，文档链接改指向媒体 API |
读取与恢复
旧五个公开文件路径在下一次部署此代码时通过 Next rewrites 指向现有媒体 ID；访问权限沿用原有管理员认证。预览接口直接读取 S3。运行镜像只包含人物包 JSON 和媒体清单，不再包含 PNG。
作者工具 scripts/managed-media.mjs 从媒体 API 下载并验证图片；可设置 MEDIA_BASE_URL（默认现有服务器地址）与进程环境中的 PROMPT_TOKEN。不要将令牌写入源码、命令参数或报告；重定向不会携带凭据。运行于服务器的作者脚本可通过现有 auth-cli.cjs run 包装器，在同源 MEDIA_BASE_URL=http://127.0.0.1:3000 下使用进程内认证。
也可设置 MEDIA_SOURCE_ROOT 指向仓库外缓存，目录结构与清单相同。本次原文件备份位于仓库外路径：/Users/zzyang/ProjectMedia/output/s3-media-migration-20261029/source。该备份不提交 Git。
node scripts/managed-media.mjs /absolute/external-cache 可下载整个清单到外部目录，拒绝写入仓库。版式封面生成器要求 MEDIA_OUTPUT_FILE 指向仓库外；分割工具使用仓库外 MEDIA_AUTHORING_ROOT。产出新素材后先上传 S3、登记数据库与清单，再更新引用；不要提交 PNG 或把图片转成 Base64 塞回 JSON。
灾难恢复必须同时保留数据库备份和 S3 bucket。清单只保存索引，不替代数据库或对象存储备份。新环境需恢复所需对象及其 assets 元数据；隔离集成测试使用合成图片，不读取生产素材。
检查结果
- 16 项 Studio 单元测试、3 项清单与缓存测试、2 项人物包校验测试通过；JavaScript 语法及
git diff --check通过。 - Studio
tsc --noEmit --incremental false通过。 - Wiki 同一类型检查因本地已有依赖未安装完整（
nodemailer无法解析）未通过；本次未安装依赖、未运行 Next typegen。 - 完整集成测试、应用构建和部署未执行。用户要求此次不用 CI/CD；工作分支与 PR 不触发当前仅 main push 的工作流。用户后续手动合并 main 将按现有规则触发 CI/CD，须自行安排合并时机。