# 03 静态资源物理迁移 > 所属:`tasks/data-platform/`(三路并行设计 · 本路) > 版本:v1.0(2026-09-19 本机盘点) > 范围:**Nginx 静态树、中文网盘路径 → ASCII slug、全量迁移跑法、部署包 / manifest、URL 稳定性** > 非范围:不写 SQLite/MySQL DDL(`01-*`)、不写同步协议正文(`02-*`)、不 git commit、**本阶段不执行全量拷贝** > 与 02 对齐:只处理 L1 媒体与目录 JSON;课程包 = 规则/id 列表;资源包 = 页图+音频+structured。打包扫到 `learning/`、`reading-records/`、`profile`、`srs`、报告必须失败。checksum = SHA-256。 脚本与表:[`migration/`](./migration/README.md)。 --- ## 0. 一句话结论 当前 `$workhome`(`E:\nginx-1.8.0\html`)里的图片、绘本音频、闪卡都是 **junction 指向 `E:\BaiduNetdiskDownload` 下的中文路径**,`/estudy/data/` 还把学习记录一并暴露出去。目标是把运行时资源落到 **`html/estudy/` 下全 ASCII 树**,Win/Linux Nginx 用同一套 alias,URI 继续走 `/estudy/images`、`/estudy/audio`、`/estudy/flashcards`。同卷硬链接试点后可打包;按绘本 `stage__slug` 出 `manifest.json`(文件列表 + 尺寸 + sha256)。网盘源只读保留,随时可回滚 junction。 --- ## 1. 现状(2026-09-19 本机) ### 1.1 配置锚点 | 项 | 值 | | --- | --- | | 后端 `WORKHOME` | Windows 默认 `E:\nginx-1.8.0\html`;Linux `/data/easystudy/static` | | `HOST` / `CONTEXT` | `EASYSTUDY_HOST` 默认可空(同源);`EASYSTUDY_CONTEXT=/estudy` | | `IMAGES_DIR` | `$workhome/images` | | `AUDIO_BOOKS_DIR` | `$workhome/audio/books` | | `TTS_OUTPUT_DIR` | `$workhome/audio/tts-words` | | `DATA_DIR` | `$workhome/data`(junction → 仓库 `docs/data`) | | Nginx root | Win:`E:/nginx-1.8.0/html`;Linux:`/data/easystudy/static` | | `charset` | Win conf 为 **gbk**;Linux 为 utf-8 | `win-link.bat` / `linux-link.sh` 把分散源汇总成「URI 子路径 = `$workhome` 子目录」。Linux 脚本默认还写着 `/mnt/e/BaiduNetdiskDownload/牛津树/...`,**不能原样用于服务器打包**。 ### 1.2 软链接实测(`Get-Item` / `dir /AL`) `html` 本身不是链接。`html\audio`、`html\estudy` 是普通目录。其余: | html 路径 | LinkType | 指向 | | --- | --- | --- | | `images` | Junction | `E:\BaiduNetdiskDownload\牛津树\牛津树1-14阶段PDF+音频\images` | | `audio\books` | Junction | `E:\BaiduNetdiskDownload\牛津树\牛津树1-14阶段PDF+音频`(**整棵树**,含 PDF/images) | | `flashcards` | Junction | `E:\BaiduNetdiskDownload\牛津自然拼读课件+课程\01 电子教材【1-5级 视频+PDF+音频+课件+白板软件】\5.flash-cards` | | `data` | Junction | `D:\codes\MyProjects\easy-study\docs\data` | | `audio\tts-words` | Junction | 仓库 `audio\tts-words` | | `audio\en` / `cn` | Junction | `251228-words\audio\en` / `cn` | | `audio\phonemes` | Junction | `251228-words\audio\pho-v2` | | `audio\ipa` | Junction | `251228-words\video-cut\server\output` | | `audio\words` | Junction | `D:\codes\english\download` | 未进 `win-link.bat`、但是已在 html 下:**`audio\cambridge`**(实体目录,约 822MB)。 完整表:[`migration/mapping/current-junctions.csv`](./migration/mapping/current-junctions.csv)。 ### 1.3 网盘顶层(可访问,未拷贝) `E:\BaiduNetdiskDownload` 存在。与本产品相关的只有: | 顶层 | 约体积 | 现网是否挂到 Nginx | | --- | --- | --- | | `牛津树\`(含 zip) | 21.1 GB(目录 18.1 + zip 3.0) | 是(images + 整棵当 audio/books) | | `牛津自然拼读课件+课程\` | 67.1 GB | **仅** `5.flash-cards`(926 MB) | 同盘还有 Peppa、Bluey、YLE 真题、高中教材等,**不进 Easy Study 迁移范围**。 牛津树 `牛津树1-14阶段PDF+音频\` 结构:`images/stage-NN//*.png` + `stage-NN/*.mp3` + `stage-NN/PDF/` + 部分 `stage-NN/音频/` 重复 mp3。页图是未压缩 PNG(样例单页 4–7MB)。 拼读课件四包: | slug(拟定) | 原名 | 体积 | 现网 | | --- | --- | --- | --- | | `opw-flashcards` | `01 .../5.flash-cards` | 926 MB | 已挂 | | `opw-phonics-core` | `01 电子教材...` 整包 | 47.3 GB | 否(含白板 ISO、游戏、点读包) | | `opw-fufu-video` | `02 付付老师...` | 8.0 GB | 否 | | `opw-moli-video` | `03 茉莉老师...` | 8.3 GB | 否 | | `opw-lexue-video` | `04 乐学无忧...` | 3.5 GB | 否 | ### 1.4 仓库内已有资源 vs Nginx alias | 仓库路径 | html / URI | 体积 | | --- | --- | --- | | `docs/data` | `/estudy/data/` | 17.1 MB(含 learning 0.3 MB) | | `audio/tts-words` | `/estudy/audio/tts-words/` | 0.2 MB(28 个 mp3) | | `251228-words/audio/pho-v2` | `/estudy/audio/phonemes/` | 约数 MB | | `251228-words/audio/en` `cn` | `/estudy/audio/en` `/cn` | 合计约 17 MB | | `251228-words/video-cut/server/output` | `/estudy/audio/ipa/` | 1.6 MB | | `D:\codes\english\download`(仓外) | `/estudy/audio/words/` | 1.02 GB / 79667 mp3 | | 绘本图、整本 mp3、闪卡 | 不在 git,只在网盘 | 见上 | `docs/data/learning/` 已 gitignore;`reading-records/` 仍有测试 JSON。二者都在 `/estudy/data/` 静态树里,**任何人能猜 URL 就能拉学习记录**(02 已标隐私缺口)。 ### 1.5 绘本 URL 怎么拼(不要改 API JSON 形状) `docs/data/book-index.json`:14 个 stage,**364 本**。字段 `img_folder`(PascalCase)、`img_path` = `images/{stage}/{img_folder}/`、`book_title`、`pdf_path`。index 里 **不存绝对 URL**。 运行时: 1. 页图:`config.image_url(stage, book_folder, file)` → `{CONTEXT}/images/{stage}/{img_folder}/{file}`,例如 `/estudy/images/stage-03/AtTheSeaside/002.png`。`file` 来自 structured 或扫盘(`000.png`…)。书架封面前端写死 `002.png`。 2. 整本音频:`resolve_audio_file` 在 `$workhome/audio/books/{stage}/` 下用 `book_title` / `img_folder` / 空格化 / `Chip's` HTML 实体 / pdf 文件名 匹配 **真实 mp3 文件名**,再 `quote` 进 URI。因此现网是 `/estudy/audio/books/stage-01/Chip%26%2339%3Bs%20Robot.mp3` 这类,而不是 `img_folder.mp3`。 3. 单词:`/estudy/audio/tts-words/{accent}/{voice}/{word}.mp3`,回退 `/audio/words`、`/audio/en`、`/audio/nas`(NAS 反代,不进包)。 4. 闪卡:curriculum `letters.json` 写死 `/estudy/flashcards/letters/...`。 后端另 `mount /images` 作直连兜底;经 Nginx 入口时走 alias。 映射脚本实扫:**363/364 有页图**(缺 `Chip'sRobot1` 空壳)、**350/364 有 mp3**(14 本缺音频,多在 12–14 级与 title 对不上的撇号书)。40 本 `img_folder` 含撇号/弯引号/`!`/逗号,物理目录要 slug。 --- ## 2. 目标目录规范 统一静态根 `$static_root`(Win `E:/nginx-1.8.0/html`,Linux `/data/easystudy/static`)。**禁止** Nginx alias 再指向网盘中文路径。 ``` $static_root/ estudy/ # 可整目录打包 index.html, assets/ # SPA images/books/{stage}/{fs_slug}/*.png audio/books/{stage}/{fs_slug}/book.mp3 audio/tts-words/{accent}/{voice}/{word}.mp3 audio/phonemes/ audio/en/ audio/cn/ # 旧词库,进 core audio/ipa/ # 可选 audio/words/ # 可选词典包,不进 core courses/opw-flashcards/ # 现 /estudy/flashcards courses/{course_id}/ # 后续视频/PPT 包 data/ # 仅 L1 catalog book-index.json book-structured/{stage}/ book-ocr/{stage}/ book-key-words/{stage}/ curriculum/ manifests/ core-runtime.json book/{book_id}.json course/{course_id}.json ``` **ID:** - `book_id` = `{stage}__{fs_slug}`(与 02「按绘本 `stage__folder`」一致) - `fs_slug`:NFKC → 弯引号变 ASCII → 去掉 `'` → `!?,` 等变 `-` → 只留 `[A-Za-z0-9._-]` - `AtTheSeaside` 不变 - `Chip'sRobot` → `ChipsRobot` - `Biff’sAeroplane` → `BiffsAeroplane` - `Oh,otto!` → `Oh-otto` - `course_id`:上表 `opw-*` Nginx 把 `/estudy/images/` **alias 到** `estudy/images/books/`,因此对外仍是 `/estudy/images/{stage}/{slug}/`,不必把 `books` 暴露进 URI。 `html/images`、`html/audio/books` 在切换后可改成指向新树的 junction,让后端 `WORKHOME/images` 继续能读盘;这是本地便利,服务器只部署 `estudy/` 即可。 --- ## 3. 中文路径 → slug 映射 机器表(本机已生成,未拷贝): - [`migration/mapping/books.csv`](./migration/mapping/books.csv) — 364 本 ×(图+音频) - [`migration/mapping/url-rewrites.csv`](./migration/mapping/url-rewrites.csv) — 390 条(40 条图前缀 + 350 条旧 mp3 文件名) - 手写样例:[`example-books.csv`](./migration/mapping/example-books.csv)、[`example-courses.csv`](./migration/mapping/example-courses.csv) 列:`source_path → dest_path → book_id/course_id → public_url → rewrite_from → method(hardlink|copy|deny)`。 同卷(E: 网盘 → E: html)**硬链接**;跨卷(D: 仓库 → E: html)**复制**。 --- ## 4. 全量迁移跑法(草稿,默认不拷贝) 原则:源只读;先一本试点;哈希校验后再切 Nginx;旧 junction 留到确认。 1. `00-inventory.ps1` 确认链接仍指向网盘。 2. `01-build-mapping.py` 刷新 CSV。 3. `02-migrate.ps1 -FilterBookId stage-03__AtTheSeaside`(DryRun)再 `-Execute`。同卷 `New-Item HardLink`,跨卷 `Copy-Item`。Linux:`02-migrate.sh` + `os.link` / `cp -a`。 4. `03-hash-manifest.py --write`:每文件 sha256;包 checksum = 对「path + bytes + sha256」排序后的 sha256。扫到用户数据 → 退出码非 0。 5. 浏览器:封面、翻页、整本音频、闪卡;`/estudy/data/learning/` 必须 403。 6. 替换 Nginx location(见 §6),`nginx -t` && reload。 7. 可选:把 `html\images` junction 从网盘改到 `html\estudy\images\books`。 8. 全量 `-Execute`(约 16.7GB 运行时子集;硬链接几乎不占新空间)。 9. 回滚:`restore-junctions.ps1` + conf.bak。删硬链接 **不会** 删网盘源。 不要用 `robocopy` 指向 `NUL` 做计量(本机已卡住)。体积用 Python `getsize` 遍历。真拷贝跨卷时可用: ```text robocopy /E /COPY:DAT /DCOPY:DAT /XJ /R:2 /W:5 /NP /LOG:migrate-robocopy.log ``` 同卷优先硬链接,避免 14GB PNG 双份。 --- ## 5. 打包(不含学习记录) | 包 | 内容 | 约体积 | 拉取粒度 | | --- | --- | --- | --- | | `core-runtime` | SPA + tts/phonemes/en/cn + `data/` L1 + `opw-flashcards` | ~1GB(闪卡为主) | 安装一次 | | `book:{book_id}` | 页图 + `book.mp3` + 若有 structured/key-words | 单本通常 30–80MB(PNG 很大) | 按绘本 | | `course:{course_id}` | 课件/视频选修 | 3–47GB | 按课程,家庭 NAS 可全量 | | `dict-words` | `/audio/words` | 1GB | 可选 | **禁止入包:** `learning/**`、`reading-records/**`、`reports/**`、`srs.json`、`profile.json`、`days.json`、测试孩子 `apitest` 等、牛津 PDF/zip/扫描脚本、拼读白板 ISO/游戏(除非单独 course pack)、网盘无关目录。 `manifest.json` 最小字段(02 要求 + 本路补全): ```json { "id": "book:stage-03__AtTheSeaside", "kind": "book", "version": "1", "checksum": "", "checksum_alg": "sha256-of-sorted-path-bytes-sha256", "items": [ { "path": "images/books/stage-03/AtTheSeaside/002.png", "bytes": 0, "sha256": "" }, { "path": "audio/books/stage-03/AtTheSeaside/book.mp3", "bytes": 0, "sha256": "" } ] } ``` 设备侧只存 `pack_id + version + checksum` 与本地文件指针(02);文件落盘即上述树。 --- ## 6. Nginx:Win / Linux 同一结构 草稿:[`migration/nginx-estudy-static.conf.snippet`](./migration/nginx-estudy-static.conf.snippet)。 | URI | alias | | --- | --- | | `/estudy/images/` | `$static_root/estudy/images/books/` | | `/estudy/audio/` | `$static_root/estudy/audio/` | | `/estudy/audio/tts-words/` | 同上树内(更具体 location 保留) | | `/estudy/flashcards/` | `$static_root/estudy/courses/opw-flashcards/` | | `/estudy/data/` | `$static_root/estudy/data/`(仅 L1) | | `/estudy/data/learning/` `/reading-records/` | **deny all** | `charset utf-8`(ASCII 化后 Win 不必 gbk)。`/estudy/audio/nas/` 仍是局域网反代,不进包。切 loc 后 **停用** `win-link.bat` 对网盘的依赖;脚本仅作 `restore-junctions.ps1` 回滚。 后端 `EASYSTUDY_WORKHOME` 可继续指向 `$static_root`,或显式: - `EASYSTUDY_IMAGES_DIR=$static_root/estudy/images/books` - `EASYSTUDY_AUDIO_BOOKS_DIR=$static_root/estudy/audio/books` - `EASYSTUDY_TTS_DIR=$static_root/estudy/audio/tts-words` - `EASYSTUDY_DATA_DIR` 指向 **不含用户目录的 catalog 副本**(学习记录改走 API,见 02) `resolve_audio_file` 仍按「stage 目录下 title.mp3」找文件;切到 `.../{slug}/book.mp3` 后,HTTP 靠 rewrite,**磁盘解析要跟一次小改**(实现阶段,不在本设计里改代码)。过渡期也可在 `{stage}/` 再硬链接一份旧文件名。 --- ## 7. URL 稳定性与重写 尽量不断的前缀:`/estudy/images/`、`/estudy/audio/`、`/estudy/flashcards/`、`/estudy/audio/tts-words/`、`/estudy/audio/phonemes/`。 | 情况 | 旧 URI | 新物理 | 是否要 rewrite | | --- | --- | --- | --- | | 324 本 img_folder==slug | `/estudy/images/stage-03/AtTheSeaside/002.png` | `estudy/images/books/stage-03/AtTheSeaside/` | 否(仅 alias 插入 `books/`) | | 40 本特殊文件夹名 | `/estudy/images/stage-01/Chip'sRobot/` | `.../ChipsRobot/` | **是**(前缀 map) | | 几乎全部整本 mp3 | `/estudy/audio/books/stage-03/At the Seaside.mp3` | `.../AtTheSeaside/book.mp3` | **是**(精确 location 或 map) | | 闪卡 | `/estudy/flashcards/...` | `courses/opw-flashcards/` | 否 | | 非正式旁路 | `/estudy/audio/books/images/...`、`.../PDF/` | 删除 | **故意 404**(切断泄漏) | | 公开学习记录 | `/estudy/data/learning/...` | 不部署 | **403** | 完整 rewrite 表见 `url-rewrites.csv`。实现可用 `map $uri $asset_rewrite` 或由脚本生成一串 `location =`。 前端 `withBase('/images/...')` 与 API `image_url` 在 rewrite 存在期间都不必改。长期可让 API 直接吐 slug URL,rewrite 只服务缓存/旧客户端。 --- ## 8. 风险 | 风险 | 影响 | 缓解 | | --- | --- | --- | | 中文路径 + Win `charset gbk` | 服务器/Linux 打包断链、URL 编码混乱 | 物理树 ASCII;utf-8;不再 alias 网盘 | | 页图 14.2GB PNG | 全量包过大、蜂窝无法下 | 硬链接本地;按书包;后续可转 jpeg(另任务) | | 拼读 67GB 视频/ISO | 误把 01 整包打进 core | 运行时只迁 flashcards;视频单独 course_id | | `audio/books` 指向整棵牛津树 | 已泄漏 PDF/图片;迁移后旁路 404 | 文档声明非正式 URL 作废 | | 撇号 / `'` / 弯引号 | 图目录与 mp3 文件名不一致,14 本音频未匹配 | mapping 标 missing;人工补;rewrite 覆盖已匹配的 350 本 | | `Chip'sRobot1` 无页图 | index `has_images=true` 不准 | 不打资源包或从 index 剔除 | | 跨卷 D:→E: | 不能硬链接 | copy;core 音频很小 | | `/estudy/data/` 过宽 | 学习记录可匿名下载 | deny + 包内无 L3 | | 后端仍按 title.mp3 找盘 | 切目录后工具链/API 解析失败 | 过渡期旧名硬链接,或改 `resolve_audio_file` | | 路径长度 / 权限 | Windows junction 替换失败 | 只 rmdir junction,不 del 源 | | NAS `/audio/nas/` | 服务器无 192.168.11.94 | 包内用 tts/en;nas 仅局域网 | --- ## 9. 分阶段执行 | 阶段 | 做什么 | 完成标准 | | --- | --- | --- | | **P0 方案(本阶段)** | 盘点、mapping 脚本、Nginx 草稿、禁止全量拷贝 | 本文 + `migration/` | | **P1 试点** | 硬链接 1 本可读书(建议 `stage-03__AtTheSeaside`)+ tts/phonemes 复制 + data L1(排除 learning) | 该书封面/音频通;learning 403 | | **P2 运行时全量** | 363 本图 + 350 本 mp3 硬链接;flashcards;core 音频 | mapping 行校验条数;抽查 1–4 级与一本撇号书 | | **P3 Nginx 切流** | 三份 conf 结构对齐;rewrite 表编译进 conf;停用网盘 alias | `nginx -t`;旧 junction 仍在 | | **P4 打包** | `estudy-core.zip` + 按书 zip + manifests | 打包脚本拒绝用户数据;checksum 可复算 | | **P5 收尾** | 后端 `IMAGES_DIR`/`resolve_audio_file` 认 slug;可选 jpeg;视频 course pack | 实现阶段;可回滚 | P1 未过不要开 P2。网盘中文目录作为只读源保留到 P4 以后。 --- ## 10. 给 01/02 的接口(无 DDL、无协议正文) - 资源主键:`book_id`、`course_id`、`pack_id`(`book:{book_id}` / `course:{course_id}` / `core-runtime`)。 - 清单字段:`id, version, checksum, checksum_alg, items[{path,bytes,sha256}]`。 - 下载 URL 仍可映射到现有 `/estudy/images`、`/estudy/audio`、`/estudy/flashcards`。 - L3/L4 不进包、不进公开 alias。设备文件布局即 §2。