一、SiYuan 是什么：隐私优先的本地化知识库

入门

SiYuan 是一款本地优先（local-first）的个人知识管理工具，所有数据保存在你自己的设备或自建服务器上，而不是云端厂商的数据库里。它采用「块级引用 + 双向链接」的组织方式，比传统 Markdown 笔记更适合搭建长期可维护的笔记体系。

和 Notion、Obsidian 等同类工具相比，SiYuan 的差异点在于：完全开源（AGPLv3）、默认不依赖任何云服务、对中文用户友好。官方同时提供桌面端（Electron）和服务端（Docker）两种形态，既能当本地 App 用，也能像 Wiki 一样部署在内网给团队访问。

核心定位可以归纳成三句话：把想法变成可重组的「块」、用关系网替代线性目录、所有数据掌握在自己手里。如果你在意笔记的长期可读性，又不想被某个 SaaS 厂商绑定迁移成本，SiYuan 是值得认真评估的方案。

二、快速部署：Docker 一键跑起来

入门

服务端模式适合「想从浏览器访问」「想在内网分享给多人」「想 7×24 小时挂在 NAS 上」这几类场景。官方推荐用 Docker 部署，3.7.0 之后必须显式带上 serve 子命令，否则容器会启动失败。

先准备一个宿主机目录用于持久化数据，例如 /data/siyuan/workspace，再执行下面这段命令：

docker run -d \
  --name siyuan \
  --restart always \
  -v /data/siyuan/workspace:/siyuan/workspace \
  -p 6806:6806 \
  -e PUID=1000 \
  -e PGID=1000 \
  b3log/siyuan \
  serve \
  --workspace=/siyuan/workspace/ \
  --accessAuthCode=你的访问密码

启动后浏览器访问 http://服务器IP:6806，首次会要求输入 --accessAuthCode 设的密码。PUID/PGID 用于让容器内的进程以指定用户身份读写挂载卷，避免出现权限归属 root 的尴尬。

如果只是想本地体验、不需要长期挂着，最简单的方式是直接装桌面端：下载页 提供了 Windows / macOS / Linux 安装包，开箱即用、不写一行配置。

习惯 Compose 的同学可以用下面的等价文件，结构更清晰：

services:
  siyuan:
    image: b3log/siyuan
    container_name: siyuan
    restart: always
    ports:
      - "6806:6806"
    environment:
      - PUID=1000
      - PGID=1000
    volumes:
      - ./workspace:/siyuan/workspace
    command: serve --workspace=/siyuan/workspace/ --accessAuthCode=你的访问密码

三、配置详解：环境变量、数据卷与端口

进阶 · 推荐细读

SiYuan 的配置入口分两处：命令行参数控制启动行为，环境变量控制容器身份；二者重叠时命令行优先级更高。下面按使用频率整理成速查表。

端口与网络

• 6806：默认 HTTP 端口，所有 Web 访问都走这里。修改需同时改 -p 映射和容器内参数。
• 容器内不要修改监听地址为 127.0.0.1，否则从宿主机访问会失败。

数据卷（最关键）

• /siyuan/workspace：工作区目录，存放数据库 siyuan.db、附件、快照等。必须挂载到宿主机，否则容器重建 = 数据全丢。
• 建议把宿主机路径和容器内路径保持一致（例如都是 /siyuan/workspace），可以省去一类路径映射相关的疑难杂症。

常用环境变量

核心命令行参数

--workspace=路径           工作区目录
--accessAuthCode=密码      浏览器访问密码
--port=端口                自定义 HTTP 端口
--host=地址                监听地址，默认 0.0.0.0
--lang=语言代码            启动时强制语言
--servePath=路径           静态资源前缀，便于反代

--accessAuthCode 一旦设置，所有访问都要输入，建议用一个足够长、且与服务端其他密码不同的字符串；如果只是本地 NAS 内部使用，也可以留空省去每次输入密码的麻烦。

四、功能导览：块、双链、数据库与同步

入门

上手 SiYuan 的第一关是理解「块（Block）」这个概念。不同于 Notion 的页面树，SiYuan 把每一行、每一段、每一个标题都当成独立可引用的块，块与块之间可以建立双向链接，这也是后续做知识图谱、闪卡、数据库视图的基础。

编辑器主界面

进入后左侧是大纲树，中间是块编辑器，右侧是大纲/关系图/书签等面板。常用的快捷键和大多数 Markdown 编辑器兼容：# 出一级标题，> 出引用，``` 出代码块，[[ 触发双链候选。

块级操作的小技巧

• 输入 / 唤起菜单，可快速插入数据库、公式、嵌入文件等。
• 把鼠标悬停在块左侧的 ⋮⋮ 抓手，能拖拽、复制、转化为其他类型。
• 选中一段文本按 [[ 可创建反向链接，源块和目标块会自动关联。

数据库视图

在编辑器内输入 /database 即可插入一个内嵌数据库，支持表格、看板、画廊等多种视图，适合做任务管理、阅读清单、书籍卡片等结构化场景。底层存储仍是 SQLite，导入导出都走标准格式。

同步与备份

官方提供了三类同步通道，按推荐顺序排列：

1. 云端同步（付费）：官方 S3 兼容存储，开箱即用、最省心。
2. 自建 S3 / WebDAV：在「设置 → 同步」里填入自己的 MinIO、阿里云 OSS、坚果云 WebDAV 即可，所有数据走端到端加密。
3. 数据快照 + Git：在「设置 → 数据仓库」开启快照，每次保存会自动生成一份可 diff 的备份，适合喜欢把笔记当作纯文本资产管理的用户。

插件与扩展

「集市」标签下可以浏览社区插件，覆盖AI 助手、PDF 标注、闪卡（Anki 风格）、Mermaid 增强等高频需求。插件以独立仓库形式发布，安装时填入 GitHub 仓库地址即可，无需等官方发版。

五、运维进阶：反代、SSL、升级与备份

深入 · 老手可选

把 SiYuan 暴露在公网或团队内网前，建议补齐「反代 + HTTPS + 定期备份」这三件事，缺任何一项都可能在未来某次升级或迁移时翻车。

反向代理（Nginx 示例）

server {
    listen 443 ssl http2;
    server_name notes.example.com;

    ssl_certificate     /etc/letsencrypt/live/notes.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/notes.example.com/privkey.pem;

    client_max_body_size 0;

    location / {
        proxy_pass http://127.0.0.1:6806;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

client_max_body_size 0 是为了放行大文件上传（比如导入整本 PDF）；Upgrade 头那两行是 WebSocket 转发，关系图、协同编辑等功能都依赖它。

升级策略

• 升级前先看一眼「设置 → 关于」里的数据库版本和迁移说明，跨大版本（如 2.x → 3.x）建议先做一次完整快照。
• 拉取新镜像后用同一条 docker run 命令重启即可，工作区数据落在挂载卷里不会丢。
• 桌面端升级会自动提示，下载安装包覆盖即可，不要把工作区放在系统盘的用户目录以外，否则升级后可能找不到旧数据。

数据备份

最稳妥的方案是把 /siyuan/workspace 整目录扔进定时任务里打 tar 包，再推到对象存储：

tar -czf siyuan-$(date +%F).tar.gz -C /data/siyuan workspace
rclone copy siyuan-$(date +%F).tar.gz remote:siyuan-backup/

另外官方内置的「数据仓库 → 快照」建议同时打开，快照是增量、人类可读（基于 Git），适合回溯单篇笔记的修改历史；tar 包是粗粒度兜底，两者互补。

常见误区

• 不要把 --workspace 指向容器内的临时目录（如 /tmp），容器重建即丢。
• 反向代理后出现登录态丢失，大概率是 Host 头没透传，按上面 Nginx 示例补齐即可。
• 多端同时编辑同一篇笔记是支持的，但服务端是单实例设计，不要用负载均衡把多个容器挂在同一工作区前面，会引发数据库写冲突。

项目信息

参考链接

• GitHub 仓库
• 项目主页