SilverBullet 介绍与选型指南

SilverBullet（v2.12.1，2026-10-28 溯源）纯服务器端可编程 Markdown 笔记应用的介绍与选型指南：space 即文件夹的核心理念、三层架构与 Space Lua/查询体系，以及与 Obsidian（LiveSync）/Trilium/Logseq 的量化选型对比。

SilverBulletSilverBullet知识库Docker2026/10/28

SilverBullet 介绍与选型指南

目标：面向「想在一台自己的服务器上托管一套 Markdown 笔记库」的读者，讲清 SilverBullet 是什么、核心理念是什么、和 Obsidian（LiveSync）/Trilium/Logseq 等常见知识库的定位差异，并给出量化的选型对比与适配场景判断。本文为认知篇，全部结论来自官方站点与官方文档联网溯源（查询日期 2026-10-28），未做本地部署实测；部署与命令实操见本专栏后续各篇。

一、环境信息

本文为联网溯源的认知篇，不依赖本地实验环境。为便于读者核对信息时效，溯源口径如下：

  • 软件版本：SilverBullet v2.12.1（GitHub Releases 最新稳定版，shields.io 徽章实查，2026-10-28）
  • 开源许可：MIT（官方文档站 SilverBullet.md 页明确「MIT-licensed SilverBullet Server」）
  • 代码仓库：github.com/silverbulletmd/silverbullet，社区星数 6.4k（shields.io 实查，2026-10-28）
  • 官网与文档：silverbullet.md（官网）/ docs.silverbullet.md（官方文档站）/ community.silverbullet.md（社区论坛）
  • 对比对象：Obsidian、Trilium（平台已有专栏）、Logseq 的定位信息同样来自各自官方站点/文档（2026-10-28 口径）

💡 说明：SilverBullet 自 2025 年的 v2 大版本起发生了架构级演进（配置体系从 SETTINGS 文件迁移到 CONFIG 页、引入多空间 Dashboard 等），网络上大量旧教程仍描述 v1 行为。本文以 v2.12.1 官方文档为准，涉及 v1→v2 差异处会明确标注。

二、软件概述

2.1 一句话定位

SilverBullet 官方对自己的定义是：一个「可编程的开源知识管理系统（Knowledge Management System）」，它把你的笔记、团队知识与产品文档保存为你完全拥有的 Markdown 文件。翻译成工程师的语言：它是一个「纯服务器端的 Markdown 笔记应用」——服务端只负责把一个文件夹（space）里的 .md 文件通过 HTTP 提供出来，浏览器客户端承担 90% 以上的编辑与索引逻辑。

官方文档在术语表中明确给出对标关系：SilverBullet 的 space（空间）就是 Obsidian 的 vault、Logseq 的 graph——而在实现上，它就是一个普通的文件夹，里面的每一页就是每一个 .md 文件。这个「文件夹即数据库」的设计是理解 SilverBullet 一切特性的钥匙：你可以随时用任何编辑器、任何脚本直接读写这些文件，备份就是复制目录，同步就是同步文件夹。

2.2 项目身世与现状

SilverBullet 由 Zef Hemel（SQLite 社区知名开发者，WASM SQLite 的早期推动者）创建并维护，采用 MIT 许可，以「单二进制 / 单容器」形态发布，支持 x86_64 与 ARM64（含树莓派）。项目自 2023 年公开发布以来持续高频迭代，2025 年完成 v2 大版本重写（Space Lua 成为核心扩展语言、引入多空间模式与 Dashboard），当前稳定版 v2.12.1（2026-10-28 实查），官方提供 GitHub Releases 下载与 GHCR/Docker Hub 镜像双通道。

官方文档站本身就是一个运行中的 SilverBullet 空间——「吃自己的狗粮」到了文档层面，这也侧面印证了其「文档即站点」的可编程能力。

2.3 与「云笔记」的本质区别

SilverBullet 不做云服务的「锁定」生意：没有私有账号体系依赖（自托管时账号就在你服务器上）、没有私有存储格式（全部是磁盘上的 Markdown）、没有订阅制（MIT 开源，官方托管仅是可选增值）。它的价值主张可以概括为三点：

  1. 文件所有权：notes are files，离开 SilverBullet 你依然拥有全部数据；
  2. 浏览器即客户端：任何设备打开浏览器就能用，PWA 安装后可离线工作；
  3. 可编程性：内置 Space Lua 语言、查询体系与模板体系，笔记库可以像软件一样被「开发」。

三、核心架构

3.1 三层架构

官方 Architecture 文档把 SilverBullet 划分为三层，理解这个分工对部署与排障都很关键：

层位置职责
Client（编辑器）每个浏览器标签页一个实例承担 90%+ 逻辑：编辑器、Space Lua 解释执行、索引（datastore）、插件、查询渲染
Service Worker每个浏览器一个实例离线缓存与客户端-服务端同步引擎
Server服务器上的单进程身份认证、托管客户端静态资源、提供文件 CRUD 的 HTTP API——本质上是个「聪明的文件服务器」

这个架构带来两个直接推论：

  • 服务端资源占用极低：官方 Install 文档明确「几百 MB 内存即可，树莓派都能跑」，因为重活（索引、Lua、渲染）都在浏览器端完成；
  • 「多端」由服务端形态保证：所有设备通过浏览器访问同一个服务端 space，天然解决多端同步问题——这与 Obsidian（本地优先，多端需依赖 Sync 付费服务或社区 LiveSync 方案）形成鲜明的定位差异。

3.2 数据模型：space = 文件夹，page = 文件

  • Space（空间）：顶层文件夹，至少包含一个 index 页（index.md）和一个 CONFIG 配置页（CONFIG.md）；
  • Page（页面）：一个 .md 文件，页面名与路径一一对应（Projects/Launch 页即 Projects/Launch.md 文件）；
  • Document（附件文档）：非 Markdown 的任意文件（PNG/PDF 等），同样按路径存放；
  • 元数据：页面支持 YAML frontmatter 与 #tag 行内标签，由客户端索引后可供查询。

3.3 可编程内核：Space Lua 与查询体系

v2 把一门完整的 Lua 方言（Space Lua）作为内建脚本语言：页面里的 ```space-lua 代码块会被执行，${expression} 占位符可以动态渲染内容；配合 Integrated Query（类 SQL 的 query[[from ... where ... select ...]] 语法）与模板函数（templates.pageItem 等），可以在页面里实现任务看板、动态目录、数据视图等「笔记库编程」。这是 SilverBullet 相对多数 Markdown 笔记应用最大的差异化能力，也是它自称「programmable」的底气。

3.4 服务端 HTTP API

服务端对外暴露一套精简的 HTTP API（官方 HTTP API 文档）：/.fs 前缀提供空间文件读写（GET/PUT/DELETE，带 ETag 条件写防覆盖）、/.auth 处理登录、/.search/query 提供全文搜索（支持语义搜索模式）、/.ping 健康检查。官方甚至提供了配套的 sb 命令行客户端直接消费这套 API——意味着笔记库完全可以被脚本和自动化工具驱动，而不仅仅是人肉编辑。

四、功能特性

综合官方文档站的特性页与术语表，SilverBullet 的功能清单如下：

  • 纯 Markdown 编辑：所见即所得风格编辑器 + 源码模式，支持 YAML frontmatter；
  • 双向链接与提及：[[wiki 链接]]、Linked Mentions、Linked Tasks、锚点；
  • 任务管理：任务即复选框列表，带 done 状态、截止日期（📅 emoji 语法）、标签，可被查询聚合；
  • 标签体系：行内 #tag 与 frontmatter 标签，支持自定义 tag schema（用 Lua 定义字段校验）；
  • 全文搜索 + 语义搜索：服务器端搜索支持 words/phrase/semantic 三种模式，语义搜索可选嵌入模型（granite-embedding-97m-multilingual-r2 约 220 MB 或 multilingual-e5-small 约 488 MB）；
  • 模板体系：Slash Templates（斜杠命令插入模板）、Page Templates（页面模板）、查询结果模板渲染；
  • Space Lua 编程：页面内 Lua 代码块、命令扩展、UI 扩展（装饰、按钮、视图）、事件系统；
  • 插件（Plugs）与 Library：官方标准库 Library（页面、模板、Lua 函数集）与社区插件分发机制；
  • 离线优先（PWA）：HTTPS 部署下可安装为 PWA，全量同步到浏览器本地，离线可编辑、联网后自动同步（支持 ETag 条件写与冲突处理）；
  • 多空间模式（v2 新增）：一台服务器托管多个 space，Dashboard 管理账号与访问级别（none/read/write），支持 OIDC 单点登录（Google Workspace、Pocket ID 等）；
  • 客户端加密：认证开启时可选端侧加密（浏览器本地数据加密存储）；
  • HTTP API 与 sb CLI：文件 CRUD、搜索、Lua 求值均可通过 API/CLI 自动化。

💡 技术拓展：「双链笔记」生态里的查询方案不止一种——Obsidian 用 Dataview 插件（DQL 查询语言）或 DataviewJS；Logseq 用内建 Datalog 查询；Trilium 用脚本 API + 收集器；SilverBullet 则把查询直接做成了 Space Lua 的Integrated Query 语法，且查询在客户端本地索引（datastore）上执行、服务端零负载。四者思路一致（「把笔记当数据库查」），但 SilverBullet 的查询与编程语言（Lua）是同一套体系，学习成本集中在一处。

五、快速开始（最小可用示例）

本文为认知篇，不重复部署细节（那是后续篇章的任务），这里只给「最小心智模型」帮助理解产品形态。官方推荐的 Docker Compose 编排（摘自官方 docs.silverbullet.md 的 Install/Docker 页，2026-10-28 版本）核心是三件事：

  1. 镜像 ghcr.io/silverbulletmd/silverbullet（:latest 跟随最新稳定版，-slim 后缀为不含 Chromium 的精简变体）；
  2. 把宿主一个目录挂载为容器内 /data（数据根目录）；
  3. 服务监听 3000 端口，浏览器打开即用。

首次启动：全新空数据目录会进入多空间模式的 Dashboard 引导（创建管理员账号与首个空间）；若把一个已有页面的文件夹直接作为空间启动，则按经典单空间模式立即对外服务（可用 SB_USER=用户名:密码 环境变量开启登录认证）。

完整的 Compose 编排、环境变量、HTTPS 前置要求与逐步验证，见本专栏部署篇；参数体系详见配置篇；HTTP API 与备份运维见命令运维篇。

六、适用场景与限制

6.1 适合的场景

  • 个人多端知识库：手机/平板/办公电脑/家用电脑全部浏览器访问同一服务端，天然同步，PWA 离线兜底；
  • 团队/产品文档站：多空间模式 + 账号访问级别 + OIDC SSO，可作为轻量内部文档/Wiki；
  • 工程师的「可编程笔记」：用 Lua 与查询把笔记库做成任务管理、读书卡片、项目管理工具；
  • 自动化驱动的笔记库：HTTP API + sb CLI 让脚本、cron、AI Agent 直接读写笔记（这恰好是 G22 文档处理场景的独特优势）；
  • 低配设备自托管：树莓派级硬件即可承载（官方明示）。

6.2 限制与不适合的场景

  • 强协作编辑缺失：无多人实时协同编辑（Google Docs 式）；官方 Collaboration 机制基于文件级冲突检测与合并，重度多人同页编辑不是设计目标；
  • 离线特性依赖 HTTPS：PWA/Service Worker/离线同步/端侧加密是浏览器「安全上下文」能力，纯 HTTP 局域网部署会降级为「仅在线模式」（官方 TLS 页明确列出限制清单）；
  • 大小写敏感要求：官方强烈建议部署在大小写敏感的文件系统上（Linux 原生；macOS APFS 与 Windows NTFS 默认大小写不敏感，官方明确「不推荐」作为服务端系统）；
  • NAS/网络文件系统需谨慎：官方指出 space 目录若放在 NFS/SMB 挂载上，mtime 语义不可靠会影响同步引擎，需改用轮询监听（SB_FS_WATCH=poll）；
  • SQLite 数据库用户注意：SilverBullet 不用数据库，检索能力依赖客户端索引；若需要服务端重检索/全文聚合分析，应选 Trilium 或专用知识库。

6.3 部署形态小结

形态说明适用
Server（本专栏主线）单二进制或官方镜像部署，浏览器/PWA 访问自托管主力形态
Desktop桌面应用（Electron 形态），个人/教育用途免费本地单机使用，可与 Server 同步
Hosted官方托管服务（silverbullet.md/hosting）不想运维服务器者

七、同类选型对比

7.1 量化对比表

对比口径：官方站点/文档（2026-10-28 实查）；星数为 shields.io 徽章值。四款均为「知识/笔记管理」方向的知名开源方案，但定位差异显著。

维度SilverBullet v2.12.1Obsidian（+Sync/LiveSync）Trilium（平台专栏实测 v0.106.0）Logseq
开源许可MIT（全开源）个人免费闭源，商业需付费AGPL-3.0AGPL-3.0
客户端形态纯浏览器/PWA（零安装）桌面/移动原生应用桌面应用 + 内建 Web/同步服务端桌面/移动应用
数据存储纯 Markdown 文件（文件夹即库）本地 Markdown 库（vault）自有 SQLite 层级文档模型（可导出 Markdown）本地 Markdown + 本地 SQLite 索引
多端同步服务端即中心，天然多端官方 Sync 订阅制；自托管需 CouchDB + LiveSync 插件（第三方）内建同步服务端（自托管）无官方同步（靠第三方网盘/Syncthing）
服务端资源占用极低（官方：几百 MB 内存、树莓派可用）无服务端（LiveSync 方案需额外跑 CouchDB）中等（需 Node.js 进程 + SQLite）无服务端
可编程性Space Lua 内建 + 查询一体化Dataview/Templater 等社区插件内建 Script API（JS）+ 导出Datalog 查询 + 插件
协作文件级冲突合并（非实时协同）无有限（单用户设计为主）无
离线能力PWA 全量离线（需 HTTPS）原生离线桌面端原生离线原生离线
社区星数（shields.io，2026-10-28）6.4k闭源（官方仓库仅 issues，不适用）39k（TriliumNext/Trilium）45k
中文友好度界面英文为主，中文内容无障碍完善良好良好

关键差异解读：这张表的核心分野在「多端访问的实现方式」——SilverBullet 把浏览器当唯一客户端、服务端当唯一数据源，多端是架构赠品；Obsidian 是本地优先的极致单机体验，多端要么花钱（官方 Sync）、要么自己搭 CouchDB 跑 LiveSync（社区方案，运维复杂度高）；Trilium 是「有数据库思维」的层级笔记，服务端同步内建但客户端仍需安装；Logseq 则完全本地，同步交给外部工具。

7.2 选型建议（如果……则……）

  • 如果你要「一台服务器 + 所有设备浏览器直接访问 + 数据必须是纯 Markdown 文件」→ SilverBullet 是最直接的对口答案；
  • 如果你是重离线、重本地插件生态的深度单机用户，能接受 Sync 订阅或自建 CouchDB → Obsidian；
  • 如果你需要层级化笔记树 + 脚本自动化 + 富结构（属性、关系）而非纯文件夹 → Trilium（本平台有完整实测专栏）；
  • 如果你的笔记以大纲/日记流为主、习惯 block 级操作 → Logseq；
  • 如果你需要多人实时协同 Wiki → 以上皆非，看 Outline/BookStack 类产品（超出本文对比范围）。

八、参考链接