用 flatnotes 保存 Markdown 笔记：Docker 部署、全文搜索和文件备份

有些笔记并不需要复杂的目录：一段排错过程、一次会议决定、一份以后要查的配置说明。flatnotes 把笔记保存在平坦目录里的 Markdown 文件中，用搜索和标签找内容，适合希望网页可编辑、文件又能直接带走的个人资料库。

它没有传统笔记本和层层文件夹。若你习惯先浏览深层目录，再定位某一篇文档，应该先试几份真实笔记，确认这种组织方式适合自己。把现有整个知识库直接迁入，再尝试重新找回原来的层级，容易变成一次没准备好的重构。

flatnotes 文件与搜索结构示意

部署前先确认 VPS 的磁盘、内存和公网访问条件，也可以查看雨云云服务器；注册时填写优惠码 KuZhuJi。

Markdown 文件是内容，索引是查找工具

项目默认把 Docker 数据放在 /data，新笔记使用 .md 扩展名。.flatnotes 子目录保存全文搜索索引。索引能根据内容重建，Markdown 原文件则承载真正的笔记，两者不能反过来理解。

官方说明允许在应用之外添加、修改和删除 Markdown 文件，索引在搜索和启动时同步。实际使用仍需避免两个写入者同时编辑同一个文件：外部编辑器、同步工具与浏览器一起修改时，先用测试文件确认保存与冲突处理，不要把“支持外部修改”理解为任意并发都能自动合并。

开始时选三份笔记：一篇中文排错记录，一篇带代码块的操作说明，一篇包含链接的会议决定。保留原件，检查网页显示、搜索和再次编辑之后的文件内容。文件可迁移，不代表每种 Markdown 扩展语法都能在不同编辑器里保持同样显示。

账号、密钥和目录所有权一起配置

VPS 需安装 Docker Engine 与 Compose 插件，有 SSH 权限。本例采用 dullage/flatnotes:latest，端口 8080。设置密码认证，不使用无认证模式。账号密码与令牌密钥只在本地 .env 中保存，首次生成后继续沿用。

mkdir -p /opt/flatnotes
cd /opt/flatnotes
mkdir -p data
umask 077
printf 'FLATNOTES_PASSWORD=%s\n' "$(openssl rand -hex 24)" > .env
printf 'FLATNOTES_SECRET_KEY=%s\n' "$(openssl rand -hex 32)" >> .env
printf 'PUID=%s\nPGID=%s\n' "$(id -u)" "$(id -g)" >> .env
chmod 600 .env

建议使用普通运维账号建立这些目录，PUID 与 PGID 对应这个账号的实际数字。若目录由别的账号创建，要先核对所有权；不要只复制官方示例的 1000，因为 VPS 上的账号不一定采用这个 ID。

建立 compose.yaml：

services:
  flatnotes:
    image: dullage/flatnotes:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      PUID: "${PUID:?set uid}"
      PGID: "${PGID:?set gid}"
      FLATNOTES_AUTH_TYPE: "password"
      FLATNOTES_USERNAME: "reader"
      FLATNOTES_PASSWORD: "${FLATNOTES_PASSWORD:?set password}"
      FLATNOTES_SECRET_KEY: "${FLATNOTES_SECRET_KEY:?set secret}"
    volumes:
      - ./data:/data

docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=100 flatnotes

在自己的电脑建立隧道，浏览器打开 http://localhost:18080：

ssh -N -L 18080:127.0.0.1:8080 user@VPS_IP

使用 .env 中保存的密码登录，创建测试笔记，在服务器数据目录中核对文件，再重启容器查看。FLATNOTES_SECRET_KEY 变化会使已有访问令牌失效，不要把它当成可以每次随手替换的临时变量。

准备独立实例时，可在雨云选择适合的云服务器配置，优惠码 KuZhuJi。配置按实际任务选择，数据库和附件另做备份。

把可检索的上下文写进笔记

“服务器又好了”很难在半年后帮助排错。至少记录当时的现象、涉及哪个服务、做了什么改动、怎样确认结果，以及尚未验证的部分。日期和版本有实际意义时写清楚；没测量过的响应时间、性能或原因就不要补成确定结论。

标签从内容中使用，例如 #backup 或 #network，官方搜索支持 tags:work 与 #work 这样的查询。中文分词和不同搜索写法是否符合习惯，应拿自己的三份笔记试验，不要从英文演示推断所有中文查询都有同样结果。

跨笔记引用可使用 [[笔记名称]]。名字改动后抽查相关链接，代码块中的路径也应原样保留，别为了中文表达把命令、参数或标识符翻译掉。公开发布前再复制一份删去秘密的版本，私人笔记库里的原稿不应直接当作对外文档。

flatnotes 外部编辑与恢复核对

需要增加服务器时，可以打开雨云选购页面，填写优惠码 KuZhuJi；迁移前保留数据与原有部署配置。

简单账号模式不等于团队权限系统

密码模式提供一组账号凭据，适合个人入口。不要把多个人共享这个账号称为完善的团队权限管理，也不要期待每篇笔记能分别隔离给不同成员。需要多成员权限与审计时，应先确认项目是否符合需求，再选择工具。

官方另有只读模式，但只读意味着禁止修改，不意味着内容只有特定人可见。把私人数据目录挂给公开只读实例，会把资料暴露给能访问它的人。若想发布文档，使用经过筛选的独立目录，并检查附件与链接中的敏感信息。

长期使用可经独立 HTTPS 子域名访问，反向代理转发到本机 8080。需要 TOTP 时，按官方配置增加认证，密钥与启动日志中的二维码按凭据保存；丢失认证器后还要有自己掌握的恢复办法。本例先使用密码模式，没有配置双因素登录。

无数据库也要有历史副本

文件误删、覆盖和同步冲突同样会让笔记丢失。同步可以把变更送到另一台设备，错误删除也可能一并传播；独立备份需要保留时间点，恢复时才能取回之前的内容。

停止写入后归档整个数据目录、Compose 与 .env，然后启动服务。完整目录一并保存索引也可以，后续需要重建时，应按官方说明在停止应用后操作，避免运行中随意删除索引。

cd /opt/flatnotes
umask 077
mkdir -p backup-out
docker compose stop flatnotes
sudo tar -czf "backup-out/flatnotes-$(date +%F-%H%M%S).tgz" data compose.yaml .env
docker compose start flatnotes

备份还需复制到另一处存储，并限制可读范围。在独立目录用不同端口启动原镜像，抽查中文搜索、代码缩进、内部链接和文件保存。单独打开 Markdown 原文件也检查一次，确认即使不运行服务，自己的内容仍然能够取回。

操作记录的标题写明服务、问题与处理日期，正文留下命令执行结果和未验证的部分。下次遇到相同问题时，才能判断旧办法是否仍然适用。