docs: 迭代报告——standalone 写路径性能与持久化排障复盘

[NeverENG]

记录本轮排障链的复盘小故事（用户要求写入 docs 稍后阅读）：225 qps 归因 → group commit → 挖出 SSTable 重载致命 bug → WAL 自清洁 → 自审原子重写。关联 PR #150/#153/#157/#159/#158。

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added a detailed guide covering standalone write durability troubleshooting and recovery.
  • Documented WAL batching, checkpoint cleanup, crash-safe replacement, performance comparisons, and reproduction steps.
  • Added validation scenarios for restart recovery and atomic WAL updates.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: fdc7012b-c807-4ead-9a3d-3875651ec356

📥 Commits

Reviewing files that changed from the base of the PR and between 9adfbd6 and f948052.

📒 Files selected for processing (1)

• docs/iteration-2026-07-19-standalone-write-durability.md

---

📝 Walkthrough

Walkthrough

新增 standalone 写入耐久性迭代复盘文档，记录性能瓶颈定位、WAL 与 SSTable 修复、恢复测试、原子替换方案及复现实验。

Changes

Standalone 写入耐久性

Layer / File(s)	Summary
性能与耐久性修复复盘 docs/iteration-2026-07-19-standalone-write-durability.md	记录 fsync 瓶颈、WAL group commit、SSTable MaxKey 恢复修复、WAL checkpoint、cpMu 并发约束及 tmp 文件加原子 rename 的 WAL 重写方案，并附性能数据、测试与复现命令。

Estimated code review effort: 1 (Trivial) | ~3 minutes

Possibly related issues

• NeverENG/BanDB issue 132：涉及 standalone 写路径的 WAL/memtable 原子性与并发问题，与文档记录的 cpMu、checkpoint 和原子 WAL 替换直接相关。

Possibly related PRs

• NeverENG/BanDB#34：涉及 SSTable block index 的 LastKey/MaxKey 及恢复元数据路径。
• NeverENG/BanDB#150：涉及 WAL Append、flushLoop 与批量 Sync 的同一实现路径。

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/iteration-standalone-durability

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🐯 BanGD 数据库内核评审

整体风险：🟢 低

变更总结：这是一个纯文档 PR（docs/iteration-2026-07-19-standalone-write-durability.md），记录了一次完整的排障链复盘——从 225 qps 性能瓶颈归因（group commit），到挖出 SSTable 重载导致已刷盘数据全丢的致命 bug，再到 WAL 自清洁 checkpoint 以及原子重写修复。文档本身不涉及代码变动，但它详细描述了 storage/zstorage 层的多个核心架构决策：group commit 的批量化 fsync、双表 MemTable 的 active/dirty 配合 cpMu 读写锁做 checkpoint、以及用 os.Rename 替代三步骤 Truncate→Write→Sync 实现 WAL 原子重写。这些决策涉及并发所有权（cpMu 设计）、崩溃安全不变量（WAL before data）、存储格式兼容（SSTable footer 的 MaxKey 懒加载 vs 索引末项）、以及热路径性能（fsync 摊销）。

本评审不阻塞合入；架构级建议以 Issue 形式跟踪，普通问题在下方内联列出。

架构问题（共 2 项）

• [存储] WAL checkpoint 增量重写可代替全量重写 docs/iteration-2026-07-19-standalone-write-durability.md → 🐯 [存储] WAL checkpoint 增量重写可代替全量重写 · iteration-2026-07-19-standalone-write-durability.md #161
• [并发] cpMu 读锁粒度过粗，group commit 批内写入仍串行 docs/iteration-2026-07-19-standalone-write-durability.md → 🐯 [并发] cpMu 读锁粒度过粗，group commit 批内写入仍串行 · iteration-2026-07-19-standalone-write-durability.md #162

---

_{本次评审消耗 token：共 45645 tokens（输入 34588，输出 2481，缓存命中 8576，缓存写入 0）｜维度 [concurrency, memory, lock, storage, performance]｜补充阅读周边文件 [storage/zstorage/memtable.go]｜对抗式复核 3 票/条，过滤疑似误报 0 条}