排查一台服务器时，命令记在聊天记录里，截图在桌面，最后的处理结果放进另一个文档。下一次遇到相似故障，能找到其中两样，却找不到完整过程。TriliumNext 适合把这些材料放在一棵笔记树里：一个问题有正文、附件和关联笔记，后续发现也能接着写。
这里部署一个个人笔记服务，重点是怎样把第一份资料整理好，以及怎样保住它。它可以在浏览器里使用，也能和桌面端同步；桌面端与服务端版本需要协调。多人实时协作、公共知识门户或者严格的团队权限管理，需要另行评估，不宜把个人笔记库直接当成团队文档平台。
一棵笔记树怎样安排才不累
笔记可以按项目和问题组织，也可以通过链接、属性和克隆把同一份内容放到不同上下文里。克隆有自己的用途：同一条故障说明同时出现在“服务器 A”和“数据库问题”下面时，仍然对应同一份笔记，修改会反映在关联位置。只有真的需要独立演化的内容才复制成两份。
刚建库时可以先分三个入口：正在处理、长期资料、已完成记录。每台机器或每个项目下面放一页概况，写系统版本、相关入口和维护事项，再把变更过程放在子笔记。不要把密码明文塞进概况页；密码库和知识笔记的访问范围不同，复制笔记做分享时也容易一起带走秘密。
从一个真实的小问题开始，例如“网站返回 502”。正文写清楚出现时间、看到的现象、检查命令、输出中关键的几行和最终处理。截图放在相关段落附近，给关联配置页加内部链接。以后搜索 502，得到的是能复用的排查过程，省去重新理解几张没有说明的截图。
安装前先决定用哪个版本
服务器已经安装 Docker Engine 和 Compose 插件，当前用户有 Docker 权限。示例以宿主机 Caddy 提供 HTTPS，域名 notes.example.com 先解析到 VPS。容器的 8080 端口只映射到本机。准备数据目录时，使用服务器上的本地磁盘，避免直接把 SQLite 数据目录放到语义不确定的共享文件系统上。
TriliumNext 官方镜像为 triliumnext/trilium，常规镜像的数据目录是 /home/node/trilium-data。rootless 镜像的目录不同，运行用户配置也不同，两个方案的参数不能混搭。下面采用常规镜像，镜像版本通过 .env 指定。
mkdir -p /opt/trilium/trilium-data
cd /opt/trilium
docker version
docker compose version
截至 2026 年 10 月 3 日，项目最新正式发布标签为 v0.106.0，本例将它写入 .env。如果稍后按本文安装，先查看正式发布说明和镜像标签是否一致。准备同步的桌面客户端时，要确认客户端和服务端的版本兼容性，再选择实际标签。
printf 'TRILIUM_VERSION=v0.106.0\n' > .env
services:
trilium:
image: triliumnext/trilium:${TRILIUM_VERSION:?set TRILIUM_VERSION in .env}
restart: unless-stopped
ports:
- "127.0.0.1:8080:8080"
environment:
TZ: Asia/Shanghai
volumes:
- ./trilium-data:/home/node/trilium-data
保存为 compose.yaml。.env 未填写时 Compose 会直接报错，避免不知不觉选到浮动版本。部署文档中常规镜像通过入口脚本安排运行用户，不支持随意添加 user:；若要改变 UID/GID，应使用所选版本支持的 USER_UID、USER_GID，并匹配数据目录所有者。
cd /opt/trilium
docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 trilium
curl -I http://127.0.0.1:8080/
检查日志里的数据目录和启动状态。目录挂载写错时，页面也可能暂时能用，但笔记留在了容器可写层里；重建容器之后才发现记录消失。初始化后查看宿主机 trilium-data 内是否出现数据库和配置，再重建一次容器验证持久化，验证时只用测试笔记。
私人初始化，再接 HTTPS
先从自己的电脑通过 SSH 转发访问初始化界面，替换命令中的账号与地址。
ssh -N -L 18080:127.0.0.1:8080 [email protected]
打开本机 18080 端口，选择新建笔记库并设置登录密码。如果已经有桌面端笔记库，需要按同步初始化流程安排现有实例，不要随手建一个空库，再把两个不同来源的数据库文件覆盖来覆盖去。先复制一份原有数据并确认版本，再开始同步。
宿主机 Caddy 的站点段如下。校验配置后重载，让浏览器通过 HTTPS 访问。若 Caddy 在另一个容器里，则改用共享网络上的服务地址，127.0.0.1 不能跨容器指向笔记服务。
notes.example.com {
reverse_proxy 127.0.0.1:8080
}
在域名入口重新登录，创建一条测试笔记并上传一个小附件，刷新后确认还在。代理如果限制上传大小，应先用小文件验证链路，再决定需要多大额度。没有必要为了几份普通文档取消所有上传限制。
个人笔记可能包含工作材料。可以把入口限制在自己的 VPN 内；需要公网访问时，保留应用认证，设置强密码，并查看当前版本支持的二次验证方式。登录页上没有明显报错，也不能说明陌生人无法访问分享链接或公开内容，发布分享前需要用未登录窗口核对可见范围。
把笔记写成下一次能接着用的记录
运行记录先保证能看懂。标题中放机器或项目名称，正文中保留日期和软件版本，让以后的人能判断命令在什么环境里执行。排障输出很长时，把原始附件保留，正文只写与结论有关的几行，并写清楚还没有排除的原因。
例如数据库连接失败，可以把“应用配置”“数据库账号权限”“网络检查”分别写成三条关联笔记。排查记录链接到它们，配置变更只改配置页。这样记录里的时间线不会被后续整理覆盖，也不用在每条故障笔记里复制一大段相同参数。
图片和附件要有说明。一个名字叫 image.png 的附件，半年后很难识别；“2026-10-03，迁移前磁盘占用”就容易判断。给附件写来源或对应步骤，也便于后来清理过期材料。上传后下载一次，核对能打开，不能只凭编辑器里出现图标就认定文件完整。
属性和关系功能适合有稳定用途以后再加。先用简单链接把服务器、项目和故障连起来，等确实需要按“未处理”“待升级”集中查看时，再设相应属性。一次建立几十个字段，往往会让新增笔记比解决问题本身还费时间。
桌面端同步需要单独验证
同步的目标是让服务端与桌面客户端共同维护同一个库，而不是通过网盘实时同步一份打开着的 SQLite 文件。先检查两端版本，再按桌面端同步设置填写服务器的 HTTPS 地址和所需凭据。设置完成后，从两端分别新建不同名字的测试笔记，等待同步并确认对方能看到。
再修改一次已有笔记，附上一个小文件，检查内容和附件一起同步。只看到树结构出现，不代表附件已经完成。长期离线的设备重新上线时，先观察同步状态和错误日志，确认完成以后再进行大批整理，减少误判和重复操作。
同步报错先看错误属于哪一层：域名或证书问题、认证失败、版本不兼容、还是代理超时。浏览器能打开首页，只证明普通页面请求正常，较大的同步请求仍可能被代理中断。不要把同步问题简单处理成清空一端数据；如果没有完整备份，清空可能把最完整的一份库也丢掉。
自动备份之外，还要留一份离机副本
Trilium 的内部备份可以帮助恢复误操作，但仍可能和数据库位于同一台机器。应用内的导出又适合拿走一部分内容，和完整迁移所需的数据目录不是同一件事。长期使用时，把完整目录备份到其他存储，记录对应镜像版本。
为了取得一致副本，可以短暂停止容器后打包。下面保存 .env 是为了保留确切的版本配置；如果其中以后加入了其他凭据，备份也要按敏感文件保护。
cd /opt/trilium
mkdir -p /opt/backups
docker compose stop trilium
tar -czf "/opt/backups/trilium-$(date +%F-%H%M).tgz" compose.yaml .env trilium-data
docker compose start trilium
把压缩包复制到另一处，再选一个独立目录做恢复测试。使用原版本启动，换掉宿主机监听端口，暂时不配置桌面客户端同步，避免恢复环境加入正常使用的同步链路。登录后检查正文、内部链接和附件，抽几条较早记录下载文件。能够打开首页的空库不算恢复成功。
升级时先读正式发布说明，特别是数据库变化和同步兼容性。备份完成后再更新镜像标签，观察日志，检查桌面同步。需要回退时，用升级前的数据和旧镜像一起恢复，不能假定旧程序可以直接读取新版迁移过的数据库。
笔记开始积累以后，最值得维护的是上下文：这条命令为什么执行，当时的环境是什么，最终证明了什么。服务安装只花一次时间，保存这些说明才会让下次排障少走一遍旧路。