备份与恢复工具指南

版本 v1.0 · 2026-07-07 · backup.py · rollback.py · 操作手册 · 故障排除

1. 环境准备 2. backup.py 使用指南 3. rollback.py 使用指南 4. 常见场景操作手册 5. 与部署流水线的关系 6. 故障排除

1. 环境准备▶

Python 路径 · 脚本位置 · 备份仓库 · 基本用法

环境配置一览

项目	路径 / 值	说明
Python 路径	`C:\Users\徐\.workbuddy\binaries\python\versions\3.13.12\python.exe`	项目内置 Python，无需全局安装
backup.py	`canvas/backup.py`	备份脚本，位于 canvas 根目录
rollback.py	`canvas/rollback.py`	回滚脚本，位于 canvas 根目录
备份仓库	`d:\网文剧本\bloodbound-backups\`	所有备份存放于此，按时间戳命名
备份上限	20 个	超出后自动轮转清理最旧的备份

基本用法

两个脚本都需要先 cd 到 canvas 目录，再用 Python 执行。示例：

cd /d d:\网文剧本\bloodbound\canvas
C:\Users\徐\.workbuddy\binaries\python\versions\3.13.12\python.exe backup.py

备份仓库结构

d:\网文剧本\bloodbound-backups\
├── bak_20260701_0930\         ← 常规备份（时间戳命名）
├── bak_20260702_1415\         ← 常规备份
├── bak_safety_20260703_1020\  ← 安全备份（回滚前自动创建）
└── ...                        ← 保留最近 20 个版本

备份使用 shutil.copytree 全量复制，自动忽略 .git、node_modules、__pycache__ 等目录。单次备份约 1.6 MB，20 个版本约 32 MB。

2. backup.py 使用指南▶

创建备份 · 验证备份 · 列出备份 · 清理旧备份

命令总览

命令	功能	输出
`python backup.py`	创建完整备份	备份路径 + 文件数
`python backup.py --verify`	验证最新备份完整性	文件数对比 + 顶层目录列表
`python backup.py --list`	列出所有备份	序号 + 名称 + 文件数
`python backup.py --clean`	清理旧备份	保留最近 20 个，删除最旧的

详细说明

python backup.py — 创建完整备份

将 canvas 目录中所有文件全量复制到 d:\网文剧本\bloodbound-backups\bak_时间戳\。同一分钟内重复执行会自动追加序号。备份完成后自动触发轮转检查，超出 20 个时清理最旧的。

[备份] 正在备份: d:\网文剧本\bloodbound\canvas
[备份] 目标路径: d:\网文剧本\bloodbound-backups\bak_20260707_1430
[备份] 源文件数: 42
[备份] 备份文件数: 42
[完成] 备份成功！当前共有 5 个备份

python backup.py --verify — 验证最新备份

检查最新备份目录是否包含文件，并列出顶层目录/文件。用于备份后立即确认完整性。

[验证] 正在验证最新备份: bak_20260707_1430
[验证] 备份文件数: 42
[验证] 备份看起来正常，包含 42 个文件
[验证] 顶层目录/文件 (12 项):
  - characters.html  [文件]
  - index.html  [文件]
  - references  [目录]
  - style.css  [文件]
  ...

python backup.py --list — 列出所有备份

显示备份仓库中所有 bak_* 目录，按时间排序。方便找到特定时间点的备份。

[列表] 共有 5 个备份:

  序号  备份名称                   文件数
  -----------------------------------------
  1     bak_20260701_0930          40
  2     bak_20260702_1415          41
  3     bak_20260703_1020          42
  4     bak_safety_20260705_0800   42
  5     bak_20260707_1430          42

python backup.py --clean — 清理旧备份

当备份数超过 20 个时，删除最旧的备份，保留最近 20 个。未超出上限时不做任何操作。

[清理] 将删除 3 个旧备份，保留最近 20 个:

  删除: bak_20260601_0800
  删除: bak_20260602_0900
  删除: bak_20260603_1000

[清理] 完成，剩余 20 个备份

3. rollback.py 使用指南▶

列出备份 · 恢复最新 · 恢复指定 · 预览模式 · Git 回退

命令总览

命令	功能	安全机制
`python rollback.py`	列出可用备份	无操作（仅显示）
`python rollback.py --latest`	恢复最新备份	自动创建安全备份
`python rollback.py --backup 名称`	恢复指定备份	自动创建安全备份
`python rollback.py --dry-run --latest`	预览恢复内容	无操作（仅预览）
`python rollback.py --git 提交哈希`	Git 回退到指定提交	自动创建安全备份

详细说明

python rollback.py — 列出可用备份

不带任何参数时，显示所有可用备份及其文件数、类型（常规/安全）。同时输出恢复命令提示。

[列表] 可用备份（共 5 个）:

  序号  备份名称                        文件数      类型
  --------------------------------------------------------
  1     bak_20260701_0930              40          常规备份
  2     bak_20260702_1415              41          常规备份
  3     bak_20260703_1020              42          常规备份
  4     bak_safety_20260705_0800       42          安全备份
  5     bak_20260707_1430              42          常规备份

用法:
  python rollback.py --latest              # 从最新备份恢复
  python rollback.py --backup bak_20260707_1430  # 从指定备份恢复
  python rollback.py --dry-run --latest     # 预览模式

python rollback.py --latest — 恢复最新备份

自动选择最新的常规备份（跳过安全备份），将其内容恢复到 canvas 目录。恢复前自动创建 bak_safety_* 安全备份，确保当前内容不会丢失。

[安全备份] 正在创建回滚前安全备份...
[安全备份] 完成: bak_safety_20260707_1500（42 个文件）
[恢复] 备份来源: bak_20260707_1430（42 个文件）
[恢复] 恢复目标: d:\网文剧本\bloodbound\canvas
[恢复] 正在清理当前目录...
[恢复] 正在从备份复制文件...

[恢复] 恢复完成！
[恢复] 备份文件数: 42
[恢复] 当前文件数: 42

python rollback.py --backup 名称 — 恢复指定备份

从 --list 输出中选择特定备份名称进行恢复。同样会自动创建安全备份。

python rollback.py --backup bak_20260703_1020

[安全备份] 正在创建回滚前安全备份...
[安全备份] 完成: bak_safety_20260707_1505（42 个文件）
[恢复] 备份来源: bak_20260703_1020（42 个文件）
...
[恢复] 恢复完成！

python rollback.py --dry-run --latest — 预览恢复

预览模式：列出将被恢复的文件清单，但不做任何实际更改。适合在恢复前确认操作范围。--dry-run 可与 --latest、--backup、--git 组合使用。

[恢复] 备份来源: bak_20260707_1430（42 个文件）
[恢复] 恢复目标: d:\网文剧本\bloodbound\canvas

[预览模式] 以下文件将被恢复:
  characters.html
  index.html
  style.css
  references/protagonists.md
  ... 还有 38 个文件

[预览模式] 共 42 个文件将被恢复，未做任何更改

python rollback.py --git 提交哈希 — Git 回退

使用 Git 将 canvas 目录恢复到指定 commit 的状态。需要先通过 git log --oneline 查找目标提交哈希。同样会自动创建安全备份。

python rollback.py --git a1b2c3d

[Git] 目标 commit: a1b2c3d
[Git] 仓库根目录: d:\网文剧本\bloodbound
[Git] 找到 commit: a1b2c3d Canvas Update | 07-05 14:30
[安全备份] 正在创建回滚前安全备份...
[安全备份] 完成: bak_safety_20260707_1510（42 个文件）
[Git] 已恢复到 commit a1b2c3d
[Git] 安全备份: bak_safety_20260707_1510

典型回滚操作全流程

以下是一次完整的回滚操作示例：

步	操作	说明
1	`python rollback.py`	查看可用备份列表，确认有可用的恢复点
2	`python rollback.py --dry-run --latest`	预览恢复内容，确认文件清单无误
3	`python rollback.py --latest`	执行恢复。脚本自动创建安全备份后覆盖 canvas
4	打开浏览器验证	确认恢复后的页面渲染正常、内容正确
5	`python backup.py`	创建新的常规备份，锁定恢复后的状态

安全备份命名规则：bak_safety_时间戳。恢复出错时，可从安全备份再次恢复。

4. 常见场景操作手册▶

AI写坏章节 · 回退到三天前 · 预览恢复 · 本地全毁 · 验证备份

场景速查

场景一：AI 写坏了一个章节

AI 生成了一段不满意的内容并覆盖了原文件。需要快速回退到上一次备份。

cd /d d:\网文剧本\bloodbound\canvas
python rollback.py --latest

脚本自动创建安全备份后，从最新常规备份恢复。如果恢复后仍不满意，可从安全备份再恢复。

场景二：想回退到三天前的版本

需要找到三天前的某个状态。先列出所有备份，找到对应日期的备份。

# 第一步：列出所有备份
python backup.py --list

# 第二步：找到目标日期的备份名称，例如 bak_20260704_1430
# 第三步：从该备份恢复
python rollback.py --backup bak_20260704_1430

备份按时间戳命名，日期直接体现在名称中（bak_YYYYMMDD_HHMM）。

场景三：不确定恢复内容，先预览

恢复前想确认会影响哪些文件，不做实际更改。

python rollback.py --dry-run --latest

预览模式列出所有将被恢复的文件，但不会修改任何内容。--dry-run 也可与 --backup 和 --git 组合。

场景四：本地文件全部损坏

极端情况：canvas 目录被清空或损坏。从 Git 仓库重新克隆后重建。

# 第一步：从 Git 克隆
git clone https://gitee.com/beijing-zangdai_0/the-book-of-blood-covenant.git

# 第二步：进入 canvas 目录
cd the-book-of-blood-covenant\canvas

# 第三步：如需从本地备份恢复（比 Git 更新）
python rollback.py --latest

Git 仓库保留的是最近一次推送的版本。本地备份可能比 Git 更新。两者结合使用。

场景五：验证备份是否完好

定期检查备份是否正常，确保有可用的恢复点。

# 验证最新备份
python backup.py --verify

# 查看所有备份状态
python backup.py --list

验证会检查备份目录是否包含文件，并列出顶层内容。建议在每次重要操作后执行。

5. 与部署流水线的关系▶

备份在构建链中的位置 · 部署流水线 · 安全网

构建链中的备份位置

备份是整个部署流水线的第一步，在任何构建和部署操作之前执行，确保有回退点。

backup.py ➔ build.js ➔ sync-to-nas.js ➔ deploy-preview ➔ deploy-production

步	操作	工具	说明
1	备份	`backup.py`	在任何修改之前执行，确保有回退点
2	构建	`build.js`	编译、打包、生成静态资源
3	同步	`sync-to-nas.js`	将构建产物同步到 NAS 存储
4	预览部署	`deploy-preview`	部署到预览环境进行验证
5	生产部署	`deploy-production`	推送到正式环境

回退机制

如果构建或部署过程中出现问题：

构建失败 → python rollback.py --latest 恢复到构建前状态
预览异常 → python rollback.py --dry-run --latest 先预览再恢复
部署出错 → python rollback.py --git 上一个commit 回退到上一个稳定版本

备份是安全网。每次 python backup.py 都会在流水线起点创建一个恢复锚点，确保任何环节出错都能回到已知的好状态。

6. 故障排除▶

中文路径编码 · 目录不存在 · 权限错误 · 备份过大

常见问题与解决方案

问题	原因	解决方案
中文路径编码问题	CMD 内联执行 `python -c` 时，中文路径可能被错误编码	使用 `python backup.py` 脚本文件方式执行，不要用 `-c` 内联代码。脚本内部使用 `pathlib` 和 `utf-8` 编码，可正确处理中文路径
备份目录不存在	`d:\网文剧本\bloodbound-backups\` 尚未创建	首次运行 `python backup.py` 时会自动创建该目录（`mkdir(parents=True, exist_ok=True)`），无需手动创建
权限错误	Python 进程对目标目录没有读写权限	确保 Python 对 `d:\网文剧本\bloodbound-backups\` 和 canvas 目录有完整读写权限。如果用管理员终端执行仍有问题，检查目录安全属性
备份过大 / 磁盘空间不足	备份累积过多，未及时清理	运行 `python backup.py --clean` 清理超出 20 个的旧备份。常规备份单次约 1.6 MB，20 个约 32 MB
安全备份创建失败	回滚前自动创建安全备份时出错（磁盘满/权限不足）	脚本会提示"是否仍要继续恢复？(y/N)"。输入 `y` 继续（不推荐），或先解决磁盘/权限问题后重试
Git commit 找不到	使用 `--git` 时指定的 commit 哈希不存在	先运行 `git log --oneline -20` 查看最近的提交记录，复制正确的短哈希值
恢复后文件数不匹配	恢复完成后当前文件数与备份文件数有差异	通常是正常现象 — `.git`、`node_modules` 等被忽略的目录中的文件不参与备份和恢复。差异在 5 个以内属于正常

快速诊断命令

# 检查 Python 是否可用
C:\Users\徐\.workbuddy\binaries\python\versions\3.13.12\python.exe --version

# 检查备份仓库状态
python backup.py --list

# 验证最新备份
python backup.py --verify

# 预览恢复（不做更改）
python rollback.py --dry-run --latest