备份与恢复工具指南

项目	路径 / 值	说明
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。

命令	功能	输出
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 个备份

命令	功能	安全机制
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_时间戳。恢复出错时，可从安全备份再次恢复。

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

步	操作	工具	说明
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 都会在流水线起点创建一个恢复锚点，确保任何环节出错都能回到已知的好状态。

问题	原因	解决方案
中文路径编码问题	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