Updates and Backups zh CN - on22s/Side-Story GitHub Wiki

English · 简体中文 · 日本語

更新与备份

在更新、重置、迁移安装位置，或尝试大规模训练／资料库任务之前，请先保存工作并做好备份。Git 跟踪的是应用代码，不会备份你生成的有声书项目。

返回首页 · 相关页面：安装、脚本与审校、故障排查

更新之前

  1. 等待正在进行的生成、审校、渲染、数据准备、训练和导出任务完成；或在界面中取消任务，并等待它们停止。
  2. 将当前脚本保存到 Script library（脚本库），并保留需要的快照／检查点。保存脚本很有用，但它并不等于备份音频、上传的源文件、全部设置或所有资料库。
  3. 停止应用，以及另外启动的、正在向应用数据写入内容的进程。
  4. 将实际使用的数据和设置目录复制到单独的备份位置。应包含配套文件和子目录，不能只复制主 JSON 文件。
  5. 记录当前检出的修订版本，以及本地代码／环境改动，以便确认这份备份是由哪个安装版本产生的。

复制前停止所有写入进程，有助于避免把不同时间点的 JSON 状态、检查点分片和音频混在同一份备份中。原始书籍源文件和不可替代的录音也应另行独立保存。

Pinokio 或普通代码检出目录中需要备份的内容

未覆盖数据路径时，检出目录的根目录就是可变数据的根目录，而设置和上传文件仍使用原来的 app/ 位置。

内容 默认需要保留的位置
应用设置 app/config.json
当前书籍与声音状态 annotated_script.json、chunks.json、state.json、voices.json、voice_config.json、character_aliases.json，以及相关配套文件／日志文件
生成／审校进度 检查点头文件及其匹配的分片目录，以及脚本旁的快照、质量清单和审校记录
上传的源文件 app/uploads/
已保存的脚本 整个 scripts/，包括配套的声音配置和元数据
生成与导出的音频 voicelines/、cloned_audiobook.mp3、audiobook.m4b、按章节导出的文件，以及任何另行保存／下载的导出 ZIP 文件
可复用声音与角色配音信息 voice_library.json、designed_voices/、clone_voices/
训练与数据集工作 lora_models/（包括其清单和元数据）、lora_datasets/、dataset_builder/、preparer_output/，以及任何外部数据集目录
高级设置与证据记录 voicelab_config.json、reports/、run_history/、evaluation_reviews/，以及你希望保留的日志
单独提供的资源 本地 GGUF 文件、自定义模型／解释器设置、已下载的内置适配器，以及存放在上述目录之外的参考文件

最稳妥的完整快照，是在停止运行后复制整个检出目录，再加上所有已配置的外部数据／资源。只有在确定知道如何重建时，才排除环境目录或可重新下载的缓存。不要从其他操作系统恢复 Python 环境，也不要认为复制过来的 GPU 环境可以直接通用。

请完整复制同一组检查点文件。头文件可能引用同级目录中名为 *.parts-<id> 的目录；只复制 JSON 文件可能导致检查点无法使用。同样，应将分块状态日志与其匹配的 chunks.json 快照一并保留，不能混用不同备份中的文件。

自定义路径

  • ALEXANDRIA_DATA_DIR 用于迁移应用的可变数据根目录。使用非默认数据根目录时，上传文件位于其中的 uploads/ 子目录，配置默认保存在其中的 config.json。
  • ALEXANDRIA_CONFIG_PATH 可独立覆盖设置文件的路径，即使数据根目录位于其他位置也是如此。
  • Voice Lab（声音实验室）、Preparer（数据准备工具）、自定义克隆参考文件和外部工具可能指向其他目录。请单独备份这些目录。
  • 内置适配器资源仍与检出目录中的 builtin_lora/ 关联，仅备份自定义数据根目录并不能涵盖这些资源。

请记录这些路径和你使用的环境变量名称。注意保护备份的访问权限：配置中可能包含 API 密钥，脚本、录音和日志也可能包含私密文本或声音数据。env:NAME 形式的密钥引用不包含密钥本身；在新安装中，应以安全方式恢复相应的环境变量。

使用 Pinokio 更新

  1. 完成上述备份步骤。
  2. 选择 Update（更新）。
  3. 观察终端。启动器会停止它已知的写入进程，运行 git pull，然后重新运行核心安装程序。
  4. 如果 Git 报告本地改动或冲突，请保留这些改动，并有意识地处理问题。不要仅为了完成更新而丢弃文件。
  5. 安装完成后，启动应用，并检查 Setup（设置）、已保存的脚本、声音库以及一小段音频样本。
  6. 如果更新改变了可选的原生依赖项，请先停止应用，再重新运行 Install Voice Tools (Optional)（安装声音工具，可选），然后再使用相关阶段的功能。

更新不能保证中断的任务可以恢复，也不能保证旧检查点与发生变化的输入／设置／代码兼容。请保留备份，直到重要工作能够打开，且小规模测试通过。Reinstall（重新安装）会重新运行核心依赖安装程序；它与 Reset（重置）不是同一操作，本身也不会拉取新代码。

Docker 升级

使用随项目提供的 Compose 配置时：

  1. 等待正在进行的任务停止后，使用 docker compose stop 停止服务。
  2. 备份整个 data/，而不仅是 data/runtime/。现有资料库、设置、上传文件和音频片段是从同级目录挂载的。
  3. 如果不想重新下载权重，请保留现有的 Hugging Face 命名缓存卷。不要把删除卷的命令当作常规升级步骤。
  4. 更新检出目录，并在同一项目目录中使用 docker compose up --build 重新构建并启动。
  5. 删除任何备份之前，先检查设置、资料库，并运行一个小任务。

随项目提供的配置设置了：

  • ALEXANDRIA_DATA_DIR=/alexandria/runtime，挂载自 data/runtime
  • ALEXANDRIA_CONFIG_PATH=/alexandria/config/config.json，由 data/config 提供持久化存储
  • 在运行时目录树下分别挂载资料库／上传文件／音频目录，保留现有的宿主机目录布局

此布局不需要迁移宿主机数据。旧的容器内路径，例如 /alexandria/scripts、/alexandria/voicelines 和 /alexandria/app/uploads，都是指向运行时位置的符号链接。如果用自定义部署替代 Compose，请同时保留配置和运行时数据的持久化存储。

重置警告：会移除当前工作

**Pinokio 的 Reset（重置）具有破坏性。不要把它当作通用的故障排查捷径。**它会停止由启动器管理的写入进程，并删除检出目录下的这些默认路径：

annotated_script.json
voices.json
voice_config.json
character_aliases.json
state.json
app/config.json
chunks.json
cloned_audiobook.mp3
voicelines/

这会移除当前脚本、当前声音分配／状态、已生成的音频片段、合并后的 MP3，以及默认设置文件。重置脚本会保留可复用的资料库，例如已保存的脚本、设计声音／克隆声音和训练资料库。

重置清单是明确列出的，并使用默认检出目录路径。它不是完整的数据擦除工具，未列出所有报告／检查点／导出文件，也不应假定它会清空自定义数据／配置目录。反过来，保留资料库也不意味着保留了上面列出的当前项目。请先备份；如果你的安装方式有所不同，请检查 reset.js。

恢复与验证

请在安装实例停止运行时恢复数据。将每份当前书籍快照、其配套文件、声音配置和音频放在一起恢复。恢复资料库时，请连同其清单和元数据一起恢复，再恢复到正确的设置路径，并还原所有必需的环境变量。

在继续长时间任务之前：

  • 确认加载的是预期的书籍源文件和脚本。
  • 确认克隆参考文件和适配器路径能够解析到真实文件。
  • 试听已有音频，并生成一小段测试台词。
  • 查看可用的恢复控件；更改源文件、模型或设置后，不要假定检查点仍然有效。
  • 在上述检查成功之前，不要改动备份。

有关音频就绪状态和最终输出，请参阅渲染与导出。

来源

依据已发布的 main 分支版本 8c7a33cb310ab9264594a09ca27e48271585094f 核对：更新、重置、运行时路径、路径覆盖、已保存脚本的配套文件、检查点存储、Docker 持久化。