笔记系统与数据库维护

很多人提到 Trilium，第一反应是“一个自托管笔记系统”。但只要你真的把它长期跑在 VPS 上，问题很快就不会停留在“能不能打开网页”这个层面，而会变成：

这篇就把我这次处理 Trilium 的实际经验整理一下。

一、第一条原则：不要先相信工作区里的 compose 文件

这次最先确认清楚的一件事是：工作区里的 compose 文件，不一定就是你线上真实运行的那套。

很多时候你会在某个项目目录看到类似：

./trilium-data:/home/node/trilium-data

然后直觉上就觉得，“那我的数据目录一定就在这个项目目录旁边”。但真实情况经常不是这样。尤其一台已经跑了很多服务、经历过多轮调整的 VPS，容器和数据目录可能早就不在那个地方了。

我这次最终确认到的真实路径是：

/opt/trilium
/opt/trilium/trilium-data
/opt/trilium/trilium-data/document.db

这个确认本身就很重要。因为后面无论是备份、升级、读库还是排障，全部都建立在“你先找对了真实数据目录”这个前提上。

二、什么时候该直接看 SQLite，而不是前端

如果你的问题是下面这些之一：

那这时候前端页面其实不够可靠，你应该直接看 SQLite。

Trilium 这类系统一个典型误导点就是：前端没刷新，不代表数据没变。所以这次我直接从本地数据库去看：

只要这些表里的记录还在，就说明问题大概率不是“数据丢了”，而是“前端状态没刷新到你想看的样子”。

三、直接改 SQLite 不是禁区，但要知道自己在做什么

我这次实际就做了两类事情：

  1. 读库确认结构与真实数据位置
  2. 直接写库，新增/调整笔记内容和树结构

这听起来很激进，但在某些场景下反而是最直接的方式，尤其是当你要批量改笔记、补树结构、做同步笔记的时候。

不过这里有个前提：你得清楚自己改的是什么表、为什么改，而且最好先确认这些改动的影响范围。直改库不是日常首选，但也不应该被神化成“绝对不能碰”。

四、真正让我踩坑的不是写库，而是“写完前端没变”

这次最有价值的经验，反而不是“如何写库”，而是这条：

直接改 Trilium SQLite / 调整笔记树结构后，前端不一定会立刻可见。

这件事在第一次碰到时很容易让人误判：你明明查库看见数据已经写进去了，但网页里就是不显示，或者树结构位置不对。于是你会开始怀疑：

但这次实际证明：很多时候，数据库已经是对的，只是 Trilium 前端/内存状态还没刷新过来。

而最直接有效的收尾动作就是：

docker restart trilium

我这次就是在重启之后，前端才把新增笔记和树结构稳定显示出来。这个经验以后我会默认记成规则：只要直接动过库或改过树，就顺手重启 Trilium。

五、升级前不要省那一分钟备份

这次升级 Trilium 时，我先做的不是 pull 镜像，而是先备份：

rsync -a /opt/trilium/trilium-data/ /opt/trilium/backups/trilium-data-时间戳/
cp -a /opt/trilium/docker-compose.yml /opt/trilium/backups/docker-compose.yml.时间戳

为什么这一步必须做？因为真正有价值的不是容器本身，而是：

容器升级失败，大不了重拉镜像；数据目录出问题，才是真正伤筋动骨。

六、这次升级实际怎么做的

确认好数据目录并备份之后，这次的升级流程其实很简单：

cd /opt/trilium
docker compose pull trilium
docker compose up -d trilium

然后做三件验证：

  1. 看容器是不是 healthy
  2. 看日志有没有异常
  3. 本机打开 http://127.0.0.1:8383 和 /login 是否正常返回

这次最终升级后的版本是：

TriliumNext 0.102.2

而且容器状态正常，本地访问也没问题。对于一台多服务 VPS 来说，这已经算是非常理想的升级结果了。

七、Trilium 在多服务 VPS 里的正确维护思路

我现在对 Trilium 的态度很明确：它不是一个“装上就不管”的附件服务，而是一个会承载越来越多个人知识、运维笔记和工作痕迹的长期系统。

所以维护思路应该是：

八、我现在把它当成什么

对我来说，Trilium 现在已经不只是“一个笔记网页”。它更像这台 VPS 上的个人知识层：

所以这次一边升级、一边补树、一边写库，其实不是杂活，而是在把它慢慢变成真正可维护的知识系统。