44 lines
4.4 KiB
Markdown
44 lines
4.4 KiB
Markdown
# 内容图片存储与本次迁移
|
||
|
||
内容图片存放于现有 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，须自行安排合并时机。
|