feat: SQLite 定期备份内置进二进制

SQLite 是单文件、没有外部主从，坏一份就是全丢，而 data/ 一直被 gitignore、此前没有任何备份。备份做进二进制，不依赖外部 cron / systemd timer。 - 快照用 VACUUM INTO，不用 cp 主库：服务边跑边写时 cp 可能拷到写了一半的页 - 启动时补一次，之后每小时醒一次看是否到期；默认间隔 24h、保留最近 7 份 - 产出自检 SQLite 文件头，不合格即删并报错，不留「看着像备份的废物」 - 新增 -backup 子命令，供升级 / 迁移 / 交付前手工备一份 - 落 data/backups/ —— systemd 单元是 ProtectSystem=strict，只放开了 data/ 可写 - 边界写进文档：只防误删 / 误改 / 写坏，不防整盘损坏，跨机保存仍需人工配套： - deploy/DELIVERY.md 新增第 7 节「数据备份与恢复」+ 红线条目 - clonezilla-cleanup.sh 提示克隆前清空 data/backups/，避免原型机测试数据被带走 - deploy/eaisalestrain.env 补 4 个备份环境变量 - PROJECT_STATE.md 记 D24 另：清理 worker_task 中 17 条没聊过天的历史空任务（id 1-11、13-18），删前先备份、清单经确认，删除程序带「命中数与白名单不一致即中止」保险。该项为一次性数据操作，不产生代码改动。 Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-09-14 16:33:05 +08:00
parent f197dbd206
commit 20df2ff06e
8 changed files with 561 additions and 0 deletions
@@ -29,6 +29,7 @@
 ├── .env                     # JWT 密钥等（交付前生成，勿提交源码库）
 ├── data/
 │   ├── eai_agentplatform.db     # SQLite（首启自动建）
+│   ├── backups/             # 定期备份（服务自动维护，见第 7 节）
 │   └── kb_data/             # 素材 + 提取缓存
 ├── knowledge_source/        # 知识源 Markdown
 └── (前端静态资源由 Nginx 托管，见 ../docs/deploy.md)
@@ -131,3 +132,47 @@ SQL
 - [ ] 管理员密码非 `admin123`
 - [ ] `.bash_history` 已清空、无 `.git`
 - [ ] 测试账号（zhangsan 等）、演示素材、演示考试记录已删除
+- [ ] `data/backups/` 里没有**原型机自己的**数据备份（见第 7 节末）
+
+---
+
+## 7. 数据备份与恢复
+
+SQLite 是单文件、没有主从副本，文件坏一份就是全丢，所以服务自带定期备份，默认开着。
+
+**怎么跑**：进程启动时先检查一次（距上次备份够久就补一份），之后每小时醒一次看是否到期。
+不需要外部 cron / systemd timer，备份逻辑在二进制里。间隔和保留份数由 `.env` 控制：
+
+```
+BACKUP_ENABLED=true          # 关掉就完全不备
+BACKUP_DIR=data/backups      # 必须在 data/ 下（ProtectSystem=strict 只放开这里）
+BACKUP_KEEP=7                # 保留最近几份，更旧的自动删
+BACKUP_INTERVAL_HOURS=24     # 间隔
+```
+
+**备份文件长这样**：`data/backups/eai_agentplatform-20260914-162401.db`。
+用 `VACUUM INTO` 产出，不是 `cp` 主库 —— 服务边跑边写时 `cp` 可能拷到写了一半的页；
+`VACUUM INTO` 出来的是已压实、内部一致的完整副本，且不用停服。产出的文件会校验 SQLite 文件头，
+不是真库就删掉并报错，不会留下「看着像备份的废物」。
+
+**手工备一份**（升级、迁移、动数据之前留个手边的副本）：
+
+```bash
+sudo -u eai_agentplatform /opt/eai_agentplatform/eai_agentplatform-server -backup
+```
+
+**恢复**（会覆盖当前数据，先停服）：
+
+```bash
+sudo systemctl stop eai_agentplatform
+sudo -u eai_agentplatform cp data/backups/eai_agentplatform-20260914-162401.db data/eai_agentplatform.db
+sudo systemctl start eai_agentplatform
+```
+
+> 备份只在**本机 data/ 目录**里，防的是误删/误改/写坏，防不了整盘损坏。
+> 要防整盘，得把 `data/backups/` 定期拷到机器之外（U 盘 / 内网文件服务器）。
+
+**克隆前注意**：原型机的 `data/backups/` 里会有原型机自己的历史数据（测试账号、演示素材），
+整盘克隆会原样带到客户机器上。清理时一并删掉该目录内容，让客户机器从干净状态开始。
+
+恢复之后想核对内容，直接看文件时间戳和大小即可 —— 文件名里的时间就是备份时刻。
@@ -43,6 +43,8 @@ done
 step "3. 清理测试/演示数据（保留生产库结构，清空内容）"
 echo "  - 提示：测试用户 zhangsan / 演示素材 / 演示考试记录等由管理员在 Web 界面手动清理，"
 echo "    或在克隆前用 sqlite3 执行（见 DELIVERY.md 第 4 节）。脚本不自动清库，避免误删正式数据。"
+echo "  - 别漏了 $APP_DIR/data/backups/ ：里面是原型机自己的历史快照，含同一批测试数据，"
+echo "    整盘克隆会一起带到客户机器上。确认无用后手工清空该目录（见 DELIVERY.md 第 7 节）。"

 step "4. 清空日志与 shell 历史"
 for f in "$APP_DIR/logs" "$APP_DIR"/*.log /var/log/eai_agentplatform*.log; do
@@ -21,6 +21,13 @@ EMBED_MODEL=bge-m3
 KB_DATA_DIR=data/kb_data
 KNOWLEDGE_SOURCE_DIR=/opt/eai_agentplatform/knowledge_source

+# 定期备份（默认开：启动时补一次，之后每 BACKUP_INTERVAL_HOURS 小时检查一次，保留最近 BACKUP_KEEP 份）
+# 备份目录必须留在 data/ 下 —— systemd 单元是 ProtectSystem=strict，只放开了 data/ 可写
+BACKUP_ENABLED=true
+BACKUP_DIR=data/backups
+BACKUP_KEEP=7
+BACKUP_INTERVAL_HOURS=24
+
 # 上传大小限制（字节）
 FILE_MAX_SIZE_DOC=209715200
 FILE_MAX_SIZE_VIDEO=2147483648