04-开发-数据库快照在线备份与校验SOP
一、适用场景
HFMS 家庭管理系统承载健康 / 资产 / 财务 / 制度四类家庭数据，一旦误写或介质损坏必须可回退。
本技能固化「生成快照 → 异地镜像 → 三重校验 → 风险观察」这条已跑通的日常备份作业。
常态化为每日定时任务（本例：每日 03:00，工作目录 D:/家庭管理系统HFMS/程序源代码），服务无需停机。
同样适用于版本发布前、批量导入前、跨机迁移前的一次性手工快照。
二、操作步骤
- 先读落点，不猜路径：读
config.env的DB_PATH、BACKUP_DIR、BACKUP_KEEP、NAS_MIRROR_DIR，
确认快照该落哪、保留几份、异地在哪。（config.env解析器不剥行内注释 → 注释须独占一行。） - 生成快照（工作目录
程序源代码/）：
C:/Users/icece/.workbuddy/binaries/python/versions/3.13.12/python.exe backup.py backup
内部走 SQLite 在线备份 APIsrc_db.backup(dst_db)（backup.py:56），服务运行中可直跑。
产出BACKUP_DIR/<YYYYMMDD-HHMMSS>/：hfms.db+MANIFEST.json+SHA256SUMS。 - 异地镜像：
python tools/backup_mirror.py（tools/backup_mirror.py:39main）。
NAS_MIRROR_DIR为空或不可达 → 打印「异地镜像已跳过」并退出码 0，属正常，不算失败。 - 三重校验（缺一不算完成）：
① 步骤 2 输出含「快照已生成」；
②python backup.py list中该快照在列；
③python tools/_verify_snapshot_tmp.py <快照目录> [线上库]—— 比对SHA256SUMS，
并以只读方式打开快照库与线上库比对表数 / 总行数，输出VERDICT: PASS才算过。 - 只读体检查兜底面（可复用
scripts/backup_health.py，只读不写）：
检查BACKUP_DIR可写、快照存量与BACKUP_KEEP关系、是否存在异盘/异地兜底。 - 风险观察项只上报、不处置：发现如「异地目录消失、全部快照同盘」属配置层决策，
超出「只做备份」边界，写进记录交给用户拍板，不得自行删改迁移。 - 落记录：追加
.workbuddy/memory/<今日>.md与自动化记录（快照名、落点、校验结论、观察项）。
三、注意边界
- 只做备份：不动任何业务数据、不删任何文件、不重启服务。旧快照淘汰交给
BACKUP_KEEP+_prune()（backup.py:86）自动做。 - 只读打开快照库会在快照目录留下
hfms.db-shm/-wal（0 字节，无害），不必惊慌也不要顺手删。 - 沙箱/Agent 环境下禁止对线上库做写操作校验（
wal_checkpoint需写权限，必失败）；一律走副本或只读比对。 MANIFEST.json中docs_files=0/word_dirs=0不是故障：2026-10-15 已确认制度检索权威源＝WORD_LIB（客户数据源）Word 原件，
路径以绝对值存于documents.source_path，检索直读原件；DOCS_ROOT=制度文档/extracted是方案 B 之前的旧口径遗留。
真实缺口是制度 Word 原件本身不在快照覆盖范围内（另行决策，不属本流程）。- 同盘不叫备份：若
BACKUP_DIR与DB_PATH在同一物理盘，则无盘损隔离，须靠 NAS 或异地盘补位。
四、反例避雷
- ✗ 把「异地镜像已跳过」当失败回滚或重试 →
NAS_MIRROR_DIR为空是常态，脚本已优雅退出（退出码 0）。 - ✗ 只看
backup.py打印「快照已生成」就判成功 → 必须补 SHA256 与表数/行数比对，否则「生成了但坏着」照样记成功。 - ✗ 见
docs_files=0就去改DOCS_ROOT→ 2026-10-15 已定口径，属旧路径遗留；改配置不但无益还会误判制度检索故障。 - ✗ 用通配符批量清理旧快照 → 曾有 glob 误删 92 份家庭档案的教训；淘汰只能走
BACKUP_KEEP自动_prune，删除必须精确路径逐条。 - ✗ 校验时以可写方式打开快照库 → 会污染快照本身；只读或先
copy2到.workbuddy再验。 - ✗ 备份脚本报失败就重启服务「抢救」 → 备份是只读旁路操作，重启属越界，且会打断在线业务。
五、代码锚点 / 实战战绩
锚点
- 程序源代码/backup.py：:48 cmd_backup、:56 src_db.backup(dst_db)（在线备份核心）、:86 _prune、:132 cmd_list、:152 cmd_verify、:176 cmd_restore
- 程序源代码/tools/backup_mirror.py：:39 main、:43 跳过分支、:32 _snaps、:24 _sha
- 程序源代码/tools/_verify_snapshot_tmp.py：:8 SNAP/LIVE 取 argv、:18 sha256、:54 stats
- 程序源代码/config.env：DB_PATH / BACKUP_DIR / BACKUP_KEEP / NAS_MIRROR_DIR / DOCS_ROOT
- 程序源代码/hfms-backups/<快照名>/：MANIFEST.json（time / db / docs_files / word_lib / role）
战绩
- 2026-10-12 首次执行起连续 5 次成功（10-12 / 10-13 / 10-14 / 10-15 / 10-16），每次均 SHA256SUMS ALL OK + 表行比对 PASS。
- 2026-10-16 第 5 次：快照 20261016-030111，24.2MB，98 表 / 5833 行（时点值，非稳定基线，见「基线口径订正」节）与线上库完全一致；NAS 镜像按惯例跳过。
- 落点演进：2026-10-13 由 E:/HFMS备份 迁回源码树内 程序源代码/hfms-backups/（用户指令），E 盘存量转作异盘兜底。
- 2026-10-16 校验时发现风险并只上报未处置：E:/HFMS备份 已不存在（E 盘仍在）→ 异盘兜底失效，4 份快照全在 D 盘同盘。
基线口径订正（2026-10-25）
撤回说明：本包此前把「98 表 / 5833 行」当作稳定校验基线使用。2026-10-25 第 14 次定时快照
实测总行数 5770（−63），该数值基线已被证伪。总行数属数值基线，随时点漂移（易变表自然增减），
不可与历史数字硬比。
订正过程
1. 快照 20261025-093828：SHA256 3ff60ab5ba3b… ALL OK，只读开库比对 98 表 / 5770 行，与线上库一致。
2. 与上一份快照做表级 diff → 差异全部落在易变表：sessions 67→2(-65)、page_cache 8→4(-4)、
audit_log +3、ledger_hl +1、hl_archive_index +1、settings +1。
3. 业务台账表只增不减 → 定性「非数据丢失」，VERDICT PASS。
正确口径（取代本包旧表述）
- 表数属结构基线，可硬比（基准 98）；行数属数值基线，不可硬比。
- 行数校验一律做「与上一份快照的表级 diff」，易变表 sessions / page_cache / audit_log / settings
及归档类（*_archive_index）豁免。
- SHA256 ALL OK 只证明文件完整，不证明内容没少，之后仍须走表级 diff。
影响面（四类穷举）
- 代码/配置：无改动（校验脚本 tools/_verify_snapshot_tmp.py 本就输出表级 diff，是判读口径错了）。
- 文档手册：本包正文与正例中所有「5833 行」已标注为「时点值，非稳定基线」。
- 技能包：同批订正 04-开发-数据库快照在线备份与校验SOP、04-开发-每日定时备份自动化执行与判成败SOP、
04-开发-同批重复产物识别与逐份独立校验法、06-成品-跨机数据迁移先校验后写入SOP 四包。
- 记忆与自动化：MEMORY.md 八已改口径；每日备份自动化记录按新口径书写。
权威出处：05-测试-历史基线数值失效与表级差分校验法（本批新建，口径的单一出处）。
六、关联笔记
- 与
04-开发-备份保留策略收紧与统一淘汰法互补：那条管保留份数与淘汰口径，本条管生成与校验，合起来才是完整备份闭环。 - 与
04-开发-沙箱环境写文件限制规避法配套：DB 校验一律走副本 / 只读，先写.workbuddy再cp。 - 与
06-成品-跨机数据迁移先校验后写入SOP同源：先校验后动作，不校验不落地。 - 与
00-总纲-隐私红线规则配套：快照含家庭全量数据，只落本机/内网，不得上传云端或交公有模型。 - 自动化：
HFMS 每日数据库快照备份（每日 03:00，工作目录D:/家庭管理系统HFMS/程序源代码）。
七、版本记录
-
v1.0（2026-10-16）：首版。固化在线快照三步作业 + 三重校验口径 +
docs_files=0正确解读 + 同盘无隔离风险识别 + 只上报不处置边界；
附scripts/backup_health.py只读体检查器。 -
（2026-10-25 订正）撤回「5833 行」稳定基线表述，改以表级 diff + 易变表豁免为准；
订正过程与影响面见「基线口径订正（2026-10-25）」节。
