# 数据生命周期与恢复说明

v0.6 发售的 SQL 库拥有库存、资格、固定凭证、请求键、outbox/inbox、签名任务、隔离消息、会话及链游标；均不是可随意重建的缓存。RabbitMQ 已确认接收不等于业务已完成，备份须核对 SQL 与 broker 的未确认消息。发售和二级交易各用独立 dataset/数据库/队列，Redis 可重建。当前没有发售整体备份恢复 CLI，不能用模拟 exchangectl 操作发售库。见[发售架构](../02-architecture/flash-sale-design.md)和[验收](../04-testing/sale-acceptance.md)。

> 当前基线：模拟 v0.3 保留，独立链模式升级为 v0.5。新增完整历史查询、任务版本保护、已确认事件索引、只读对账和基础告警，见 [设计](../07-history/v0.5-design.md)、[执行报告](../reports/2026-10-12-v0.5.md)。历史报告与证据保留原版本。

> 历史 v0.4 记录：chain-journal.db 保存命令/版本/域/扫描锚点，chain-views.db 为投影/outbox，PG 或独立 chain-tasks.db 是 raw 交易/nonce 权威，不能当投影删除。当时备份须停应用协调链库、任务和 Kafka 消费水位，见 [v0.4 报告](../reports/2026-10-12-v0.4.md)。当前 v0.6 已改用 RabbitMQ，恢复规则见[链部署](web3-deployment.md)；换任务库或重建 Anvil 必须检查域与 dataset，不能拿模拟 exchangectl 维护链库。


更新：2026-10-11。面向当前单机模拟交易系统的维护与审阅。具体命令见[部署手册](deployment.md)，代码见 [store.go](../../backend/store.go)、[runtime.go](../../backend/runtime.go)、[maintenance.go](../../backend/maintenance.go) 与 [exchangectl](../../cmd/exchangectl/main.go)。

## 1. 数据归属

| 数据 | 权威性与增长 | 维护规则 |
| --- | --- | --- |
| journal.db：metadata/commands | 权威业务输入；engine_version=1、dataset_id；日志只增 | 不删除/手改；checkpoint 只处理 SQLite WAL，不删 commands |
| auth.db：users/sessions/auth_audit | 权威身份、密码摘要、会话/CSRF、访问审计 | 必须和业务数据同一停机点备份；不能由撮合日志重建 |
| views.db：订单/余额/价档/成交/分录/结果/资金审计/进度 | 派生查询模型，包含每次 envelope | 可从 journal 重建；业务表与进度整批原子提交 |
| Engine 内存：树/FIFO/订单/账户/去重 | 在线业务裁定状态，启动由日志恢复 | 不由 HTTP 读取；进程重启后重新构造 |
| 浏览器 sessionStorage | 标签页待确认原请求，非服务端权威 | 保存原键/内容，不存凭证；关闭标签或清存储无恢复保证 |
| exchange.lock | 本机进程锁协调文件 | 是否存在不代表锁是否被持有；不能靠删锁文件解锁 |

每库默认最多一条连接，SQL 都在外围；投影查询会与投影事务争用连接。金额为 TEXT/decimal，不用 SQL REAL 结算。市场规则是引擎版本绑定的编译期常量，并非可热改配置表。

FULL 保证提交屏障，但其断电效果依赖文件系统与存储正确实现同步；不保证磁盘损坏/云卷丢失。应用命令日志与 SQLite `-wal/-shm` 是不同层次，不能把清 WAL 当作删业务历史。

## 2. 从受理到可见

Submit 在外围计算业务摘要、schema 和接收时间；唯一 journal 写者按队列顺序赋 seq，在 FULL 事务写 commands。只有 Commit 成功才发送 durable。核心逐条 Apply，包含拒绝与同键确认也消费一个位置。

核心返回脱离原件的订单/余额/分录副本，首次去重记忆再持有独立 Order。projector 用 copyResult 分离 HTTP 响应与尚未提交投影的数据，然后回包；整批投影提交业务表/results/progress 后归还在途额度。成功回包不等于查询已追上，min_seq 读自己的写最多等待 2s。

results 保存每条 envelope 的结论；按键查询返回首次已投影结论，单笔订单查询返回最新投影状态。两者时间含义不同。资金审计含拒绝/重复状态，重复确认推进水位而不再增发资金。

## 3. 启动与重放

先取得目录 flock，打开数据库、迁移、检查元数据/完整性，再从日志头恢复核心。每条命令检查格式版本、存储 seq 与 payload seq、存在的摘要、连续性；缺摘要旧日志在外围补算。schema=0 兼容旧格式，schema=1 为当前格式，未知格式拒绝。

即使 views 已经追平，全部命令仍逐条 Apply 来恢复内存账户/活动簿/去重；仅跳过正常已投影前缀的重复 SQL。缺失后缀按恢复批 64 条补齐，旧资金审计迁移可补写前缀审计；恢复批大小不随运行批配置变化。投影超前/日志缺口/不兼容引擎版本拒绝启动，完成后才开放 HTTP。

目前没有持久化核心快照、日志截断、幂等 TTL 或终态淘汰。命令、投影、保留订单、去重和恢复成本随历史增长；活动订单预算不等于历史内存上限。快照/分区属于 P8，需要独立设计与验证。

## 4. 离线检查与备份

1. 停唯一服务实例，确认它退出，使用同版 exchangectl 取得同一目录锁。
2. `check` 重放并补齐正常落后投影，再在临时库独立重放，比较固定派生表的有序逐行 JSON 摘要。
3. `backup` 先完成检查，再对三库 TRUNCATE checkpoint；只有成功后复制到不存在的新目录，文件 fsync，最后写 manifest 并同步目录。
4. 保存工具报告、manifest、数据库 SHA256、程序版本与存储位置；备份包含敏感身份/会话，目录 0700、文件 0600，并复制到受限异机位置。

check 可能修复落后投影，不是只读审计；人工改坏已投影前缀会被独立对账发现。临时空间与恢复时间按全历史预算；/tmp 不足会让 check/backup/restore 失败。manifest 的 SHA256 防意外字节错误，不是签名；数据库文件固定白名单，不从 manifest 任意路径复制。正规文件校验不是针对恶意并发路径替换的完整安全协议，维护目录仍需可信权限与停机。

备份目标必须不存在。正常错误返回会尝试清理本次创建的目标，原有目录不删除；强杀/清理失败可能留下无完整 manifest 的目录，不能把它当成功备份。先保存错误输出；若残留目录存在，保留排查，再选择新目标。运行中只拷贝 `.db` 会遗漏 WAL，禁止这种备份方式。

## 5. 恢复与投影重建

| 操作 | 使用场景 | 成功后的身份与数据 |
| --- | --- | --- |
| restore | 从可信完整备份恢复三个库到不存在的新目录 | dataset/用户/会话/原键结果继承备份；原目录保留 |
| rebuild-views | views 损坏/对账不符，journal/auth 完整 | 保持数据集与权威业务；从原日志重建查询库 |
| 初始化新目录 | 全新演示系统 | 新 dataset，新身份与序号，不能自动重发旧浏览器 pending |

restore 先校验 manifest/白名单/字节摘要，再创建新目录、复制、重放与逐表对账，最后匹配报告。原始数据不覆盖；正常失败尝试删除本次新建目标，强杀可能留下半成品。失败看 stderr 与目标状态，不把未成功返回的新目录切为 current。

rebuild-views 不通过普通 OpenStore 强行打开坏 views，而是先锁原目录，分别 checkpoint journal/auth，再复制到原目录内 staging，构造干净投影并独立检查。它不删除或改变权威业务记录；checkpoint 会改变权威数据库文件/WAL 的物理布局，不能说所有权威文件字节从不变化。

验证成功后，将旧 `views.db/-wal/-shm` 移到 `views-preserved-<时间戳>`，再 rename 新库并同步目录。多文件移动并非一个原子操作；替换失败可能处于旧文件已部分保留、主库缺失或新库尚未发布的状态。先保持停机，保留 preserved/日志及仍存在的 staging（正常返回会尝试清理 staging，强杀可能残留）；不要直接把旧 WAL/SHM 混配到新主库。主库缺失可从 journal 创建并恢复，已有文件的可用性由完整性和对账判断。

重建后应执行 check、启动 ready、验证会话/余额/原键确认与公共行情。不要删除 journal/auth 来绕过失败，不在同一数据目录起第二写者。

## 6. 数据集、版本与回滚

正常重启、投影重建、备份恢复保持 dataset_id；全新目录才生成新 ID。恢复较早备份虽保留同 dataset，但水位更低，旧高水位 min_seq 可能持续等待失败；不要以同 dataset 推断没有丢失备份后的记录，必须对账处理浏览器待确认请求与已确认命令。

数据集标识不是单机故障 fencing，也不保证跨主机同 dataset 唯一运行。flock 只在本地目录生效。回滚数据库到旧备份会丢失备份后的已确认命令，需先保留最新日志并明确数据方案。

业务语义升级要验证历史 fixture 或迁移；engine/schema/API 版本含义不同。本轮只有文档/注释更新，不升级这些版本或重发历史发布包。当前与历史证据见[文档报告](../reports/2026-10-11-documentation.md)、[测试完善报告](../reports/2026-10-11-test-hardening.md)。

## v0.5 链数据生命周期

chain-journal.db/commands 是订单命令权威，日志 schema 1 不变；chain-views.db 增加 indexed_blocks、chain_events、index_progress 和 view_metadata schema 2。删除 views 会从日志补订单，并从创世重建链索引，完整追平前对账可能为 lag；必须先保存完整任务权威。任务库 schema 2 的 version 列与 payload 版本一起更新，raw/nonce 不可由重建投影替代。停机一致性备份、同域恢复后访问回环 /check。

独立读池：日志/投影的 WAL 读取与唯一写连接分开，每读池1连接；SQLite读池query_only，PG任务Reader独立1连接，owner与任务写池仍分别占用专用/业务连接。TestReadSnapshotDoesNotBlockWriter 保持旧水位快照时仍能完成新命令，避免对账占住唯一写池。查询仍有CPU/磁盘与WAL保留成本，需要超时和后续增量策略。

对账还离线验签任务原交易：raw编码、sender、chain/to/value、hash/nonce与calldata都按当前域核对；不需relayer私钥、不调用发送RPC。终态对账测试额外损坏raw，必须报TASK_RAW_INVALID，检查不会尝试修复或广播。
