Z.G.的数字花园

Quartz 404 排查与迁移回滚记

10分钟阅读

Quartz 数字花园 404 排查记：AI 把我带沟里去了

⚠️ 剧透预警

归根结底：bind mount 挂错了路径。别人把内容放 A 文件夹，Quartz 盯着的却是 B 文件夹。就这么简单——但 AI 硬说这是”跨操作系统文件系统阻塞”，建议我全量迁移。结果绕了一大圈又滚回来了。

先给不懂技术的朋友补课

什么是 bind mount？

想象你有一栋房子（Windows D 盘），里面有个书房（网站展示/ 文件夹）。你在后院搭了个工作间（WSL 的 ~/quartz/content/ 目录）。

Bind mount 就像在工作间墙上开一扇门，直接通到书房——你在工作间伸手就能拿到书房的书，不用来回跑。但问题是——这扇门开错位置了。

什么是 rsync —delete？

rsync 是”同步工具”，--delete 是”删除目标目录里有但源目录没有的文件”。用的时候一定要小心：

这就像”把左边口袋的东西整理到右边口袋，右边有而左边没有的，扔掉”。如果左边口袋是空的，右边口袋的东西会被扔光。

第一阶段：发现不对劲

视觉改造（先搞了装修）

我用 Cursor + Gemini 对数字花园来了一次大装修：

  • 换招牌：网站标识从”大菜”改成”Z.G.”
  • 换字体：引入衬体字（Noto Serif SC），排版更精致
  • 昼夜模式：白天商务风，晚上深炭灰
  • 加导航：启用了面包屑导航、文件夹树默认展开
  • 做减法：列表圆点改短横线，移除 Emoji 图标

装修过程中踩了两个小坑：

  • 坑①：AI 改配置时没覆盖旧的，导致重复定义，改了半天不生效
  • 坑②：AI 改布局文件时漏了 export 关键字，编译直接报错

发现 404

装修完本地预览一看：

  • 左侧边栏显示的文件夹是空的
  • 中间内容区显示了三个文件夹：Finance_Logic、Trade_Workflows、Tech_Stack
  • 随便点一个 → 404 页面

第二阶段：AI 的错误诊断

Gemini 的分析（看着很专业，其实是错的）

Gemini 排查完给出了一个”高深”的判断：

“WSL DrvFs 跨系统 I/O 阻塞导致 bind mount 无法递归扫描子文件夹。”

这段翻译成人话：Gemini 说因为 Windows 的 D 盘是通过 USB 线连到 Linux 的，这条线太细了，Linux 没法透过这条线看清楚文件夹的结构。

听起来很有道理对不对？但这是错的。

实际的真相

我从头检查了一遍，发现：

# 实际配置（错的）
~/quartz/content  →  bind mount 到了 D:\（整个 D 盘根目录）
 
# 应该配置（对的）  
~/quartz/content  →  bind mount 到了 D:\个人知识库\网站展示\

Quartz 盯着整个 D 盘看，当然找不到 网站展示/ 下面的子文件夹。 就好比你让人去厨房拿盐，但他去了整个超市——超市太大，他转晕了。

而且旧技能里还有一条”定时炸弹”：

rsync -a --delete "/mnt/d/个人知识库/网站展示/" ~/quartz/content/

网站展示/ 文件夹一直为空，--delete 参数在每次同步时都在静默清空 ~/quartz/content/。这是雪上加霜，但不是根本原因——就算不清空，Quartz 也找不到正确的内容。

第三阶段：错误的迁移（负优化）

我被引导要求”提取同步逻辑”

Gemini 的结论（DrvFs 阻塞）听起来太专业了，我信了。我按照”方案 A”执行了一整套迁移：

  1. 卸载旧的 bind mount
  2. 在 WSL 内部建了一个新仓库 ~/knowledge-vault/
  3. 从 D 盘复制 5 篇手册 + 2 篇复盘过去
  4. 重写自动化脚本，所有路径指向 WSL
  5. 更新系统配置

做完发现问题大了

我发现：

  • ❌ Obsidian（笔记软件）在 Windows 上，读不到 WSL 内部的路径
  • ❌ ~/knowledge-vault/ 和 D 盘变成了两份数据，没有同步机制
  • ❌ 本来数据单向流动（D 盘 → Quartz），现在变成分叉了

这是一次明明白白的负优化——对 Hermes（AI）写文件是方便了，但对我在 Obsidian 上读文件变差了。

第四阶段：回滚（拨乱反正）

回滚决策（三步走）

  1. 删掉 ~/knowledge-vault/（D 盘有完整备份，不怕丢）
  2. 脚本路径全部改回 /mnt/d/个人知识库/
  3. 只修 Bug，不动物理结构

数据恢复

# 从 Git 历史恢复被清空的内容
cd ~/quartz && git restore content/

成功恢复 4 篇文章 + 首页 index.md。另外补了一篇 Git 没追踪的新文章。

真正的 Bug 修复

Bug旧代码修复
rsync --delete 静默清空rsync -a --delete "网站展示/" ~/quartz/content/改为安全的 cp -r
bind mount 挂错位置~/quartz/content → D:\（整个 D 盘）卸载，content 改为普通目录
write_file 不落盘用 terminal 写入有时不触发 Windows 通知改用 Python open() 写 D 盘

最终架构

D:\个人知识库\           ← 唯一主数据源（Obsidian 直接读写）
    ├── 手册\           ← 5 篇
    ├── 笔记\           
    ├── 复盘\           ← 3 篇（含本篇）
    ├── Inbox\          ← 收件箱
    └── 网站展示\       ← 公网发布副本
        └── 行业研究\
        └── 复盘\

~/quartz/content/       ← 普通 WSL 目录（不是 mount 点）
                        通过 cp 从 D 盘同步过来

教训总结

教训 1：AI 诊断链条越长，误判概率越大

这次故障的层层传递：

我发现 404
  → 问 Gemini
    → Gemini 看到 bind mount → 认为是 DrvFs 跨系统问题
      → 建议"方案 A"全量迁移
        → 我让 Zack 查路径
          → Zack 按"方案 A"执行迁移
            → 做完发现负优化
              → 回滚

如果第一步检查 mount | grep quartz，发现 bind mount 指向 D:\ 而不是 D:\个人知识库\网站展示\，后面所有操作都不会发生。

以后遇到问题，先检查最基础的配置，而不是相信 AI 的”高深”分析。

教训 2：不要为了解决 AI 的问题制造用户的问题

迁移到 WSL 内部对 Zack（AI）写文件方便了，但对我（Obsidian 用户）读文件变差了。

改之前应该先问：“你的工具也在这条路上吗？” 有时候”对机器好”不等于”对人好”。

教训 3：技术人的爽 ≠ 用户的爽

Zack 觉得 ext4 比 DrvFs 快 3-5 倍、没有锁文件的问题——这些都是技术层面的好处。但对我来说，D 盘才是家。Obsidian 在 Windows 上读 D 盘是本地操作，读 WSL 内部要绕网络路径，体验差很多。

教训 4：--delete 是一个需要敬畏的参数

# 这条指令在"网站展示"为空时 = 静默清空 content
rsync -a --delete "/mnt/d/个人知识库/网站展示/" ~/quartz/content/

--delete 不是”同步”——是镜像。源目录为空，目标目录也会变空。用 cp 替代后，再也没有这个隐患了。

附录：操作验证清单

以后再遇到类似问题，按这个顺序查：

序号检查项命令
1bind mount 挂到哪了？mount | grep quartz
2content 目录有什么？ls ~/quartz/content/
3源目录（网站展示）有什么？ls "/mnt/d/个人知识库/网站展示/"
4Quartz 构建报错吗？cd ~/quartz && npx quartz build
5Cloudflare 部署成功了吗？等 1 分钟后刷新页面