# 05 切换与回滚命令清单(本阶段不要在生产 html 上执行全量拷贝) 本文是操作备忘。路径以本机 2026-09-19 盘点为准。 ## 0. 前置 - E: 网盘与 `E:\nginx-1.8.0\html` **同卷**,绘本图/整本 mp3 优先硬链接,不占双倍空间。 - D: 仓库音频/JSON **跨卷**,必须复制。 - 所有脚本默认 dry-run。真正执行前先用一本可读绘本试点:`stage-03__AtTheSeaside`。 ## 1. 盘点(只读) ```powershell powershell -File tasks/data-platform/migration/00-inventory.ps1 python tasks/data-platform/migration/01-build-mapping.py ``` 产出:`migration/mapping/books.csv`、`url-rewrites.csv`。 ## 2. 试点迁移(仍建议先 DryRun) ```powershell # 只打印 powershell -File tasks/data-platform/migration/02-migrate.ps1 -FilterBookId stage-03__AtTheSeaside # 真正写入这一本 powershell -File tasks/data-platform/migration/02-migrate.ps1 -Execute -FilterBookId stage-03__AtTheSeaside ``` Linux / 服务器: ```bash export DEST=/data/easystudy/static DRY_RUN=1 FILTER_BOOK_ID=stage-03__AtTheSeaside bash tasks/data-platform/migration/02-migrate.sh ``` ## 3. 校验 ```powershell python tasks/data-platform/migration/03-hash-manifest.py --root E:/nginx-1.8.0/html/estudy --book-id stage-03__AtTheSeaside --dry-run # 落地后写 manifest: python tasks/data-platform/migration/03-hash-manifest.py --root E:/nginx-1.8.0/html/estudy --book-id stage-03__AtTheSeaside --write ``` 人工抽查: 1. 打开 `http://127.0.0.1/estudy/` 书架封面 `/estudy/images/stage-03/AtTheSeaside/002.png` 2. 阅读器整本音频(旧 URL 应被 rewrite 到 `.../AtTheSeaside/book.mp3`) 3. 确认 `/estudy/data/learning/` 返回 403/404,而不是 JSONL ## 4. Nginx 切换 1. 备份现用 conf:`copy deploy\nginx\nginx-win.conf deploy\nginx\nginx-win.conf.bak` 2. 把 `migration/nginx-estudy-static.conf.snippet` 中的 location 块替换进 `nginx-win.conf` / `nginx-win-prod.conf` / `nginx.conf`(三份结构一致,只改 `$static_root`) 3. `nginx -t` 后 reload 4. **先不要删** `html\images` 等 junction。新 alias 指向 `html\estudy\...` 后,旧 junction 仅作回滚。 可选:为让后端 `WORKHOME/images` 仍能直接读盘,把 `html\images` 从「指向网盘」改成「指向 `html\estudy\images\books`」: ```powershell cmd /c "rmdir E:\nginx-1.8.0\html\images" mklink /J "E:\nginx-1.8.0\html\images" "E:\nginx-1.8.0\html\estudy\images\books" ``` `html\audio\books` 同样改指 `html\estudy\audio\books`(注意:新树是 per-book 目录,后端 `resolve_audio_file` 需后续改为读 `book.mp3`;切换窗口靠 Nginx rewrite 保旧 URL)。 ## 5. 回滚 ```powershell powershell -File tasks/data-platform/migration/restore-junctions.ps1 # 还原 conf.bak 后 nginx -t && reload ``` 网盘源文件全程不动。硬链接删除只去掉 html 侧目录项,源文件仍在。 ## 6. 全量(仅试点通过后) ```powershell powershell -File tasks/data-platform/migration/02-migrate.ps1 -Execute python tasks/data-platform/migration/03-hash-manifest.py --root E:/nginx-1.8.0/html/estudy --write powershell -File tasks/data-platform/migration/04-pack.ps1 -Root E:\nginx-1.8.0\html\estudy -Execute ``` 不要把 `docs/data/learning`、`reading-records` 打进 zip。脚本遇到这些路径会抛错。 ## 7. 服务器打包目录建议 ``` dist/ estudy-core.zip # SPA + 小音频 + L1 catalog JSON + flashcards books/stage-03__AtTheSeaside.zip courses/opw-flashcards.zip manifests/_index.json # 各 pack id/version/checksum ``` 上传对象存储或 NAS 后,设备按 02 的 catalog/asset pack 清单按需拉取。本阶段不写同步协议。