1. 思源笔记一个本地优先、块级引用的知识管理新范式如果你和我一样在知识管理的道路上尝试过 Evernote、Notion、Obsidian 等一系列工具最终却总感觉有些地方“差一口气”——要么是数据被锁在云端心里不踏实要么是编辑体验不够流畅打断思路再或者是双链、引用功能做得不够彻底难以构建真正的知识网络——那么思源笔记SiYuan的出现很可能就是那个让你眼前一亮的答案。思源笔记是一款隐私优先、本地优先的个人知识管理系统。它的核心设计哲学是“重构你的思维”这不仅仅是一句口号而是通过其块级Block引用和所见即所得的 Markdown 编辑器来实现的。简单来说它把 Notion 的块编辑体验、Obsidian 的双向链接网络、以及传统 Markdown 编辑器的简洁高效结合成了一个以你的数据安全为第一要务的本地应用。这意味着你的所有笔记、图片、附件都首先存储在你自己的电脑硬盘上你可以完全掌控它们无需担心服务商倒闭或政策变动导致的数据风险。同时它又通过精心设计的同步机制让你能在多设备间安全地协作。我第一次接触思源是因为受够了某些在线笔记工具偶尔的网络延迟和格式兼容性问题。我需要一个能让我心无旁骛写作又能轻松建立知识关联的工具。思源的“块”概念让我印象深刻在思源里每一个段落、列表项、标题甚至一个代码块都是一个独立的“块”。你可以像乐高积木一样任意拖动、引用、嵌入这些块。这种细粒度的内容组织方式彻底改变了我的笔记习惯让知识的复用和连接变得前所未有的简单。接下来我将结合自己深度使用一年多的经验为你详细拆解思源的架构、核心功能、部署方案以及那些官方文档里不会写的实操心得和避坑指南。2. 核心架构与设计哲学解析2.1 为什么是“本地优先”与“块级引用”在云服务无处不在的今天“本地优先”听起来有些复古但这恰恰是思源笔记最核心的竞争力也是其设计哲学的基石。所谓“本地优先”是指应用运行时产生的所有数据都首先被写入你设备上的本地文件系统。思源的工作空间Workspace就是一个普通的文件夹里面以.sy为扩展名的 JSON 文件存储着你的笔记内容assets文件夹存放着所有插入的图片、附件。这种设计带来了几个关键优势首先是绝对的隐私和数据主权。你的笔记从未未经加密就离开你的设备。思源提供的云端同步服务需会员是端到端加密的但即使你不使用官方同步仅通过本地备份或自己熟悉的网盘如 Dropbox、iCloud Drive 的文件夹同步功能来同步工作空间文件夹也能实现多设备间的数据流转。当然官方强烈不建议直接使用第三方同步盘如坚果云、百度云盘的同步文件夹进行实时同步因为这可能因文件冲突导致数据损坏。正确的做法是手动导出数据包.sy.zip进行迁移或使用其提供的端到端加密同步。其次是极致的响应速度和离线可用性。所有操作都在本地完成没有任何网络请求的延迟。无论你是输入文字、插入图片还是进行复杂的块引用体验都如桌面软件般流畅。这对于需要专注写作或在不稳定网络环境下工作的人来说至关重要。“块级引用”则是组织思维的革命。传统的笔记引用通常以“文档”或“页面”为单位粒度太粗。而在思源中最小的内容单元是“块”。你可以将某个段落、某个列表项单独引用到另一篇笔记中。被引用的块会形成一个“反向链接”面板清晰地展示所有引用它的上下文。这种设计使得知识不再是孤立的岛屿而是形成了高度互联的网络。当你修改源块时所有引用处的内容都会同步更新除非你选择嵌入为静态快照这保证了知识网络的一致性。2.2 技术栈与生态系统一览思源笔记的技术选型体现了其追求高性能和跨平台的目标。其桌面端基于Electron框架这使得它能够用 Web 技术HTML, CSS, JavaScript开发同时获得原生应用的体验并轻松支持 Windows、macOS 和 Linux。移动端Android/iOS/HarmonyOS则是各自平台的原生开发以保障移动设备的性能和体验。它的核心编辑器引擎是一个名为Lute的独立项目这是一个用 Go 语言编写的高性能 Markdown 渲染引擎。Lute 不仅负责将 Markdown 解析为 HTML更实现了思源独有的“所见即所得”编辑体验——你输入 Markdown 语法如**加粗**它会实时渲染为加粗样式但背后依然保留着纯文本的 Markdown 源格式。这种设计兼顾了纯文本爱好者的操控感和普通用户的视觉友好性。整个思源的生态系统是模块化且开源的内核 (Kernel)用 Go 编写负责数据存储、索引、查询和同步等底层服务。前端 (Frontend)基于 Vue.js 的 Web 界面提供了我们日常交互的编辑器、设置面板等。移动端独立的 Android、iOS 项目。社区集市 (Bazaar)一个插件、主题、模板的共享平台允许用户扩展思源的功能。数据仓库 (Dejavu)负责版本历史和快照管理类似于一个简化的 Git 系统用于数据同步和恢复。这种架构分离的好处是清晰的职责划分和可维护性。作为用户我们能感知到的是快速迭代的功能和稳定的性能。3. 从安装到上手全平台部署与核心功能实操3.1 选择你的部署方式桌面、移动端与 Docker 服务思源提供了极其灵活的部署方案你可以根据使用场景选择。对于绝大多数个人用户我强烈推荐从官方应用市场安装桌面端和移动端。桌面端Windows/macOS/Linux访问 思源官网下载页 或 GitHub Releases 页面获取安装包。安装过程无任何捆绑软件。首次启动时它会让你选择一个文件夹作为“工作空间”这就是你所有数据的家。建议选择一个你常用备份工具如 Time Machine, rsync能覆盖的位置。移动端iOS/Android在 App Store 或 Google Play 搜索“思源笔记”即可。移动端主要用于查阅、简单的编辑和收集灵感。它的数据需要通过与桌面端配置相同的同步端来保持同步。对于高级用户或团队协作场景Docker 部署是更优雅的选择。你可以将思源作为一个 Web 服务部署在家庭服务器或云主机上然后通过浏览器在任何设备上访问。下面是我在个人服务器上使用 Docker Compose 部署的配置详解其中包含了一些确保稳定运行的技巧version: 3.8 services: siyuan: image: b3log/siyuan:latest container_name: siyuan-note restart: unless-stopped ports: - 6806:6806 # 将容器的6806端口映射到宿主机的6806端口 volumes: - /path/on/your/server/siyuan-workspace:/siyuan/workspace # 关键将宿主机目录挂载为工作空间 environment: - TZAsia/Shanghai # 设置容器时区避免日志时间错乱 - SIYUAN_ACCESS_AUTH_CODEyour_strong_password_here # 设置访问密码务必修改 # - SIYUAN_ACCESS_AUTH_CODE_BYPASStrue # 如果不设置密码可以启用此选项不推荐 command: - --workspace/siyuan/workspace - --accessAuthCode${SIYUAN_ACCESS_AUTH_CODE} # 命令行参数优先级高于环境变量部署与权限要点目录权限在启动容器前务必确保宿主机上挂载的目录如/path/on/your/server/siyuan-workspace存在并且对 Docker 进程有读写权限。通常你需要运行chown -R 1000:1000 /path/on/your/server/siyuan-workspace1000是容器内默认用户ID。如果遇到权限错误可以查看容器日志docker logs siyuan-note来排查。访问授权码SIYUAN_ACCESS_AUTH_CODE是保护你数据的唯一密码必须设置一个强密码。在浏览器中访问http://你的服务器IP:6806时就需要输入这个密码。反向代理推荐长期暴露 6806 端口并不安全。你应该使用 Nginx 或 Caddy 进行反向代理配置 HTTPSSSL证书。关键是要代理 WebSocket 连接Nginx 配置中需要包含proxy_pass http://localhost:6806/ws;和proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade;这些指令否则编辑器无法正常工作。数据备份Docker 容器的数据是易失的。你定期备份的就是挂载出来的那个siyuan-workspace文件夹。可以使用tar命令打包或结合rsync同步到另一台机器。注意Docker 版本目前不支持导出 PDF/Word也不支持通过桌面/移动端 App 直接连接只能通过浏览器。它更适合作为纯 Web 版的个人知识库或小团队共享知识库。3.2 核心编辑器功能像搭积木一样组织知识安装好后让我们深入核心的编辑体验。思源的编辑器是“块编辑器”的典范。基础块操作在空白处输入/会唤出强大的块菜单。你可以快速插入标题、段落、列表、待办事项、代码块、表格、公式等数十种类型的块。每个块左侧都有一个“拖动手柄”六点图标你可以通过拖拽轻松调整块的顺序和层级实现大纲式的结构化。块引用与嵌入这是构建知识网络的利器。假设你在笔记 A 中定义了一个概念块在笔记 B 中想提及它。你只需在笔记 B 中输入((然后输入概念块的部分内容思源会智能搜索并让你选择要引用的具体块。引用后会显示一个带链接的块预览。如果你输入{{则是“嵌入”会将目标块的内容完整地、静态地复制到当前位置。引用是动态的源块修改后所有引用处会同步更新有一个“刷新”按钮嵌入则是独立的副本。自定义属性与 SQL 查询你可以给任何块添加自定义属性键值对比如为读书笔记添加author: 作者名、rating: 5。更强大的是你可以使用简单的 SQL 语句查询这些属性。例如创建一个“查询嵌入块”输入 SQLSELECT * FROM blocks WHERE content LIKE %关键词% AND updated date(now, -7 day)这个块就会动态显示最近7天所有包含“关键词”的块列表。这相当于在你的笔记内部实现了一个轻量级数据库。双向链接与关系图当你使用[[创建文档链接或通过引用建立块链接后思源会自动为你构建链接关系。点击右下角的“关系图”图标你会看到一个直观的、可交互的知识图谱清晰展示笔记间的关联强度。这对于回顾和发现知识盲点非常有帮助。3.3 数据同步、备份与版本管理实战数据是无价的因此正确配置同步和备份至关重要。官方端到端加密同步会员功能这是最省心、最安全的多设备同步方案。在“设置 - 云端”中登录你的思源账号需购买会员选择一个同步目录即可。同步过程是增量且加密的服务器无法解密你的数据。我个人的工作流是在办公室的台式机上深度编辑通过官方同步实时将更改推送到云端回到家打开笔记本同步后即可无缝继续通勤路上用手机查看或记录灵感。三端体验一致几乎没有冲突。手动备份策略免费方案如果你不想付费或者需要额外的灾备手动备份是必须的。数据导出思源提供了完整的“导出数据”功能设置 - 导出 - 导出数据会生成一个.sy.zip压缩包包含了所有笔记、附件和配置。我建议每周或每完成一个重要项目后执行一次并将压缩包保存到异地存储如另一块硬盘、加密的云存储。文件系统备份因为工作空间就是普通文件夹你可以用任何文件同步工具如 FreeFileSync, rsync定期将其复制到备份位置。但切记不要在思源运行时让两个设备同时通过文件同步工具如坚果云同步文件夹修改同一个工作空间这极大概率会导致数据文件损坏。正确的做法是“一次只在一台设备上打开思源关闭后再让同步工具同步文件夹”。利用数据仓库Data Repo思源内核内置了类似 Git 的版本管理系统。在“设置 - 关于”中你可以看到“数据仓库密钥”。初始化后思源会为你的每一次更改创建快照。你可以在“历史”面板中按天、按路径回滚到任何一个历史版本。这是应对误操作删除内容的最后一道防线。实操心得我曾因为误操作清空了一个重要的笔记页正是通过数据仓库的历史快照功能一秒内就恢复了。我现在的习惯是重要笔记编辑完成后手动在历史面板点击“生成一个快照”并添加备注这样回滚时目标更明确。4. 高级功能与扩展打造专属知识工作流4.1 模板、片段与插件自动化你的重复劳动思源提供了多种方式来提升记录效率。模板在“设置 - 模板”中你可以创建模板片段。比如我创建了一个“会议记录”模板包含日期、参会人、议题、决议、待办事项等固定结构。新建笔记时点击“模板”按钮即可一键应用省去了每次画表格的麻烦。代码片段与 CSS 片段这是深度自定义的利器。在“设置 - 代码片段”中你可以插入 JavaScript 或 CSS 代码来修改思源的行为和外观。例如我写了一个简单的 JS 片段用于在每天早上打开思源时自动在日记本中创建以当天日期为标题的新页面。CSS 片段则可以让你修改主题颜色、字体、间距等打造独一无二的视觉风格。社区集市里有很多用户分享的精彩片段。插件系统思源的插件 API 正在不断完善。通过插件你可以集成第三方服务如翻译、OCR、添加新的编辑器功能或优化现有交互。安装插件同样在“设置 - 集市”中完成。比如有一个“日历”插件可以在侧边栏显示一个日历视图并与你的日记本关联点击日期直接跳转到那天的日记。4.2 与外部工具集成OCR、AI 与闪卡复习Tesseract OCR思源内置了 Tesseract OCR 引擎支持。当你插入一张包含文字的图片比如书本截图、会议白板照片后可以在图片的上下文菜单中选择“提取图片文字”。提取出的文字会以可编辑的文本块形式插入到笔记中这对于消化纸质资料非常方便。你可以根据需要安装不同语言的数据包来提高识别精度。AI 集成OpenAI API这是一个会员功能但非常强大。在设置中配置你的 OpenAI API Key 后你就可以在编辑器里直接与 AI 对话。选中一段文字右键选择“AI 对话”可以让它帮你总结、扩写、翻译、润色甚至进行头脑风暴。更棒的是你可以创建“AI 上下文”将整个笔记本或一组笔记作为背景知识喂给 AI让它基于你的私人知识库进行问答。这相当于为你配备了一个精通你所有笔记的私人助理。闪卡复习Spaced Repetition这是将笔记转化为长期记忆的神器。思源集成了类似 Anki 的间隔重复算法。你可以将任何笔记块比如一个问答对、一个概念定义标记为闪卡。系统会根据你的记忆程度生疏、困难、良好、简单来安排下一次复习的时间。我常用它来记忆编程语言的 API、外语单词和重要的概念定义。复习界面简洁高效完全融入笔记环境避免了在 Anki 和笔记软件间切换的割裂感。4.3 导出与发布分享你的知识成果知识管理的最终目的是输出和应用。思源提供了丰富的导出选项。标准 Markdown 导出这是最通用的格式。思源会导出一个.md文件和一个同名的assets文件夹完美保留图片、附件和基本的 Markdown 格式。你可以轻松地将笔记导入到其他支持 Markdown 的平台或静态网站生成器如 Hugo, Hexo中。PDF/Word/HTML 导出用于需要正式格式的场景。PDF 导出支持目录、页眉页脚等定制。Word 导出则方便与使用 Office 的同事协作。HTML 导出可以生成一个独立的、样式美观的网页文件。一键发布到平台思源针对中文内容平台做了特别优化。写好的文章可以直接“复制到微信公众号”、“复制到知乎”或“复制到语雀”。它会自动处理这些平台的格式限制比如图片上传、样式转换极大简化了内容分发的流程。5. 常见问题排查与性能优化指南即使设计再精良的软件在实际使用中也会遇到各种问题。以下是我和社区用户常遇到的一些情况及其解决方案。5.1 同步与数据冲突问题问题在多设备间使用官方同步时偶尔提示“同步冲突”。排查与解决检查网络冲突常因网络不稳定导致两端数据版本不一致。首先确保所有设备网络通畅。查看冲突文件思源会在工作空间的temp或conflict文件夹具体路径可能因版本而异中保留冲突副本。你可以比较这些副本手动合并需要的内容。重置同步如果冲突无法解决可以尝试在“设置 - 云端”中先在一台设备上“断开同步连接”然后重新连接并选择“覆盖远程数据”谨慎操作会以本地数据为准覆盖云端。确保操作前已做好本地数据备份。根本预防养成好习惯在一台设备上编辑完并确认同步成功后再在另一台设备上操作。避免同时在两台离线设备上编辑同一篇笔记。问题Docker 版本通过浏览器访问上传大文件如视频失败或很慢。排查与解决检查 Nginx 配置如果你使用了 Nginx 反向代理可能需要调整client_max_body_size参数默认值可能太小。在 Nginx 配置的http或server块中添加client_max_body_size 100M;根据你的需求调整大小。检查 Docker 存储驱动对于大量小文件操作思源会产生很多.sy文件Overlay2 存储驱动性能优于 AUFS。可以通过docker info查看。5.2 性能与资源占用优化问题笔记数量非常多超过上万条后启动或搜索变慢。排查与解决索引重建思源依赖内核进行全文搜索。你可以尝试在“设置 - 关于”中点击“重建索引”。这可能会花费一些时间但能解决因索引损坏导致的搜索问题。检查工作空间位置确保工作空间不在网络驱动器、慢速机械硬盘或加密卷如某些云盘的虚拟驱动器上。最好放在本机 SSD 的主目录下。关闭不用的插件和主题一些复杂或未优化的插件可能会影响性能。尝试禁用所有插件再逐个启用定位问题插件。分笔记本管理不要把所有笔记都放在一个巨大的笔记本里。按项目、领域建立不同的笔记本有助于内核更高效地管理数据。问题移动端 App 耗电较快。排查与解决调整同步频率在移动端设置中将“同步间隔”从“实时”调整为“每5分钟”或“手动”。关闭后台刷新在手机系统的应用设置中限制思源的后台活动。减少大型资源避免在移动端频繁打开含有大量高清图片或嵌入式大表格的笔记。5.3 功能使用疑难解答问题列表项下的第一个段落块找不到左侧的块图标拖动手柄。原因与解决这是思源的一个设计为了界面简洁列表项下的第一个子块默认隐藏了块图标。将光标移动到这个段落内按下快捷键Ctrl/Mac 是Cmd/即可唤出该块的上下文菜单里面包含了复制、剪切、删除等所有块操作。问题误删了数据仓库密钥无法同步了。解决步骤立即备份手动导出数据.sy.zip或复制整个工作空间文件夹。重置数据仓库在“设置 - 关于 - 数据仓库密钥”中点击“重置数据仓库”。注意此操作会清空当前的版本历史并生成一个新的空仓库。重新配置同步使用新的密钥在一台设备上初始化同步会创建一个新的云端同步目录。其他设备重新加入在其他设备上使用“导入密钥”功能输入新设备的密钥字符串然后重新连接同步。旧的云端同步目录将无法再访问其中的历史快照也会失效。问题导入大量 Markdown 文件时格式错乱或图片丢失。实操建议分批导入不要一次性导入成百上千个文件。先以小批量如10-20个测试。预处理图片链接确保你的 Markdown 文件中的图片链接是相对路径并且图片文件与.md文件在正确的相对位置。思源在导入时会尝试将这些图片复制到工作空间的assets文件夹中。使用“导入文件夹”功能在思源中新建一个笔记本然后右键笔记本选择“导入 - 导入文件夹”选择包含.md文件和assets图片文件夹的根目录这样能更好地保持原始结构。经过一年多的深度使用思源笔记已经彻底融入了我的学习和工作流。它可能不是最华丽的但绝对是最踏实、最让我放心的一款工具。它的核心理念——将控制权交还给用户同时提供现代、高效的知识管理体验——深深吸引了我。从最初的简单记录到如今构建起一个相互关联、可以随时查询和复习的个人知识库思源见证并促进了我思维的成长。如果你也厌倦了在多个工具间辗转渴望一个能安放所有想法并让它们产生化学反应的“数字花园”那么花点时间上手思源很可能是一次值得的投资。