安全与备份架构
一 · 核心理念
「保存」= Git 上传
在 Bloodbound 项目中，「保存」就是 Git 上传。不存在单独的「保存按钮」， 每一次点击「Git 上传」按钮，都会经过三层安全机制，确保代码和内容不会丢失。
为什么以 Git 为中心？
- 可追溯 每次上传都有提交记录，知道谁在什么时候改了什么
- 可回滚 任何时候都可以回到之前的任意版本
- 可协作 多人同时工作不冲突，各自提交自动合并
- 异地容灾 远程 Gitee 仓库 + 本地自动备份 = 双保险
三层安全防护
🟣 第一层 · 本地自动备份
时机：每次 Git push 之前自动触发，无论 push 成功与否
内容：完整项目快照（canvas、screenplay、content、references、根配置文件）
位置：
特点：独立于 Git，即使 Git 仓库损坏，备份也不受影响
内容：完整项目快照（canvas、screenplay、content、references、根配置文件）
位置：
archive/backups/auto/ · 保留最近 20 个特点：独立于 Git，即使 Git 仓库损坏，备份也不受影响
🔵 第二层 · Git 本地仓库
时机：commit 后，文件变更记录在 .git 目录中
内容：所有代码和文档的变更历史
特点：支持任意版本回滚、分支、对比差异
位置：
内容：所有代码和文档的变更历史
特点：支持任意版本回滚、分支、对比差异
位置：
.git/ · 项目根目录下
🟢 第三层 · Gitee 远程仓库
时机：push 成功后，代码同步到云端
内容：与本地仓库完全一致
特点：异地容灾，多设备同步，团队协作
内容：与本地仓库完全一致
特点：异地容灾，多设备同步，团队协作
理念总结
本地备份保底 → Git 记录历史 → 远程仓库容灾。
这不是三个独立的工具。而是一个以 Git 为纽带串联的完整保存链条。
二 · 六步安全上传流程
每次点击「Git 上传」按钮，后端自动执行以下六步。每一步都有独立的成功/失败状态和耗时记录。
流程图
┌─ ① 本地备份 ──────────────────────────────────────────┐
│ backup.create_backup() │
│ → archive/backups/auto/push-YYYYMMDD_HHMMSS/ │
│ → 备份 canvas/screenplay/content/references + 根文件 │
│ → 写入 manifest.json（文件清单 + git 状态） │
│ → 轮转旧备份（保留最近 20 个） │
└────────────────────────────────────────────────────────┘
│ 耗时：~1-3s（取决于文件数量）
▼
┌─ ② 文档日志 ──────────────────────────────────────────┐
│ 自动追加会话记录到 canvas/session-log.json │
│ → 有摘要时写入内容，无摘要时自动生成 Git 自动上传记录 │
│ → 插入数组头部，记录时间+来源+模型+内容 │
└────────────────────────────────────────────────────────┘
│ 耗时：< 100ms
▼
┌─ ③ git add -A ───────────────────────────────────────┐
│ 暂存所有变更文件 │
│ → CRLF 行尾警告自动过滤 │
│ → 超时 30s，超时后自动清理 index.lock │
└────────────────────────────────────────────────────────┘
│ 耗时：~1s
▼
┌─ ④ git commit ───────────────────────────────────────┐
│ 提交变更，生成历史记录 │
│ → 提交信息：自动备份 YYYY-MM-DD HH:MM │
│ → 无变更时自动跳过 │
│ → 超时 120s，超时后自动清理 index.lock │
└────────────────────────────────────────────────────────┘
│ 耗时：~2s（无 hook 时）
▼
┌─ ⑤ git push origin master ───────────────────────────┐
│ 推送到 Gitee 远程仓库 │
│ → 首次推送自动设置 upstream │
│ → 无变更时跳过 │
│ → 超时 120s │
└────────────────────────────────────────────────────────┘
│ 耗时：~3-15s（取决于网络）
▼
┌─ ⑥ 远程同步提醒 ─────────────────────────────────────┐
│ 推送成功后自动检查是否有其他服务器需要同步 │
│ → 返回需同步的服务器列表 + git pull 命令 │
│ → 前端展示提醒行（青色高亮），告知用户手动同步 │
│ → 已知服务器：192.168.1.98:8080（NAS 192.168.1.3 备用）│
│ → 无变更或失败时自动跳过 │
└────────────────────────────────────────────────────────┘
│ 耗时：< 1ms（前端展示）
▼
✓ 六步全部完成 · 总计耗时约 10-30 秒
每一步的状态显示
前端模态框实时显示六步状态：
| 步骤 | 图标 | 状态 | 说明 |
|---|---|---|---|
| 本地备份 | ◉ | 运行中 | 正在复制文件到备份目录 |
| 本地备份 | ✓ | 完成 | 234 文件 (12.5 MB) · push-20260703_091200 |
| 文档日志 | ✓ | 完成 | 自动记录 · 累计 36 次 |
| git add | ✓ | 完成 | ok (234ms) |
| git commit | ✓ | 完成 | [master abc1234] 自动备份 2026-07-03 09:12 (456ms) |
| git push | ✓ | 完成 | master -> master (2341ms) |
| git push | ✗ | 失败 | rejected: non-fast-forward · 参见故障处理 |
| 远程同步提醒 | ℹ | 提醒 | 需手动同步: 192.168.1.3:8080 (NAS备用) · git pull origin master |
| 远程同步提醒 | ✓ | 无需 | 无其他服务器需同步 |
三 · 现有保存方案整合
以下是 Bloodbound 项目中所有与「保存」相关的机制，它们都被整合在以 Git 为中心的架构中：
本地备份 backup.py
独立 Python 脚本，可命令行手动调用。Git push 前自动触发。
备份范围：canvas/screenplay/content/references + 根文件
保留策略：最近 20 个自动轮转
备份范围：canvas/screenplay/content/references + 根文件
保留策略：最近 20 个自动轮转
命令：
python scripts/backup.py · --list 查看Git 上传 server.py + 前端
六步安全流程的后端引擎。前端一键触发，后端依次执行备份→日志→add→commit→push，并返回同步提醒。
每个步骤独立计时、独立报错、独立可重试。
每个步骤独立计时、独立报错、独立可重试。
接口：
POST /api/git/push会话日志 session-log.json
记录每次 AI 会话的日期、时间、来源、模型、工作内容。
上传时自动追加一条记录。首页「积分消耗」卡片统计消耗总量。
上传时自动追加一条记录。首页「积分消耗」卡片统计消耗总量。
位置：
canvas/session-log.json规范文档 上传规范 + 架构
Git 上传操作说明（upload-spec.html）+ 本安全架构文档（safety-backup-arch.html）。
覆盖完整流程、错误速查、回滚步骤。
覆盖完整流程、错误速查、回滚步骤。
upload-spec.html · 本文档
整合关系
用户点击「Git 上传」
│
▼
[ backup.py ] ──── 创建本地副本 → archive/backups/auto/
│
▼
[ session-log.json ] ──── 追加会话记录
│
▼
[ git add → commit → push ] ──── 推送到 Gitee
│
▼
[ 前端展示 ] ──── 六步结果 + 同步提醒 + 耗时统计 + 详细输出
四 · 故障恢复方案
故障矩阵
| 故障类型 | 影响 | 恢复方案 |
|---|---|---|
| 备份失败 | 缺少本地安全网，但不影响后续步骤 | 手动运行 python scripts/backup.py |
| 日志写入失败 | 仅影响会话历史记录，不影响代码保存 | 不影响，可忽略。下次上传会重新尝试 |
| git add 失败 | 文件未暂存，后续步骤无法进行（但备份已完成） | 检查 .git/index.lock，删除后重试 |
| git commit 失败 | 变更未提交，但备份已完成 | 检查 pre-commit 钩子，手动提交或跳过钩子 |
| git push 失败 | 远程未同步，但本地备份+commit 都已完成 | 检查网络/Gitee 状态，pull 后重推 |
| 服务未启动 | 完全无法上传 | 双击 scripts/server/启动服务器.bat |
关键原则
- 备份优先 备份是第一步，即使后续所有步骤失败，备份也已存在。这是最底线的安全保障。
- 独立失败 每一步独立报错。备份失败不影响 add，add 失败不影响之前的备份。
- 可恢复 任何一步失败都可以单独重试。重试会重新走完整流程（包括创建新备份）。
紧急回滚
# 场景：push 后发现严重错误，需要回退
# 方案 A：从本地备份恢复（最安全）
cp -r archive/backups/auto/push-YYYYMMDD_HHMMSS/canvas/* canvas/
# 然后用 Git 上传按钮重新推送
# 方案 B：Git 回滚（保留历史）
git revert HEAD # 创建一个反向提交来撤销
git push origin master
# 方案 C：Git 硬回滚（丢弃历史，慎用）
git reset --hard HEAD~1 # 回退到上一版本
git push --force origin master # 强制覆盖远程
五 · 架构文件索引
核心 safety-backup-arch.html
本文档。安全与备份的核心架构说明。以 Git 为中心的三层防护 + 六步上传流程。
操作 upload-spec.html
Git 上传操作规范。一键上传说明、常见错误速查、回滚步骤、安全注意事项。
规范 version-control-spec.html
版本管理规范。commit 规范、分支策略、session-log.json 格式定义。
代码 backup.py
本地备份系统源码。
scripts/backup.py · 支持命令行和 API 调用。代码 server.py
HTTP 服务器，包含六步上传的后端逻辑。
scripts/server/server.py。数据 session-log.json
AI 会话日志。每次上传自动追加记录。
canvas/session-log.json。