SiYuan 3.8.8 介绍与选型指南

目标：面向正在做「个人/团队知识管理工具」选型的读者，系统介绍 SiYuan（思源笔记）的定位、架构、功能与同类横向对比。本篇为认知与选型篇，全部信息通过官方站点、官方仓库与官方文档联网溯源取得，逐条标注来源与查询日期，不包含本地实测结论。部署、配置与命令的实操内容分别见《SiYuan 3.8.8 Docker Compose 部署指南》《SiYuan 3.8.8 配置参数详解》《SiYuan 3.8.8 常用 CLI 命令与工具详解》。

一、环境信息

本篇是纯联网溯源的认知篇，先交代取证环境与来源清单，便于读者复核每一条结论。

• 溯源日期：2026-10-22
• 溯源方式：官方 GitHub 仓库（siyuan-note/siyuan）README 与 docs/API.md、GitHub Releases Atom 订阅源、shields.io 徽章 JSON 接口（星数与版本取证）、各对比项目仓库 LICENSE 文件
• 版本基准：官方最新稳定版 v3.8.8（来源：shields.io https://img.shields.io/github/v/release/siyuan-note/siyuan.json，查询日期 2026-10-22，返回 {"message":"v3.8.8"}）
• 星数基准：GitHub 星数一律通过 shields.io 徽章接口取证（如 https://img.shields.io/github/stars/siyuan-note/siyuan.json 返回 {"message":"47k"}），未直连 api.github.com
• 说明：本篇不包含任何本地实测结论；文中的启动命令均摘自官方 README，仅作认知演示

二、软件概述

2.1 它是什么

SiYuan（中文名「思源笔记」）是一个「隐私优先」的个人知识管理系统，核心卖点是块级（block-level）粒度的引用与双向链接，以及 Markdown 所见即所得编辑。

💡 技术拓展：双链笔记工具的「链接粒度」并不相同，选型时值得横向对比——

链接粒度	代表工具	特点	适用场景
块级（段落/列表项级）	SiYuan、Roam Research	引用可以精确到任意一个块，粒度最细	卡片式写作、深度知识网络
文件级（整篇文档）	Obsidian	链接指向整个 Markdown 文件，简单直观	文档库管理、文件生态
大纲条目级	Logseq	以大纲条目为最小单位，与块级接近	日志式、大纲式记录

SiYuan 属于「块级」阵营：官方 README 对它的第一句定义就是「supporting fine-grained block-level reference and Markdown WYSIWYG」（来源：官方仓库 README，查询日期 2026-10-22）。

关键身份信息一览（来源：官方仓库 README 与官方下载页 b3log.org/siyuan/en/download.html，查询日期 2026-10-22）：

2.2 版本节奏

从官方 GitHub Releases Atom 订阅源（https://github.com/siyuan-note/siyuan/releases.atom，查询日期 2026-10-22）实查可见，官方采用 alpha → beta → stable 三阶段滚动发布：在 v3.8.8 正式版发布之后，订阅源中已经出现 v3.8.9-alpha.1 ~ v3.8.9-alpha.3、v3.8.8-beta.1 ~ v3.8.8-beta.4 等一系列预发布版本。官方 README 的 Test Channels 一节说明，用户可在「Settings - About - Update channel」中切换 Beta 或 Alpha 渠道获取预发布版本。

对生产部署的建议：跟随 stable 版本（本批次基准 v3.8.8），Beta/Alpha 渠道仅用于尝鲜测试；Docker 部署时的升级与版本管理见《SiYuan 3.8.8 Docker Compose 部署指南》。

三、核心架构

3.1 技术栈与组件形态

SiYuan 采用「Go 内核 + 前端界面」的分层结构。整个程序在服务端形态下位于 /opt/siyuan/ 目录（官方 README 的 Docker Hosting 一节描述）：

• appearance：图标、主题、语言包
• guide：用户指南文档
• stage：界面与静态资源
• kernel：内核程序（Go 编写，名为 SiYuan-Kernel）

内核内嵌 HTTP 服务（默认端口 6806）同时服务 Web 界面与 Kernel HTTP API；移动端与桌面端则把内核嵌入本机进程。官方 README 的 Command-line Interface 一节还说明：CLI 的载体就是内核二进制本身——「The CLI binary is <install-dir>/resources/kernel/SiYuan-Kernel, invoked via the siyuan command」，即同一个内核程序既可 serve 起 HTTP 服务，也可以作为离线 CLI 直接读写工作区数据。

3.2 官方生态项目

官方 README「Architecture and Ecosystem」一节列出的生态项目如下（来源：官方仓库 README，查询日期 2026-10-22）：

解读：与多数「单仓库」笔记应用不同，SiYuan 把编辑引擎（lute）、同步引擎（dejavu）、插件系统（petal）拆成了独立开源项目，内核通过清晰的边界组合它们；对二次开发者而言，插件开发走 petal API，主题/模板/插件分发走 bazaar 集市。

3.3 数据存储模型

官方 README FAQ「How does SiYuan store data?」一节明确（来源：官方仓库 README，查询日期 2026-10-22）：数据保存在工作区的 data 文件夹——

• assets：所有插入的资源文件
• emojis：表情图片
• snippets：代码片段
• storage：查询条件、布局、闪卡等
• templates：模板片段
• widgets：挂件
• plugins：插件
• public：公开数据
• 其余文件夹为用户创建的笔记本文件夹，其中以 .sy 为后缀的文件保存文档数据，数据格式为 JSON

💡 技术拓展：知识管理工具的「落盘格式」主要有三类——

落盘格式	代表	优点	缺点
纯 Markdown 文本	Obsidian、Logseq	任何编辑器可读、可被 Git 等工具直接管理	块级属性/数据库等高级结构表达受限
SQLite 等数据库	Joplin（本地库）、Trilium	查询快、事务一致	不便直接文本化阅读与迁移
JSON 块文件	SiYuan（.sy 文件）	块级元数据完整、程序处理方便	裸读不如 Markdown 直观

SiYuan 选择第三类：文档以 .sy（JSON）保存，同时提供标准 Markdown 导出与 siyuan:// 协议。官方 FAQ 同时强调：不支持通过第三方同步盘同步数据目录，否则可能损坏数据。

四、功能特性

官方 README「Features」一节列出的功能全景如下（来源：官方仓库 README，查询日期 2026-10-22；官方注明「Most features are free, even for commercial use」，部分功能仅限付费会员，详见官方 Pricing 页）：

解读四条主线能力：

1. 块级知识网络：块引用 + 双向链接 + SQL 查询嵌入构成 SiYuan 的差异化核心，适合把笔记当作「数据库」来用（官方内置的 Database 表格视图进一步强化了这一方向）。
2. 编辑体验：所见即所得与块式操作结合，导出链路（Markdown/PDF/Word/HTML、公众号/知乎/语雀）覆盖了中文内容创作者的高频发布场景。
3. 多端与同步：官方云同步为会员特权；自托管场景则通过 Docker 部署 Web 端实现服务器化使用（详见《SiYuan 3.8.8 Docker Compose 部署指南》）。
4. 开放性：Kernel HTTP API（Authorization: Token xxx 鉴权）+ 内置 CLI + 插件集市，三类扩展通道并存，适合自动化与二次开发（详见《SiYuan 3.8.8 常用 CLI 命令与工具详解》）。

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

以下示例均摘自官方 README（查询日期 2026-10-22），按「桌面端」「服务端」两条路径给出最小可用形态。命令的真实可执行验证与逐参数讲解在部署篇完成，本篇仅作官方形态认知。

5.1 桌面端（个人首选）

官方建议「桌面与移动端优先通过应用市场安装，以便一键升级」。应用市场入口：

• 移动端：App Store、Google Play、F-Droid
• 桌面端：Microsoft Store
• 安装包：官方下载页 b3log.org/siyuan/en/download.html 与 GitHub Releases
• 包管理器：repology 徽章显示 siyuan / siyuan-note 两个包名已在多个发行版仓库收录

5.2 服务端（Docker，官方推荐的服务器形态）

官方 README「Docker Hosting」给出的标准启动命令（摘录自官方 README，查询日期 2026-10-22）：

docker run -d \
  -v /siyuan/workspace:/siyuan/workspace \
  -p 6806:6806 \
  -e PUID=1001 -e PGID=1002 \
  b3log/siyuan \
  serve \
  --workspace=/siyuan/workspace/ \
  --accessAuthCode=xxx

要点（均出自官方 README）：

• 镜像名为 b3log/siyuan，入口为 /opt/siyuan/entrypoint.sh，可通过 PUID/PGID 环境变量控制容器内运行用户以解决挂载目录权限问题
• 自 v3.7.0 起，必须显式传入 serve 子命令（如 docker run b3log/siyuan serve --workspace=...），可通过 docker run --rm b3log/siyuan serve --help 查看全部服务参数
• --workspace 指定工作区路径，--accessAuthCode 指定锁屏密码（官方强调务必修改，否则任何人都能访问数据）
• 工作区路径建议宿主机与容器内保持一致，减少权限与路径映射的心智负担

Compose 形态的官方示例、端口/持久化/鉴权的完整落地、升级与运维，见《SiYuan 3.8.8 Docker Compose 部署指南》；启动参数的逐项含义与实测行为，见《SiYuan 3.8.8 配置参数详解》。

六、适用场景与限制

6.1 适用场景

结合官方定位与功能清单，SiYuan 的高价值场景包括：

1. 个人长期知识库：块级引用/双链 + 本地 JSON 落盘 + 间隔重复，适合构建可积累、可检索的个人知识网络。
2. 中文写作与发布：公众号/知乎/语雀一键复制导出、PDF/Word 导出，内容创作链路完整。
3. 自托管 Web 知识库：AGPL-3.0 完全开源 + 官方 Docker 镜像，可在自有服务器上跑起浏览器版；Kernel HTTP API 与 CLI 支持自动化集成。
4. 多端记录：桌面/移动 App 与 Web 端共存，配合官方云同步（会员）实现跨端。

6.2 已知限制

官方 README「Docker Hosting」的 Limitations 一节明确的服务器形态限制（来源：官方仓库 README，查询日期 2026-10-22）：

• 不支持桌面与移动应用连接服务器，仅支持浏览器访问
• 服务端形态不支持导出 PDF、HTML、Word
• 服务端形态不支持导入 Markdown 文件

此外官方 FAQ 明确：不支持第三方同步盘同步数据目录（否则可能损坏数据）；部分高级功能（如官方云同步）为付费会员特权。这些限制直接决定了部署篇的技术选型与运维姿势，务必在动手前通读《SiYuan 3.8.8 Docker Compose 部署指南》与《SiYuan 3.8.8 配置参数详解》。

七、同类选型对比

7.1 量化对比总表

星数一律通过 shields.io 徽章接口取证（URL 形如 https://img.shields.io/github/stars/<owner>/<repo>.json，查询日期 2026-10-22，返回值照抄）；协议一律取证自各仓库 LICENSE 文件或仓库许可徽章（查询日期 2026-10-22）。

⚠️ 取证口径说明：Obsidian 为闭源商业产品，obsidianmd/obsidian-releases 是其官方发布/社区插件仓库而非源码仓库，星数仅作社区规模参考；Notion 无公开源码仓库，无法以星数量化；AFFiNE 的 LICENSE 主体为 MIT，但 packages/backend/packages/common/native 目录按其专项许可执行（取证自仓库 LICENSE 文件）。

7.2 关键差异解读与选型建议

对上表做三个维度的解读：

1. 「数据主权 + 服务端」维度：若要求「数据完全落在本机/自有服务器，且提供 Web 服务端」，候选收敛为 SiYuan、Joplin（Joplin Server）、Trilium、Outline、AppFlowy/AFFiNE；Obsidian 与 Logseq 没有官方自托管服务端，多端同步要么走官方付费云，要么借助第三方盘（Logseq 本质靠文件同步）。SiYuan 的独特之处是官方维护 Docker 镜像且内核内置 HTTP API 与 CLI，自动化空间大。
2. 「结构化知识网络」维度：块级双链（SiYuan）与文件级双链（Obsidian）是两种心智模型——重「卡片、引用、数据库化」选 SiYuan；重「纯文本 Markdown 文件 + 最大插件生态」选 Obsidian；重「大纲与日记流」选 Logseq。SiYuan 落盘为 .sy JSON，换取了块级元数据能力，代价是裸文件不如 Markdown 直观（但保留标准 Markdown 导出）。
3. 「Notion 替代」维度：Notion 本体闭源且不可自托管。若主要想要 Notion 的「块编辑 + 数据库视图 + 协作」，AppFlowy（AGPL-3.0，78k 星）与 AFFiNE（MIT 主体，74k 星）是功能对位替代；若要的是「团队 Wiki/文档站」，Outline（BSL 1.1，41k 星）更合适；若是「个人深度知识管理 + 隐私优先」，SiYuan 的块级双链 + 自托管 Web 端组合差异化更强。

一句话选型：个人/小团队要「自托管 + 块级双链 + 中文写作链路」→ SiYuan；要「纯文本文件 + 插件生态」→ Obsidian；要「大纲流」→ Logseq；要「Notion 桌面对位」→ AppFlowy/AFFiNE；要「团队 Wiki」→ Outline。确定选型后，从《SiYuan 3.8.8 Docker Compose 部署指南》开始落地。

八、参考链接

1. 官方网站与下载：https://b3log.org/siyuan/en/download.html （查询日期 2026-10-22）
2. 官方 GitHub 仓库（内核与界面）：https://github.com/siyuan-note/siyuan （查询日期 2026-10-22）
3. 官方英文用户指南：https://siyuan-en.b3log.org/ （来源：README 链接，查询日期 2026-10-22）
4. 官方 Kernel HTTP API 文档：https://github.com/siyuan-note/siyuan/blob/master/docs/API.md （查询日期 2026-10-22）
5. 官方 Releases：https://github.com/siyuan-note/siyuan/releases （查询日期 2026-10-22，最新稳定版 v3.8.8）
6. 版本徽章取证接口：https://img.shields.io/github/v/release/siyuan-note/siyuan.json （查询日期 2026-10-22）
7. 星数徽章取证接口：https://img.shields.io/github/stars/siyuan-note/siyuan.json （查询日期 2026-10-22）
8. 官方定价页：https://b3log.org/siyuan/en/pricing.html （来源：README 链接，查询日期 2026-10-22）
9. 社区论坛：https://liuyun.io （来源：README 链接，查询日期 2026-10-22）
10. Awesome SiYuan（生态汇总）：https://github.com/siyuan-note/awesome （来源：README 链接，查询日期 2026-10-22）