思源笔记用户指南 https://siyuannote.com/ 思源笔记用户指南 Thu, 06 Aug 2026 02:03:45 GMT https://validator.w3.org/feed/docs/rss2.html https://github.com/jpmonette/feed zh-CN All rights reserved 2026, NULL <![CDATA[AI 智能体]]> https://siyuannote.com/article/1724604650 https://siyuannote.com/article/1724604650 Thu, 31 Oct 2024 00:00:00 GMT

使用方式

 

AI模型服务商（AIHUB）

1️⃣ 便宜且相对稳定的 Token，Codex 低至 0.03x 2️⃣ 监控多渠道随时切换，十几家几乎源头的渠道 3️⃣ 供应商大厅透明 4️⃣ C 端服务专注做好 链接：https://aihub.top/register?aff=YPJ9WK6QW5PY
 
1 注册AI服务商并创建API，（直达）
2 思源笔记配置API服务商
3 填写相关设置
API 基础地址
https://aihub.top/v1
ㅤ
自定义显示名称
aihub
ㅤ
API Key
填写在API服务商复制的API 密钥
ㅤ
超时时间
120
默认值即可
notion image
4 配置模型
 
 
 

第三方免费大模型（siliconflow）

🌟 硅基流动：良心 AI 🌟
1️⃣ 免费模型: 支持免费模型 2️⃣ Token 消耗: 使用免费模型不消耗送的 2000 万 tokens 3️⃣ 付费模型推荐: 建议使用 deepseek-ai/DeepSeek-V3.1
链接: 我的邀请链接 （您与好友均可获赠2000万Tokens）
 
1、注册硅基流动账号 （直达）
2、点击 API密钥 ，新建 API 密钥 （直达），点击密钥复制后填入下步的2️⃣中
获取API
获取API
 
3、思源笔记 → 设置 → AI，按照下图填写配置
notion image
1️⃣ 在硅基流动的模型广场中挑选模型，填写模型名称（直达）推荐模型：zai-org/GLM-4.6
notion image
2️⃣ 填写新建的 API 密钥
3️⃣ 填写 https://api.siliconflow.cn/v1
 
💡
其他配置项说明（如果不清楚，使用默认值即可）：
  1. 超时时间：控制请求等待时间，避免长时间无响应。根据自己网络和请求复杂度设置合理的超时时间，如果报错了可以适当调大时间。
  1. 最大 Token 数：限制请求和响应的长度，避免过长内容。根据需求和资源限制设置合适的Token数量。
  1. 温度请求：调整生成内容的多样性，高温度增加创造性，低温度增加一致性。根据应用场景选择合适的温度。
  1. 最大上下文：限制模型考虑的历史对话长度，影响回复的相关性。建议根据对话复杂度和资源情况设置合适的上下文长度。

DeepSeek 深度求索

1、注册 DeepSeek 开放平台 ，注册获体验金（限中国大陆手机号）
2、点击菜单 API keys，然后点击 创建API key
notion image
3、在创建API key的弹窗中随意输入名称后点击创建
notion image
4、点击复制
notion image
5、将生成的 API Key 粘贴在思源笔记的 AI 设置中图标2。（DeepDeek文档说明）
图标
名称
填写内容
1
模型
deepseek-chat
2
API Key
（上面复制的API Key）
3
API 基础地址
https://api.deepseek.com/v1
notion image
💡
其他配置项说明（如果不清楚，使用默认值即可）：
  1. 超时时间：控制请求等待时间，避免长时间无响应。根据自己网络和请求复杂度设置合理的超时时间，如果报错了可以适当调大时间。
  1. 最大 Token 数：限制请求和响应的长度，避免过长内容。根据需求和资源限制设置合适的Token数量。
  1. 温度请求：调整生成内容的多样性，高温度增加创造性，低温度增加一致性。根据应用场景选择合适的温度。
  1. 最大上下文：限制模型考虑的历史对话长度，影响回复的相关性。建议根据对话复杂度和资源情况设置合适的上下文长度。

常见问题

 
 

文章

在思源文档内进行 AI 对话 - 链滴
对 Fmisc 的对话进行了一波扩展 （v5.7.0），增加了一个「文档内对话」的功能——字面意义就是直接在文档中与 AI 进行对话，不用切换到单独的聊天界面。 触发方式 直接在编辑器中输入 /chat 或 /chatmini 命令： [图片] 分别对应了两种对话模式： 超级块模式（Mini 版）： 通过 /chatm
在思源文档内进行 AI 对话 - 链滴
https://ld246.com/article/1747212372726
在思源文档内进行 AI 对话 - 链滴
fmisc v6.00 更新, 支持 AI 工具调用 - 链滴
6.0 版本的主要更新就是增加了工具调用功能（或者用烂俗一点的话叫 Agent）。 以工具组为单元支持四种工具： 网络检索工具 Bing 检索免费可用；Tavily 和 Bocha 需要提供 API Key 文件系统工具 脚本工具（无编程经验者不建议开启） 思源笔记相关工具 [图片] 案例 [图片] [图片] [图片]
fmisc v6.00 更新, 支持 AI 工具调用 - 链滴
https://ld246.com/article/1749304311185
fmisc v6.00 更新, 支持 AI 工具调用 - 链滴
 
]]> <![CDATA[嵌入内容块]]> https://siyuannote.com/article/1724455152 https://siyuannote.com/article/1724455152 Fri, 31 Dec 2021 00:00:00 GMT

概述

嵌入内容块主要用于汇总所需内容块，通过 {{ 和 }} 将 SQL 脚本包裹起来并独占一行：{{ SELECT * FROM blocks WHERE content LIKE '%关键字%' }}，数据库表请参考这里。#内容块/嵌入#

示例

查询内容中包含 内容块 的列表项：
 
查询内容中同时包含 内容块 和 引用 段落块：
 
查询内容中同时包含 内容块 和 嵌入 的标题块并按更新时间降序结果取前 2 条：

案例一

查询同时包含 在思源中 和 核心概念 文本的段落块，并排除当前文档（否则当段落块也会包含到结果集中，因为当前段落同样包含了这两个文本，下面的案例类似）：
notion image

案例二

查询同时包含标签 #内容块/嵌入# 和 #内容块/引用# 的段落块：
notion image

案例三

有时候我们可能需要随机漫游显示内容块，以方便回顾。
notion image

案例四

查询未完成的任务列表项，这里需要使用 markdown 字段而不是 content 字段：
notion image
 
]]> <![CDATA[日记]]> https://siyuannote.com/article/1725202836 https://siyuannote.com/article/1725202836 Fri, 31 Dec 2021 00:00:00 GMT
我们可以通过日记来快速创建文档，日记功能入口在顶部主菜单中。
但在使用日记前，需要在笔记本右键菜单中打开 设置，在新建日记设置中配置：
1️⃣ 存放路径：笔记本下的路径，支持模板变量
2️⃣ 模板路径（可选）：创建日记时使用该模板作为初始内容
💡
小提示 在指定的模板使用嵌入内容块，可以汇总待办事项或者需要每日查看的内容块。
 
notion image
 
在图中的红框区域配置设置项
notion image

1️⃣ 存放路径

默认的存放路径是 /daily note/{{now | date "2006/01"}}/{{now | date "2006-01-02"}}
此模板变量在新建日记时自动生成符合设定格式的位置和名称。
 
例如: 今天是2024年11月08日, 当我新建一个日记时（alt+5）日记会根据模板变量自动新建在设定的位置，并生成日期标题。
notion image
 
💡
简单解释存放路径，例如：/daily note/{{now | date "2006/01"}}/{{now | date "2006-01-02"}}
模板使用的是 Go 编程语言的文本模板进行实现
 
.action{now | date "2006-01-02 15:04:05"} 渲染 yyyy-MM-dd HH:mm:ss 例如 2024-08-01 09:50:31
.action{now | date "2006-01-02"} 渲染 yyyy-MM-dd 例如 2024-08-01
.action{now | date "2006-01"} 渲染 yyyy-MM 例如 2024-08
.action{now | date "2006"} 渲染 yyyy 例如 2024
 
更多的组合请学习 模板片段 语法
 

常见存放路径示例

效果展示
效果展示
 
效果展示
效果展示

2️⃣ 模板路径

模板路径是创建日记时使用该模板作为初始内容。自动生成自定义的日记框架。
效果展示
效果展示

集市模板

打开思源笔记设置 → 集市 → 模板 → 选择一个点击
notion image
在模板详情页面点击 下载
notion image
回到笔记页面，在笔记编辑区键入 /mu ，选择一个你需要的模板，例如日计划。（点击模板即可在当前笔记中加载预览）
notion image
将选中的模板名称填写在模板路径处。（Normal/templates/一周/日计划）
再新建日记时（alt+5）就会自动加载模板。
notion image
 

自己编写日记模板

将编写好的模板文件（.md 格式）放置于工作空间/data/templates/ 下。
然后在模板路径处填写文件名称即可
📝 模板教程
 
 

文章

思源笔记新建存放日记 年 / 月 / 周 / 日的路径设置分享 - 链滴
一、需求背景：从流水账到结构化复盘的归档逻辑 作为习惯用笔记软件记录生活的人，我希望实现这样的归档规则： 每日随手记录流水账（按日期命名） 每周汇总到对应周目录（按「年 / 月 + 周数」分级） 每月生成月度总结（按月份聚合每周内容） 核心需求是新建日记时自动生成「年 / 月 / 周 / 日」层级路径。其中关键逻辑在于
思源笔记新建存放日记 年 / 月 / 周 / 日的路径设置分享 - 链滴
https://ld246.com/article/1749032171152
思源笔记新建存放日记 年 / 月 / 周 / 日的路径设置分享 - 链滴
日、周、月记录模板分享 - 链滴
第一次使用思源笔记，感觉社区中相关的模板还是比较少，然后在大佬给出的模板基础上，进行了一些修改，于是有了本文。（由于参考了直接导出，相关 id 没有删除，可以自行处理，但是不删也不影响） 还有一个问题：在周和月导出的时候会出现几个不知名“}}}”，但是在笔记页面的显示是正常的，目前还不知原因。 使用方法：将代码保存到
日、周、月记录模板分享 - 链滴
https://ld246.com/article/1734407382742
日、周、月记录模板分享 - 链滴
]]> <![CDATA[笔记搜索]]> https://siyuannote.com/article/1735150477 https://siyuannote.com/article/1735150477 Tue, 24 Dec 2024 00:00:00 GMT
思源笔记提供多层次的搜索能力：日常可以用全局搜索快速定位笔记，遇到复杂条件时可以切换到查询语法、正则表达式或 SQL；需要脚本和插件集成时，也可以调用搜索 API。

先选哪种搜索方式

搜索方式
适合场景
示例
注意事项
关键字
快速查找标题、正文和常用块属性
同步、Docker、反向链接
结果过多时，增加关键词、限制路径或筛选块类型。
查询语法
多个关键词的包含、排除、组合查询
foo OR bar、foo NOT bar
需要在搜索方式中切换到“查询语法”。空格默认表示 AND。
正则表达式
匹配固定格式、编号、日期、链接、代码片段
\d{4}-\d{2}-\d{2}
正则过宽会影响速度，建议配合路径和类型过滤。
SQL
按块表字段、时间、类型、任务状态做结构化检索
SELECT * FROM blocks ... LIMIT 20
适合高级用户；SQL 搜索方式不支持替换操作。
API
插件、脚本、外部工具调用思源搜索
POST /api/search/fullTextSearchBlock
SQL 模式需要管理员权限；普通场景优先使用界面搜索。

打开搜索

  • 全局搜索：使用默认快捷键 Ctrl/⌘ + P，或点击界面中的搜索入口。适合在整个工作空间里查找笔记块。
  • 当前文档搜索：使用 Ctrl/⌘ + F，只在当前打开的文档中查找文本。
  • 固定搜索：使用默认快捷键 Shift + Ctrl/⌘ + F，适合把搜索面板固定在工作区中持续筛选。
  • 搜索结果中可以用方向键浏览，用回车打开；也可以在预览区快速判断命中位置。

搜索面板里的常用过滤

  • 指定路径：点击搜索面板顶部的路径按钮，把范围限制到某个笔记本、文档或目录。
  • 包含子文档：在指定路径后，按需要启用子文档范围，避免只搜到当前层级。
  • 块级类型：只搜索文档块、标题、段落、列表、代码块等特定类型。全局搜索里的过滤会覆盖“设置”里的默认块级类型。
  • 块级属性：可以在“设置 → 搜索”中配置是否搜索命名、别名、备注等块级属性。
  • 区分大小写：在“设置 → 搜索 → 区分大小写”中开启后，相关搜索功能会区分英文大小写。
  • 搜索结果显示数：结果数量过大时会拖慢搜索；数据量较大时不要把该值设得太高。

关键字搜索

关键字是最常用的搜索方式，适合记得某个词、标题片段或短句时快速定位内容。
建议用法：
  • 先输入最有辨识度的词，而不是太泛的词。例如搜 双链 通常比搜 笔记 更快收敛。
  • 结果太多时，不要继续翻很久，优先增加第二个关键词或限制路径。
  • 如果想表达“包含 A 但不包含 B”“A 或 B 任意一个”，切换到“查询语法”会更准确。
  • 如果发现重复结果，检查是否把容器块纳入了搜索范围；启用容器块后可能带来重复命中。

查询语法

查询语法适合表达明确的逻辑条件。切换搜索方式为“查询语法”后，可以使用 AND、OR、NOT 和括号组合。
写法
含义
适合场景
foo bar
同时包含 foo 和 bar
多个关键词同时出现。
foo AND bar
同时包含 foo 和 bar
显式写出逻辑，便于阅读和保存。
foo OR bar
包含 foo 或 bar 任意一个
同义词、旧称和新称一起查。
foo NOT bar
包含 foo，但不包含 bar
排除噪声结果。
(foo OR bar) AND baz
先组合 foo/bar，再要求包含 baz
复杂主题检索。
"foo/bar"
把特殊字符包在英文双引号中
关键词中包含符号、斜杠、运算符等字符。
常见误区：
  • 在“关键字”方式下输入 OR、NOT，它们可能只是普通词；需要切换到“查询语法”。
  • 操作符建议使用英文大写，括号使用英文括号。
  • 如果你想搜索字面量 AND、OR、NOT，可以用英文双引号包起来。

正则表达式搜索

正则表达式适合查“形式”而不是查“固定词”。在搜索方式中切换到“正则表达式”后，可以输入正则模式。
常见例子：
匹配 2026-06-23 这类日期。
匹配 TODO 或 FIXME。
匹配以 http:// 或 https:// 开头的链接。
使用建议：
  • 先限制到某个笔记本或文档，再运行复杂正则。
  • 正则中的 .、*、?、[、] 等都有特殊含义，搜索字面量时需要转义。
  • 如果只是查多个词，优先使用查询语法；正则留给格式化内容。

SQL 搜索

SQL 适合按结构化字段查询，例如块类型、创建时间、更新时间、任务状态等。它常用于两类场景：
  • 搜索面板中切换搜索方式为 SQL，直接用 SQL 找块。
  • 在文档中插入嵌入块，用 SQL 动态展示查询结果。
基础示例：
查找最近更新的任务块：
查找同时包含两个关键词的文档：
注意事项：
  • 日常查询尽量加 LIMIT，避免一次返回太多结果。
  • SQL 搜索方式不支持替换操作，需要替换文本时请切回其他搜索方式。
  • 不熟悉表结构时，先从 blocks 表开始；常见字段包括 id、root_id、content、markdown、type、subtype、created、updated。
  • 不要把 SQL 搜索当作修改数据库的工具；用户指南中建议只编写查询型 SQL。

搜索资源文件内容

普通笔记搜索主要面向笔记块内容。如果要搜索附件或资源文件里的文字，请使用“搜索资源文件内容”入口。
适合场景：
  • 想在 PDF、Office 文档等资源文件中查找文字。
  • 明明记得内容在附件里，但普通笔记搜索没有结果。
  • 需要确认某个关键词是否出现在资源文件正文中。
排查建议：
  • 先确认资源文件本身能被提取出文本；扫描件图片可能需要 OCR 后才容易搜索。
  • 搜索资源文件内容和搜索笔记块是两个入口，不要混用。
  • 如果资源文件很多，先用更具体的关键词，避免搜索时间过长。

API 和插件调用

插件、脚本或外部工具可以调用搜索接口：
常用请求体示例：
method 的含义：
  • 0：关键字
  • 1：查询语法
  • 2：SQL
  • 3：正则表达式
接口返回结果中通常包含命中的块列表、命中块数量、命中文档数量、页数等信息。SQL 模式需要管理员权限；如果只是做普通搜索集成，优先使用关键字、查询语法或正则模式。

搜不到或结果不准时

按这个顺序排查，通常最快：
  1. 先清空路径限制，确认不是搜错笔记本或文档。
  1. 检查是否启用了“包含子文档”。只限定父文档时，可能不会覆盖你想搜的子文档。
  1. 检查块级类型过滤。只勾选标题时，自然搜不到正文段落。
  1. 检查搜索方式。逻辑查询要用“查询语法”，格式匹配要用“正则表达式”。
  1. 检查“设置 → 搜索”中的块级类型、块级属性、区分大小写、搜索结果显示数。
  1. 如果目标内容在附件里，改用“搜索资源文件内容”。
  1. 如果某些内容被配置为忽略搜索，需要调整忽略搜索规则。
  1. 如果索引疑似异常，可以在“设置 → 搜索 → 索引”中重建索引。重建期间可能占用资源，建议在不急用时操作。
  1. 如果全局搜索响应较慢，增加关键词、设置类型过滤或缩小路径范围。

推荐学习路径

  1. 先熟悉全局搜索、当前文档搜索、路径过滤和块类型过滤。
  1. 再学习查询语法，用 AND、OR、NOT 解决大部分复杂搜索。
  1. 需要查格式时学习正则表达式。
  1. 需要按块类型、时间、任务状态汇总时，再学习 SQL 和嵌入块。
  1. 需要自动化时，再使用搜索 API 或插件接口。

参考资料

]]> <![CDATA[超链接]]> https://siyuannote.com/article/1725202932 https://siyuannote.com/article/1725202932 Fri, 31 Dec 2021 00:00:00 GMT

概述

思源支持使用 siyuan:// 协议从外部应用跳转到桌面端里的指定内容块。这个链接常用于浏览器书签、任务管理工具、日历、聊天软件、Markdown 文档或其他支持超链接的软件中。
最常见的形式是：
点击后，系统会尝试唤起思源桌面端，并定位到对应的块。
⚠️
Siyuan:// 块超链接依赖本机已经安装并注册了思源桌面端协议。它不是网页分享链接，也不能让没有本地数据的人访问你的笔记内容。

适用场景

  • 在外部待办事项中关联某条笔记、段落或任务块
  • 在浏览器书签里保存常用文档入口
  • 在聊天、邮件、项目管理工具中给自己或同设备用户快速跳转
  • 在其他 Markdown 文档中引用思源里的某个块
  • 配合启动器、快捷指令、自动化工具快速打开指定内容
如果只是想在思源内部引用内容，通常优先使用块引用、嵌入块或内部链接；如果要从思源外部跳回桌面端，再使用 siyuan:// 超链接。

链接格式

打开指定块

其中 {id} 是目标块 ID，例如：
要求：
  • 思源桌面端已经安装并能被系统唤起
  • 目标块所在的工作空间是当前桌面端正在使用的工作空间
  • 目标块所在笔记本已经处于打开状态
  • 目标块没有被删除

聚焦打开

在链接后加入 focus=1，可以让思源打开后聚焦到目标块：
例如：
如果链接里还需要追加其他查询参数，请使用标准 URL 查询字符串写法，用 & 连接多个参数。

如何复制块超链接

  1. 在思源中找到目标块。
  1. 打开块标菜单。
  1. 选择 复制。
  1. 选择 复制块超链接。
  1. 将复制得到的 siyuan://blocks/... 链接粘贴到外部应用中。
块标菜单通常位于块左侧。不同平台、主题或移动端界面可能略有差异，但入口都围绕块菜单展开。

放到 Markdown 中

如果目标软件支持 Markdown，可以把块超链接写成普通链接：
也可以使用聚焦打开：
部分软件会限制非 http 协议链接，导致 siyuan:// 无法点击或被自动转义。遇到这种情况时，可以改为直接粘贴纯文本链接，或检查该软件是否允许自定义协议跳转。

系统注册

Windows 和 macOS

Windows 和 macOS 上，思源桌面端启动后通常会自动向系统注册 siyuan:// 协议。
如果点击链接没有反应，可以尝试：
  • 确认已经安装并启动过思源桌面端
  • 退出并重新启动思源
  • 更新到较新的桌面端版本
  • 检查系统是否弹出过“允许打开思源”的确认窗口
  • 在浏览器地址栏中直接粘贴 siyuan://blocks/{id} 测试

Linux

Linux 上可能需要手动注册 URL Scheme。大致流程如下：
  1. 创建或找到 siyuan.desktop 文件。
  1. 确保文件中包含协议关联：
  1. 确保 Exec 后面带有 %u，用于接收外部传入的链接：
  1. 更新桌面数据库并设置默认处理程序：
  1. 测试是否能唤起：
更多细节可参考 xdg-utils。
💡
如果 Linux 桌面环境不一致，.desktop 文件的位置和刷新方式可能不同。常见位置包括 ~/.local/share/applications/ 和 /usr/share/applications/。

常见问题

点击后只打开思源，没有跳到目标块

可能原因：
  • 块 ID 不正确或块已被删除
  • 当前打开的不是包含该块的工作空间
  • 目标块所在笔记本没有打开
  • 外部软件没有完整传递 siyuan://blocks/{id} 链接
  • 外部软件对自定义协议兼容性不好
建议先把同一个链接粘贴到浏览器地址栏测试。如果浏览器能跳转，问题通常在外部软件；如果浏览器也不能跳转，再检查思源本身和块 ID。

外部软件不允许点击 siyuan:// 链接

一些软件只允许 http:// 或 https:// 链接，可能会把 siyuan:// 当作普通文本或危险链接处理。
可以尝试：
  • 使用 Markdown 链接格式
  • 直接粘贴纯文本链接
  • 换到浏览器、系统运行窗口或支持自定义协议的软件中测试
  • 查看目标软件是否有“允许外部协议”或“打开外部应用”的设置

移动端点击后行为不一致

Siyuan:// 超链接主要用于拉起桌面端。移动端、浏览器环境或第三方应用中的跳转行为可能受系统和应用限制影响，并不一定和桌面端完全一致。

链接发给别人能不能打开

能否打开取决于对方本机是否有同一个块：
  • 对方必须安装思源并注册 siyuan:// 协议
  • 对方必须拥有包含该块 ID 的工作空间数据
  • 对方当前工作空间和笔记本状态也会影响跳转
因此块超链接更适合个人跨软件跳转，不适合作为公开分享链接。

超链接和其他链接方式的区别

方式
适用范围
说明
siyuan://blocks/{id}
思源外部跳转到桌面端
需要本机安装思源并有对应数据
块引用
思源内部引用
适合在笔记内引用另一个块
嵌入块
思源内部复用内容
适合把查询或块内容嵌入当前文档
网页分享链接
网页访问
依赖发布、分享或站点服务，不等同于本地块超链接

使用建议

  • 给重要块建立稳定链接前，先确认该块不太会被删除或重建
  • 外部工具里保存链接时，建议同时写上简短标题，避免只有一串块 ID
  • 公开文档中不要把 siyuan:// 当作分享链接使用
  • 出现跳转问题时，优先用浏览器地址栏或 xdg-open 做最小化测试

参考资料

]]> <![CDATA[Docker 伺服]]> https://siyuannote.com/article/1725202944 https://siyuannote.com/article/1725202944 Fri, 31 Dec 2021 00:00:00 GMT
在服务器或 NAS 上运行思源，最简单稳定的方案是使用官方 Docker 镜像 b3log/siyuan。部署完成后，通过浏览器访问 http://服务器 IP:6806 即可使用。
⚠️
先确认工作空间挂载正确。 思源数据保存在工作空间目录中，如果 -v 或 volumes 写错，容器删除后可能会造成数据丢失。公开访问时务必设置强访问授权码。

适用场景

  • 适合在 Linux 服务器、NAS、Unraid、TrueNAS、群晖等环境中长期运行
  • 适合只需要通过浏览器访问思源的场景
  • 不适合把 Docker 版当作桌面端或移动端的同步服务

镜像信息

  • 镜像名称：b3log/siyuan

程序结构

容器内程序位于 /opt/siyuan/，主要结构如下：
  • appearance：图标、主题、多语言资源
  • guide：帮助文档
  • stage：界面和静态资源
  • kernel：思源内核程序
  • entrypoint.sh：容器启动入口脚本
当前 Docker 镜像入口为：
启动时最终会运行思源内核，并把工作空间路径、访问授权码等参数传给内核。

1 分钟启动

以下示例把宿主机和容器内的工作空间都统一为 /siyuan/workspace，这样最不容易写错路径。
启动后访问：
查看运行状态：
停止和启动：

参数说明

  • -v /siyuan/workspace:/siyuan/workspace：把宿主机目录挂载为容器内工作空间
  • -p 6806:6806：把思源 Web 端口暴露到宿主机
  • PUID：容器内运行用户的用户 ID，未设置时默认 1000
  • PGID：容器内运行用户的用户组 ID，未设置时默认 1000
  • --workspace：指定思源工作空间路径
  • --accessAuthCode：访问授权码，请务必改成强密码
可以用下面命令查看当前 Linux 用户的 UID 和 GID：
如果宿主机工作空间属于当前用户，例如 UID/GID 是 1001:1002，则要同步调整目录权限和环境变量：

Docker Compose 部署

更推荐长期使用 Docker Compose，方便升级、重启和维护。
在服务器上创建 compose.yaml：
同目录创建 .env：
启动：
查看日志：
关闭：

环境变量写法

除了命令行参数，也可以使用环境变量指定工作空间和访问授权码：
如果命令行参数和环境变量同时存在，命令行参数优先级更高。
不建议公开部署时关闭访问授权码。如果只在完全可信的内网环境中使用，可以通过下面变量跳过授权码：

权限处理

官方镜像会通过 entrypoint.sh 根据 PUID 和 PGID 创建或调整容器内的 siyuan 用户。现在通常不需要再额外传 -u 1000:1000。
如果出现无法创建文件、无法保存、启动时报 permission denied，优先检查：
然后让目录所属用户和容器环境变量保持一致：

反向代理和隐藏端口

如果需要通过域名访问，建议使用 NGINX、Caddy、Traefik 等反向代理，并把 Docker 端口只绑定到本机。
Docker 端口改为：
Docker Compose 写法：
NGINX 示例：
💡
建议使用独立域名或子域名，例如 siyuan.example.com。不要用 URL 重写把思源挂到某个子路径下，否则鉴权和 WebSocket 可能出现异常。

升级

升级前先备份工作空间。使用 Compose 时推荐流程如下：
生产环境更稳妥的做法是固定镜像版本，例如：
确认新版正常后再修改版本号升级。可在 Docker Hub Tags 或 GitHub Releases 查看版本。

备份和恢复

思源 Docker 部署最重要的是工作空间目录。建议定期备份整个 /siyuan/workspace，不要只备份容器。
备份：
恢复：
如果使用快照、云盘或 NAS 备份，也要确保备份的是宿主机上的工作空间目录，而不是容器内部目录。

安全建议

  • --accessAuthCode 必须设置为强密码
  • 公网访问建议开启 HTTPS
  • 使用反向代理时，容器端口尽量只绑定 127.0.0.1
  • 云服务器安全组只开放必要端口，例如 80、443
  • 不要把工作空间目录放到会被第三方同步盘实时同步的位置
  • 不要把 .env 中的访问授权码提交到公开仓库

常见问题

打开页面后要求输入授权码

输入启动参数或环境变量中设置的 accessAuthCode。如果忘记了，查看 Compose 文件、.env 文件或 Docker 启动命令。

容器启动后访问不了

依次检查：
  • 容器是否运行：docker ps
  • 日志是否报错：docker logs siyuan 或 docker compose logs -f
  • 服务器防火墙和云服务器安全组是否放行 6806
  • 如果用了反向代理，确认 /ws 已经正确代理 WebSocket

提示权限不足或无法保存

通常是宿主机目录权限和 PUID/PGID 不一致。检查目录所有者后执行：
如果你的 PUID/PGID 不是 1000:1000，请替换为实际值。

升级后数据不见了

优先检查 volumes 或 -v 是否指向了原来的宿主机目录。只要原工作空间目录还在，通常重新挂载正确路径即可恢复。

反向代理后登录或连接异常

不要使用 URL 重写；优先使用独立域名或子域名。确认 /ws WebSocket 代理配置正确。

当前限制

Docker 伺服版有一些限制：
  • 不支持桌面端和移动端应用连接，仅支持浏览器使用
  • 不支持导出 PDF、HTML 和 Word 格式
  • 不支持导入 Markdown 文件

参考资料

]]>