flatnotes 介绍与选型指南

目标：讲清 flatnotes 是什么、为谁设计、核心能力与边界，并与 memos、SilverBullet、Standard Notes、Note Mark、Trilium 等同类自托管笔记组件做量化对比，帮助读者在 5 分钟内完成「是否选它」的判断。本文为认知篇，全部信息来自官方仓库与官方文档的联网溯源（查询日期 2026-10-30），未混入本地实验结论。

一、环境信息

本文为认知篇，不依赖本地部署，信息来源与查询日期如下：

💡 说明：flatnotes 早期社区资料中常见 b4bz/flatnotes 镜像与 jim8023 账号指向，2026-10-30 实查官方 README 已统一指向 dullage/flatnotes 仓库与 dullage/flatnotes 镜像，旧引用为历史沿革，选型与部署时应以 dullage 命名空间为准。

二、软件概述

flatnotes 是一个自托管（self-hosted）、无数据库的笔记应用：整个笔记库就是服务器上的一个普通文件夹，每条笔记是一个纯 Markdown 文本文件，没有数据库、没有私有格式、没有复杂目录层级。作者在 README 中给出的设计原则有三条：

1. 内容优先：界面干净、无干扰，笔记正文永远排在第一位；
2. 不搞组织结构：没有文件夹、笔记本之类的层级概念，全部笔记平铺在一个目录里，靠强大的搜索与标签能力组织；
3. 不绑架数据：笔记就是普通 .md 文件，随时可以把整个目录拿走换用其他工具，flatnotes 运行期间也允许在应用外直接增删改这些文件（搜索索引会在每次搜索时增量同步）。

💡 技术拓展：自托管笔记应用按「数据存放形态」可分为三类，选型时先想清楚你要哪一类——

形态	代表组件	特点	适用场景
纯文件存储（无数据库）	flatnotes、SilverBullet	笔记即 .md 文件，可用任意编辑器/同步盘/脚本直接处理，迁移成本≈零	重数据所有权、要跟 Git/网盘联动的个人知识库
数据库存储	memos、Note Mark	写入性能好、易做多用户与关联查询，但数据被锁在库内，迁移要靠导出	多人轻量分享、碎片化记录
端到端加密存储	Standard Notes	数据加密后落库，隐私最强，但服务端不可读，搜索/处理受限	隐私敏感场景

flatnotes 属于第一类，且是其中「结构最简」的一个（连文件夹层级都砍掉了）。

三、核心架构

flatnotes 的架构在同类组件里属于「轻到极致」的一类，2026-10-30 实查官方仓库代码结构与 README 后归纳如下：

这个架构决定了 flatnotes 的几个关键行为特征：

• 进程极轻：后端是单进程 Python 服务，没有数据库子进程，资源占用在同类中处于最低档；
• 文件即真相：磁盘上的 .md 文件就是唯一数据源，索引只是缓存，删掉索引目录重启即可重建；
• 部署只有一种官方形态：官方 README 明确「自托管推荐使用 Docker」，镜像为 dullage/flatnotes，数据目录统一挂载到 /data。

四、功能特性

以下特性清单来自官方 README（2026-10-30 实查），flatnotes 功能刻意保持克制，Roadmap 中作者明确「为保持简单会限制新特性」：

• 移动端响应式 Web 界面：手机浏览器直接使用，无独立 App；
• Raw/WYSIWYG 双模式 Markdown 编辑器：源码模式与所见即所得模式一键切换（TOAST UI Editor）；
• 高级全文搜索：基于 Whoosh，支持相关度排序、标题/内容高亮、按标题/修改时间排序；
• 标签功能：在笔记正文里写 #tag 即完成打标，应用内按标签聚合检索；
• 可定制首页：首页快捷访问区块（Quick Access）可改标题、检索词、排序与条数；
• Wikilink 笔记互链：正文中写 [[另一篇笔记标题]] 即可在笔记间跳转；
• 明/暗两套主题；
• 多种认证模式：无认证（none）、只读（read_only）、用户名/密码（password）、TOTP 两步验证（totp）；
• RESTful API：笔记 CRUD、搜索、标签、附件均有 HTTP 接口，自带 /docs 在线接口文档。

其中「标签」与「Wikilink」值得单独说明，两者都是 flatnotes 用极低成本实现的组织能力：

• 标签是从正文正文中原地识别的：任何笔记内容里出现 #运维 这类片段，搜索索引就把它收进标签表，不需要预先建标签体系；
• Wikilink 是按标题字符串链接：不存笔记 ID，重命名标题后旧链接需要手动跟进，这是纯文件存储形态的天然取舍。

五、快速开始

flatnotes 官方推荐的唯一部署形态是 Docker，README 给出的最小 Docker Compose 示例如下（照录官方 README「Example Docker Compose」一节）：

version: "3"

services:
  flatnotes:
    container_name: flatnotes
    image: dullage/flatnotes:latest
    environment:
      PUID: 1000
      PGID: 1000
      FLATNOTES_AUTH_TYPE: "password"
      FLATNOTES_USERNAME: "user"
      FLATNOTES_PASSWORD: "changeMe!"
      FLATNOTES_SECRET_KEY: "aLongRandomSeriesOfCharacters"
    volumes:
      - "./data:/data"
      # Optional. Allows you to save the search index in a different location:
      # - "./index:/data/.flatnotes"
    ports:
      - "8080:8080"
    restart: unless-stopped

只需四个环境变量即可跑起密码登录形态：FLATNOTES_AUTH_TYPE、FLATNOTES_USERNAME、FLATNOTES_PASSWORD、FLATNOTES_SECRET_KEY（用于给登录会话 Token 签名，务必用长随机串）。把上面文件保存为 docker-compose.yml 后 docker compose up -d，浏览器访问 http://<服务器IP>:8080 即进入登录页。

完整的编排参数、国内镜像源拉取实测、端口规划、数据持久化与升级备份等操作细节，见《flatnotes v5.5.5 Docker Compose 部署指南》；全部环境变量的默认值与生效机制，见《flatnotes v5.5.5 配置参数详解》；登录 Token 获取与笔记 CRUD/搜索/附件接口的逐条实测，见《flatnotes v5.5.5 常用工具与 API 详解》。

六、适用场景与限制

适合的场景：

• 个人知识库：重内容、重搜索、不想要文件夹层级的单用户/单人使用场景；
• 数据所有权敏感的团队：笔记必须落在自有磁盘、必须能被脚本和 Git 管理、必须能随时迁走的场景；
• 内网资料速查站：配合 TOTP 或只读模式，把运维手册、配置片段、SOP 沉淀成一个内网可检索的轻量站点；
• 低配设备/NAS：单进程 Python 服务、无数据库依赖，资源占用极低。

明确的限制（选型前必须接受）：

• 单用户设计：全局只有一套用户名/密码，没有多用户、没有权限分组、没有协作编辑；
• 无文件夹层级：只有扁平一篇篇笔记 + 标签 + 全文搜索，重度目录癖用户会不适应；
• 标签仅支持 ASCII 字符：标签识别正则为 [a-zA-Z0-9_-]+（源码实查），中文片段即使写成 #运维 也不会被识别为标签，只能靠全文搜索命中；
• Wikilink 按标题链接：重命名笔记标题后，指向它的 [[...]] 链接不会自动更新；
• 无官方移动 App：官方形态只有响应式 Web 界面；
• 官方仅提供 Docker 部署形态：无 systemd/包管理器安装路径，不用 Docker 的环境需要自行处理 Python 运行时。

七、同类选型对比

下表为 2026-10-30 通过 GitHub API 实查的同类自托管笔记/知识库组件量化对比（Stars 与最近推送日期为当日实查值）：

关键差异与如何选：

• 把「数据必须是裸 Markdown 文件」当硬要求 → flatnotes 与 SilverBullet 二选一：SilverBullet 功能更重（可编程、面向 power user），flatnotes 把「简单无干扰」做到底，学习成本几乎为零；
• 要多用户/多人使用 → flatnotes 直接出局（单用户），看 memos 或 Note Mark；
• 要层级目录/复杂知识树 → flatnotes 与 memos 都不合适，看 Trilium；
• 要端到端加密 → Standard Notes；
• 要最低资源占用 + 最低维护成本 → flatnotes：无数据库、单进程、索引可随时重建，是这组里运维面最小的。

八、参考链接

• 官方仓库：https://github.com/dullage/flatnotes
• Releases（版本发布记录）：https://github.com/dullage/flatnotes/releases
• 官方 Wiki（环境变量等细节文档）：https://github.com/dullage/flatnotes/wiki
• 在线演示站：https://demo.flatnotes.io
• 官方镜像：https://hub.docker.com/r/dullage/flatnotes
• 搜索引擎 Whoosh：https://whoosh.readthedocs.io/
• 编辑器 TOAST UI Editor：https://ui.toast.com/tui-editor

本系列其他篇章：

• 《flatnotes v5.5.5 Docker Compose 部署指南》
• 《flatnotes v5.5.5 配置参数详解》
• 《flatnotes v5.5.5 常用工具与 API 详解》