思源笔记完整实战指南：从首次启动到自托管只要 10 分钟，外加 5 条避坑建议-平芜编程栈

思源笔记完整实战指南：从首次启动到自托管只要 10 分钟，外加 5 条避坑建议

【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间，让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan

思源笔记（SiYuan）是一款开源、隐私优先、可自托管的知识工作空间。它的核心能力可以概括为四件事：块级编辑让内容可以像积木一样复用，双向链接自动编织出知识网络，本地优先的存储方式让你完全掌握自己的数据，再配上数据库视图、REST API 和 MCP 接口，还能让 AI 智能体直接参与知识生产。如果你受够了"笔记散落在各个工具、导出就变味"的处境，这篇文章按"选型 → 上手 → 深入 → 部署 → 避坑"的顺序，带你把思源笔记真正用起来。

三栏布局：左侧文档树、中间编辑区、右侧图谱面板，右侧手机示意移动端同一套体验

为什么选它：三个别的笔记工具没做到的地方

在装之前先想清楚它凭什么值得换。我的判断依据有三条：

第一，数据格式是纯本地文件。你的笔记就是一台机器上的普通文件夹：文档是.sy文件，资源在assets/下，配置和工作空间说明在仓库的工作空间文档里写得很清楚。这意味着最坏情况下你丢的只是一台电脑的数据，而不是"某个云服务的账户权限"。

第二，组织单位是"块"而不是"文件"。传统工具里你只能在文档级别移动内容，思源里每个段落、标题、列表项都是一个独立的内容块，可以被引用、嵌入、拖拽到别的文档。写作到后期，70% 的内容其实是从旧笔记里"借"来的，而不是重新敲的。

第三，知识之间的连接是自动维护的。双向链接和图谱视图让你不用手动维护"哪篇笔记引用了哪篇"，链接多了以后，图谱本身就是你知识体系的导航图。

思源笔记入门：第一次启动的完整流程

安装本身没有门槛，按你的习惯三选一：

桌面端：官网提供 Windows / macOS / Linux 安装程序，双击安装即可；Android、iOS、HarmonyOS 也都有对应客户端，体验基本一致。
自托管：Docker 一行命令跑起来，详见下文部署章节。
源码构建（给开发者）：克隆https://gitcode.com/GitHub_Trending/si/siyuan，用 pnpm 装依赖后执行开发脚本即可启动，前端是 TypeScript，后端内核是 Go，代码分别在app/src/和 kernel/ 目录。

首次启动后你会看到一个预置的"思源用户指南"笔记本，它本身就是最好的教程——仓库里的用户指南与它同源。跟着做三件事就算入门：

新建一个笔记本，再在里面建第一篇文档；
在编辑器里输入/，会弹出功能菜单，段落、标题、任务列表、代码块等块类型都在这里，想换成什么块就选什么；
用全局快速搜索（截图里/k可切换结果）验证一下全文索引是否工作，输入关键词就能看到命中块和所在文档。

快速搜索面板：243 个命中分布在 31 个文档里，回车即可定位

到这里，你有了一个能写、能搜、数据在自己手里的工具。真正让它和备忘录拉开差距的，是下面这些"深入"能力。

用深之后：让知识开始流动的三种方式

块引用：把笔记变成可复用的零件

在编辑器里输入[[会弹出块引用菜单：你可以选一个块"钉"在当前段落，也可以选择直接嵌入原文。区别在于——钉住后，被引用块在别处修改，这里自动跟着更新；嵌入则是复制一份内容快照。

适合的场景：论文写作时把"结论"块钉进多篇草稿，改一次结论，所有草稿同步；或者把一段常用代码说明钉进项目文档，避免复制粘贴导致版本漂移。

双向链接与图谱：知识网络自动生长

块引用天然产生"反链"：任何被引用的块，都会出现在引用方文档的反链面板里，反过来也一样。链接密度上来之后，打开右侧的图谱视图，节点就是块、连线就是引用关系，哪个概念是枢纽、哪片知识是孤岛，一眼就能看穿。

图谱视图：中心节点是被引用最多的块，蓝色/红色连线区分引用方向，可配合节点大小、碰撞半径等参数调节

数据库视图：表格、看板、画廊三种打开方式

思源的数据库不是 Excel 那种死表格，而是"对一批文档的字段做结构化查询"，同一份数据可以在三种布局间切换：

表格视图：整理文献库、书单、项目清单，支持排序和条件筛选；
看板视图：项目管理用，拖拽卡片改变状态，任务流一目了然；
画廊视图：管理带封面图的内容（书、文章、素材），卡片式展示最直观。

同一个 Books 数据库：上半部分是表格视图（含按作者分组的作品计数），下半部分是画廊视图

顺带一提：把笔记变成间隔复习的闪卡

选中任意块可以生成闪卡，按"1 分钟 / 5 分钟 / 10 分钟 / 5 天"的节奏复习，间隔重复算法来自内置的 Riff 模块。适合用同一套笔记既做研究又备考的人——写的时候就顺手把考点抽出来。

部署与扩展：自托管、插件和 AI 智能体

自托管部署：桌面端之外的第二种活法

团队共用一台服务器、或者想在树莓派上放个"私人知识库"，用 Docker 是最省事的。最小可用配置：

docker run -it --rm \ -e SIYUAN_WORKSPACE_PATH=/siyuan/workspace \ -e SIYUAN_ACCESS_AUTH_CODE=换成你自己的访问码 \ -v ./workspace:/siyuan/workspace \ -p 6806:6806 \ b3log/siyuan:latest

这段命令做了三件事：设置工作空间路径、强制一个访问验证码（不设置的话服务等于裸奔）、把数据目录挂到宿主机方便备份。镜像构建细节可以直接看仓库根目录的 Dockerfile。部署后浏览器访问 6806 端口即可使用。

插件与 API：两种扩展姿势

插件：社区集市（Bazaar）里有现成的插件可一键安装，插件运行时在 plugin 子系统里以沙箱方式运行，写插件等于给 Web 前端加一段 JS。
Kernel API：所有界面操作背后都是 REST 接口，API 文档列得齐全。拿 Python 列一下笔记本，大概长这样：

import requests host = "http://127.0.0.1:6806" headers = {"Authorization": "Token 你的Token"} # 列出全部笔记本，返回 JSON r = requests.post(f"{host}/api/notebook/listNotebooks", headers=headers, json={}) print(r.json()["data"])

Token 在设置页生成。这个接口的价值在于：你可以写脚本定时备份、批量导入、做自动化工作流，而不需要人在界面里点点点。

让 AI 智能体成为同事

这个项目比较特别的一点：内核自带 agent 会话和 MCP 服务，可以把"读笔记、搜块、建文档"这些能力以 MCP 工具的形式暴露给外部 AI 客户端。也就是说，AI 不是只能读你导出出来的 Markdown，而是能直接在工作空间里读写。配合 API 做二次开发，"人写框架、智能体补细节、结果落回笔记"的闭环是真实可跑的。

思源笔记长期使用：5 条避坑建议

用了一段时间后，下面这几条是我最想告诉新手的：

备份要连"数据目录"一起备份。工作空间里的.sy文件是内容，但data/下还有索引和数据库快照。只拷文档目录，搜索索引和块关系会丢失。
善用数据历史，手滑不慌。思源每 10 分钟（可配置）自动给改动的文档生成历史快照，删除、清理资源前也会留档，误删可以回滚——这块机制在数据历史指南里有详细说明。

数据历史页：左侧是文档树中的历史说明，右侧正文解释 history 目录规则与各类后缀（-update/-delete/-sync 等）

服务器部署必须设访问验证码。这一点在 Docker 章节已经强调，再重复一次：不设等于把整个知识库公开。
别在一个笔记本里堆几千篇文档。按主题拆笔记本、归档老内容，检索和图谱都会更清爽；单个文档也别写成上万块。
加密笔记本想清楚再开。开启加密后，文本以密文落盘，丢了恢复口令就真丢了；而且加密块在全文搜索里的表现和明文不同。建议只给敏感笔记本单独开，详见加密笔记本说明。