ers123/obsidian-vault-rescue
GitHub: ers123/obsidian-vault-rescue
一套针对 iCloud 同步故障导致 Obsidian 笔记库丢失的应急恢复工具包，从本地缓存、浏览器数据及 AI 对话记录等多个非常规数据源中提取并重建丢失的笔记内容与结构。
Stars: 0 | Forks: 0
# obsidian-vault-rescue
一个用于恢复因 iCloud “桌面与文档文件夹”同步故障而丢失的 Obsidian 库的应急手册与工具包。
如果你的库在 iCloud 清理、账户注销，或者在你未仔细阅读的“合并”对话框之后消失了——其中的大部分内容可能仍然是可以恢复的。只不过不是在 Apple 告诉你的地方。
这个仓库打包了我在 2026 年 5 月丢失自己库时行之有效的经验：1,500 篇 Markdown 笔迹不翼而飞，没有任何警告，也不在废纸篓中，Time Machine 的备份也已经过期了三个月。我最终恢复了大约 99% 的文件结构、最近一周的完整内容，以及所有我曾阅读过的内容的参考痕迹。这些全部提取自七个未被集中记录的数据源。
在继续之前先说明一点：我不是开发者。我只是一个碰巧每天使用 AI 助手的 Obsidian 用户，这个仓库中的恢复方案是我与 Claude 花了七个小时共同解决问题的结果。这里的脚本是我们共同得出的清理后的版本。如果你也处在同样的境地——不是程序员，库没了，正在恐慌中——这正是为你准备的。
## 如果这事刚发生在你身上，请先阅读本节
在做任何其他事情之前，请停止以下操作：
1. 不要重新安装 Obsidian。它的 IndexedDB 缓存保存了你最后一周的编辑。重新安装会将其清除。
2. 不要注销 iCloud。这可能会触发另一个合并对话框，并在你的其他设备上完成删除操作。
3. 不要在任何地方清空废纸篓。
4. 如果你有另一台使用相同 Apple ID 的 Mac（或 iPad），请立即断开其 Wi-Fi 连接。它可能仍有 iCloud 即将覆盖的本地副本。在这里争取到几分钟至关重要。
然后阅读 [`docs/01-diagnosis.md`](docs/01-diagnosis.md)。
## 此工具包的功能
它对 Obsidian、Chrome 和 Claude Code 保存你工作痕迹的每个位置运行只读提取器，然后将所有内容写入一个单独的 `--output` 目录中，你可以浏览、合并该目录，并有选择地进行恢复。
| 来源 | 你将获得的内容 | 脚本 |
|--------|--------------|--------|
| Time Machine / iCloud 数据恢复 | 截至上次备份或 30 天窗口期的完整正文 | (手动 — 见文档) |
| Obsidian IndexedDB `*-backup` | 最近编辑的文件及完整内容 | `scripts/extract_obsidian_indexeddb.py` |
| Obsidian IndexedDB `*-cache/metadata` | 库中每个文件的 Frontmatter 和标题 | (同一脚本) |
| Claude Code 对话日志 | 通过 Claude 编写或编辑的每个文件 | `scripts/extract_claude_logs.py` |
| Chrome 浏览历史记录 | 你曾研究过的 URL，AI 聊天 URL（见下文） | `scripts/extract_chrome_history.py` |
| Obsidian Web Clipper 扩展 | 最近的剪藏历史（URL、标题、目标路径） | `scripts/extract_web_clipper.py` |
| **AI 聊天记录（ChatGPT、Claude、NotebookLM 等）** | **你与助手共同创建的完整笔记——可直接粘贴** | 手动；URL 列表来自 Chrome 历史记录 |
单个协调器 `scripts/recover.py` 可以运行所有这些脚本。
事实证明，最后一行对我来说是产出最高的途径。你在编写笔记时与 AI 助手进行的对话保存在提供商的服务器上，不受本地数据丢失的影响。对于你与助手共同创建的文档——草稿、提示词、摘要——你通常可以通过一个提示词逐字重新提取它们。参见 [`docs/06-ai-chat-recovery.md`](docs/06-ai-chat-recovery.md)。
## 快速开始
```
git clone https://github.com/ers123/obsidian-vault-rescue
cd obsidian-vault-rescue
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# 运行所有内容。只读 — 这绝不会触碰你的实际数据。
python scripts/recover.py --output ~/vault-recovered
```
输出目录将如下所示（文件夹名称将是你自己库的结构）：
```
~/vault-recovered/
├── 02-Library/ ← full-content recoveries
├── 05-System/
├── _SKELETONS/ ← frontmatter + headings for every file
├── _FROM_CLAUDE_LOGS/ ← files written via Claude Code
├── _REFERENCES/
│ ├── all_visits.tsv ← every URL you visited in the date window
│ ├── content_sites.tsv ← Substack / Every / Medium / etc.
│ ├── ai_chats.tsv ← ChatGPT / Claude / Gemini conversation URLs
│ ├── youtube.tsv
│ └── web_clipper_history.json ← recent clips with titles + URLs
├── _FULL_FILE_LISTING.tsv ← every file that existed, with mtime + size
└── _RECOVERY_MANIFEST.txt ← what was fully recovered, newest first
```
## 如何将恢复的数据与 Time Machine 合并
最丰富的组合通常是：
1. Time Machine —— 恢复到其自己的文件夹中，为你提供上次备份时库中所有文件的完整正文。
2. `scripts/extract_obsidian_indexeddb.py` —— 叠加最后一周的编辑（具有更新 mtime 的文件胜出）。
3. `scripts/extract_claude_logs.py` —— 叠加你通过 Claude Code 协作编写的任何内容。
4. `_SKELETONS/` —— 单独保留，作为正文无法恢复的文件的脚手架。在重写时使用它们来回忆结构。
5. `_REFERENCES/ai_chats.tsv` —— 重新打开 ChatGPT / Claude 对话。它们的完整内容保存在提供商的服务器上，通常是合成这些笔记的最佳来源。
有关具体的合并命令，请参见 [`docs/02-recovery-paths.md`](docs/02-recovery-paths.md)。
## 背后的故事
[`CASE_STUDY.md`](CASE_STUDY.md) —— 实际发生了什么，什么起作用了，什么没起作用，每一个死胡同，以及如果你不是程序员，与 AI 助手一起解决这个问题的实际体验是什么样的。
## 预防措施（即使你还没遇到过问题，也请阅读本节）
[`docs/04-prevention.md`](docs/04-prevention.md)
简短版本：
- 如果开启了 iCloud “桌面与文档文件夹”同步，请勿将你的库放在 `~/Documents/` 或 `~/Desktop/` 内。
- 使用 iCloud 同步区域之外的路径，例如 `~/Obsidian/`。
- 对于多设备使用，请付费购买 Obsidian Sync 或使用私有 Git 仓库。不要通过 iCloud 同步库本身。
- 保持外置 Time Machine 硬盘连接。大多数在这里受益于备份的人之所以只有一个过期的备份，是因为硬盘一直被扔在抽屉里。
## 为什么会发生这种情况（以及为什么 Apple 不会修复它）
[`docs/05-why-icloud-fails.md`](docs/05-why-icloud-fails.md) ——
对导致这种丢失模式不可避免的架构选择的分析，以及为什么它们中没有一个是 Apple 会描述为“出 Bug”的问题。
## 你在其他地方看不到的两种恢复技术
- [`docs/06-ai-chat-recovery.md`](docs/06-ai-chat-recovery.md) ——
将你的 AI 聊天记录（ChatGPT、Claude、NotebookLM 等）作为主要的内容恢复源。这是我自己恢复过程中最令人惊讶的一件事。
- [`docs/07-skeleton-archaeology.md`](docs/07-skeleton-archaeology.md)
—— 读取恢复的骨架路径集，以重建任何单个文件本身都不会记录的库历史（文件夹重组、批量移动、模板重新设计）。
## 许可证
MIT。使用它，分叉它，拯救某人的库。
## 免责声明
这不是专业人士提供的数据恢复建议。这对我来说行之有效。运行脚本的风险由你自行承担；它们在设计上是只读的，但软件难免有 Bug。请始终在你不想丢失的任何缓存的副本上进行操作。
标签：Apple生态, Chrome IndexedDB, eDiscovery, HTTP工具, iCloud同步, Markdown, Obsidian, Playbook, ProjectDiscovery, 取证工具包, 库, 应急响应, 数字取证, 数据丢失防护, 数据保护, 数据恢复, 数据恢复脚本, 数据泄露, 文件系统恢复, 法证调查, 浏览器缓存提取, 灾难恢复, 电子数据发现, 笔记恢复, 自动化脚本, 逆向工具