用途与实际影响
这项功能怎样使用
为什么需要它
新电脑从零安装和带回旧历史是两件事。只复制项目文件夹会混进旧机器的运行状态；真正恢复须先验历史备份，再确认数据库、浏览器大盘和自动记录重新连上。
举个实际例子
我说“把旧电脑上的 TimeAudit 连历史一起搬到新机”。恢复完成后，我应该能在浏览器里打开原来的大盘、查到备份里的旧时间线，同时看到新电脑的记录继续往前走；若备份之后到故障之前有一段拿不回来，它会单独列出，而不是承诺历史零丢失。
最后我会得到什么
恢复后应能在浏览器大盘看到备份里的旧时间线，也看见新电脑继续产生记录。若只装好了程序、旧备份读不出或故障前最后一段没备到，会逐项列出，不承诺零丢失。
正常时
所选备份、运行环境、旧历史和新采集都逐层读回时，才说明对应部分恢复。
发现问题时
数据库备份读不出、大盘打不开或新记录不前进时停在那一层并保留旧备份。
入口不可用或证据不足时
备份盘、数据库或登录条件缺失时只建立可安全准备的部分，明确旧历史目前无法找回。
从哪里开始
在已接入 TimeAudit 的 AI 对话中明确说全新安装或带历史换机，并给出可靠备份；Grafana 页面只负责查看结果。
需要准备什么
- 新旧机器与目标时间线
- 最后可靠数据库和 Grafana 备份
- 可用软件与凭据
从开始到拿到结果
- 1
核对最后真正可读的备份
系统确认历史数据库备份和大盘配置分别存在且能读取，并列出备份之后可能丢失的时段。
- 2
建立并导入
安装所需运行环境，空库建表或将已验 dump 恢复到干净库，再恢复大盘。
- 3
逐层验收
核对采集心跳、真实入库和浏览器中的旧新记录；缺备份或大盘打不开就指出停点，不说零丢失。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
8 月 31 日基线记录每日备份结果 0、备份/恢复定向测试通过；本次未刷新任务结果或从最新 dump 做隔离整库恢复关键规则与设计选择
全新安装、带历史换机、灾后 / 重装 / 硬盘更换先选场景，不把三套动作混成一张清单。
取得现行项目源码后运行 `setup_runtime.ps1` 重建 `.venv`；不复制旧 `.venv`、整个项目运行树或未干净关闭的数据卷。
先建立 WSL2、Docker Desktop、项目 `.venv` 与 PostgreSQL / ingester / Grafana 三容器。
全新空库执行 `schema.sql`；带历史换机或灾后恢复使用校验过的 dump restore。两条只选一条，避免先建再清或把空库当历史。
数据库 dump 优先于运行中 `postgres_data` 目录复制；Grafana 先确认固定 PostgreSQL datasource，再恢复 dashboard JSON 或完整状态。
恢复 `TimeAudit_AutoStart`、每分钟 `TimeAudit_Watchdog` 与 `TimeAudit_DailyBackup` 后，依次验 heartbeat、真实入库、有界聚合和浏览器大盘。
二进制库保存完整 Grafana 状态，JSON 提供版本化 dashboard 恢复；只接受精确 `.json`，不导入 `.json.bak`。
任务结果 0、备份存在和源码测试都不替代最新 dump 的隔离整库恢复；历史缺口必须按最后备份时间保留。
本模块用到的名词
- dump（逻辑备份）
- 由 PostgreSQL 生成、可校验恢复的文件。
- fresh install（全新安装）
- 没有历史库的场景；在三容器就绪后用 `schema.sql` 创建空表结构。
- history restore（历史恢复）
- 换机或灾后把校验过的 dump 恢复到干净目标库；dump 自带结构，不与空库建表步骤叠加。
- runtime rebuild（运行环境重建）
- 从现行源码和 requirements 运行 `setup_runtime.ps1` 创建项目 `.venv`，不复制旧机器的虚拟环境。
- acceptance chain（验收链）
- 从任务、heartbeat、真实入库、聚合摘要到浏览器大盘逐层回读；上一层成功不替代下一层。
- consistent snapshot（一致快照）
- 同一事务视图读取 Grafana SQLite。
- dry-run（预检）
- 只发现和验证，不修改运行实例。
专业定义
把全新安装、带历史换机、系统重装 / 硬盘更换三种场景拆开：先重建 WSL（Windows 的 Linux 子系统）、Docker、项目 .venv 和三容器，再在空库建表或 dump 恢复中二选一，接回 Grafana、三项计划任务并做真实数据链验收。
解决什么
解决全新安装与历史恢复混用、复制旧运行树、`.venv` 跨机器漂移、空库建表与 dump restore 重复、Grafana 数据源失配、计划任务漏装、长期膨胀、备份夹带、Git 分叉和未经真实数据链验收的恢复自信。
当前怎样实现
- setup_runtime.ps1 从固定 Python 3.11 基座创建项目 `.venv`、安装 requirements 并运行 pip check；启动器和 Watchdog 使用其中的 pythonw。
- docker-compose.yml 拉起 PostgreSQL 15、audit-ingester 和 Grafana 13.0.2；schema（数据结构）/main 管周/月分区、预热和 1200 天默认保留。
- backup_db 用 pg_dump；backup_grafana 用一致快照导出 JSON。
- restore_grafana 只接受合同通过的 JSON，并支持 dry-run。
- PCConfig 重建 AutoStart 与每分钟 Watchdog；DailyBackup 每天 20:40 组合备份并轮转 14 份。
- README 记录当前 `.venv`、每 1 分钟 Watchdog 与运行链；`快速部署.md` 的整树复制、零丢失和每 5 分钟说法是待 Owner 修订的旧说明。
- timeaudit_backup.py restore-check使用已安装固定镜像、无网络/无公开端口、只读归档挂载与独立数据库，绝不导入audit-postgres。原容器完成记录可跨客户端断线保留；restore-status查看同次进度，finish-restore核对退出码、可读表、所有权标签后记录结果并清理本次容器/匿名卷。running/starting不算PASS，未知资源不盲重建或删除。
- backup_db.ps1以合格Python导出到唯一.partial，flush后确认PostgreSQL custom格式、列归档并算SHA-256，再发布.dump及原子.dump.json。至少保留3份完整已验证配对，失败不替换成功档案，无法证明可清理的旧原件保留。健康检查只看清单形状、长度与新鲜度，不重哈希全部载荷。
执行流程
- 1
先选场景：全新安装没有历史、换机需要带历史，或灾后 / 重装 / 硬盘更换从备份恢复；记录最后可靠备份与预期历史缺口。
- 2
安装或确认 WSL2 与 Docker Desktop，取得现行项目源码，运行 `pwsh -File .\setup_runtime.ps1` 重建项目 `.venv`。
- 3
准备凭据后以 compose 拉起 PostgreSQL、audit-ingester、Grafana 三容器，并确认容器身份与 health。
- 4
数据库二选一：全新空库执行 `schema.sql`；带历史或灾后候选先校验 dump，再恢复到干净目标库，不额外走空库建表路线。
- 5
确认 Grafana 固定 PostgreSQL datasource，再用合同通过的 JSON 或完整 Grafana 备份恢复 dashboard，并在浏览器打开 `http://localhost:43000`。
- 6
重建并回读 `TimeAudit_AutoStart`、`TimeAudit_Watchdog`、`TimeAudit_DailyBackup`，再手动触发一次受控启动或备份检查。
- 7
按三条 heartbeat 推进、真实入库、`timeaudit_diagnostic_summary.py` 聚合覆盖、浏览器六张大盘可读的顺序验收。
- 8
最后列出备份后到故障时刻的历史缺口、不可恢复项和未执行的演练；本轮仍未从最新 dump 做隔离整库恢复。
边界
- 数据库和二进制备份不进入 PUBLIC（公开） Git。
- Git JSON 不等于完整数据库或用户状态。
- `快速部署.md` 当前“复制整个项目树”“历史零丢失”和 Watchdog 每 5 分钟属于已识别漂移；现行事实以 README、setup_runtime.ps1 与每分钟 Watchdog 定义为准。
- 恢复最多到最后一份可靠备份；故障前尚未备份的区间必须列为历史缺口。
- 无恢复回读不能称灾难恢复完成，本轮也没有把定向测试或任务结果 0 冒充最新 dump 的隔离整库恢复。
失败与恢复
- 全新安装误走 dump 恢复或历史恢复先建空表
- 停止并重新确认场景；在 `schema.sql` 建表与 dump restore 中只选正确的一条。
- 旧文档要求复制整个项目树或旧 `.venv`
- 只迁移现行源码与经选择的备份，在目标机运行 `setup_runtime.ps1` 重建环境；运行卷不作为默认迁移手段。
- JSON 有人工脏改
- 失败关闭，不覆盖或夹带。
- 退役 UID / matcher 缺失
- 合同失败，不能恢复。
- 任务显示成功但 heartbeat、入库或大盘不通
- 只把任务层标为通过，继续定位受影响层；不宣布系统恢复。
- 远端领先或分叉
- 不 push、不 force-push，保留本地备份。
真实入口
E:\Projects\Tools\TimeAudit\schema.sql表、分区与索引
E:\Projects\Tools\TimeAudit\docker-compose.yml数据库、ingester 与 Grafana
E:\Projects\Tools\TimeAudit\setup_runtime.ps1项目 .venv 创建、依赖安装和冲突检查
E:\Projects\Tools\TimeAudit\README.md现行每分钟 Watchdog、.venv 与运行验收事实
E:\Projects\Tools\TimeAudit\backup_all.ps1组合备份
E:\Projects\Tools\TimeAudit\backup_db.ps1数据库 dump
E:\Projects\Tools\TimeAudit\backup_grafana.pyGrafana 导出与同步
E:\Projects\Tools\TimeAudit\restore_grafana.py验证与恢复
E:\Projects\Tools\TimeAudit\快速部署.md三场景旧入口；含已识别的整树复制、零丢失与五分钟 Watchdog 漂移
E:\Projects\Tools\TimeAudit\test_backup_all_script.py备份回归
E:\Projects\Tools\TimeAudit\test_restore_grafana.py恢复回归
E:\Projects\Tools\TimeAudit\test_sql_partition_explain.py分区查询审计
E:\Projects\Tools\TimeAudit\DIAGNOSTICS_OPERATIONS.md质量来源、活动持久化、共享健康、数据库备份与独立恢复的当前合同
如何验证
- 8月31日回读的DailyBackup结果为0，本批未刷新该项。
- 备份、恢复与大盘合同纳入定向测试并通过。
- README 与 setup_runtime.ps1 当前证明运行环境应在目标机重建、Watchdog 为每分钟检查；它们不证明某次换机已经完成。
- 未从最新 dump 做隔离 pg_restore，也未完整走三场景任一真实换机旅程，恢复 E2E（端到端验证） 仍缺。
与其他模块的关系
先重建采集模块的运行与存储底座，再恢复硬件、进程、时间和可视化所需历史；可靠性模块接回 AutoStart / Watchdog，最终由 heartbeat、入库、聚合和浏览器大盘共同验收。