你有没有过这种困扰：把工作沉淀、个人随想和项目资料全都记在云端笔记里，哪天断网了打不开，或者哪天官方服务策略一变、账号被风控，辛苦攒了几年的笔记就全成了别人服务器里的人质？市面上虽然笔记工具很多，但真正能把数据自主权、块级细粒度排版以及网状双向链接结合得如此顺手的，思源笔记（SiYuan）绝对是当之无愧的硬核利器。

思源笔记是一款专为本地优先（Local-first）而生的知识管理与双链笔记系统。它把每一行段落、列表、代码甚至引用都视作独立的“块（Block）”，不仅支持完整的 Markdown 语义，还能像搭积木一样随意引用、嵌入和跨文档联动，特别适合想要把笔记数据牢牢攥在自己手里、追求知识网状关联的朋友。本文基于当前官方最新的稳定版本 v3.8.9 进行实机部署验证，容器默认服务端口为 6806。只要你有一台轻量云服务器或家里常开的 NAS，花上几分钟跑一个 Docker 容器，就能拥有一套属于你自己的全功能私有云笔记服务。

成品长这样

在开始敲键盘前，先来直观感受一下部署完成后的 Web 端工作台。界面清爽无杂质，左侧支持多笔记本与大纲树层级管理，中间是极度丝滑的块级编辑主区域，右侧支持知识拓扑图谱与反向链接面板：

思源笔记工作空间与演示笔记界面
图 1：思源笔记 Web 端主界面（块级编辑排版、层级大纲与双链联动效果展示）

准备工作

思源笔记官方提供了打包极为规范的 Docker 镜像，因此我们在宿主机上无需折腾任何复杂的编译依赖与数据库底座。动手部署前，请先确认以下几项准备齐备：

  • Docker 与 Docker Compose 环境：确保服务器已正常安装 Docker 引擎（建议 20.10+）以及 Docker Compose 插件。可在终端运行 docker compose version 验证可用性。
  • 防火墙与安全组放行端口：思源笔记容器默认暴露 6806 端口。请在云服务器控制台的安全组规则及本机防火墙（如 UFW 或 iptables）中，放行针对 TCP 6806 端口的入站访问；如果你后续打算使用 Nginx 反向代理并配置 HTTPS，只需放行 80 和 443 端口即可。
  • 提前想好一个专属访问授权码：思源 Web 端默认不走传统的“用户名+密码”注册系统，而是通过一个核心鉴权锁——访问授权码（accessAuthCode） 来做身份拦截。建议提前准备一个 12 位以上包含字母与数字的强密码。
如果你是在公网服务器上部署，强烈建议第一步就设置足够复杂的访问授权码。因为思源笔记只要端口暴露在公网，任何人访问 IP:6806 都会看到登录校验入口，强授权码是保护你知识库安全的第一道屏障。

第一步：Docker Compose 部署

  1. 创建项目专属目录

    规范的目录结构能让日后的维护与数据备份变得非常轻松。我们在宿主机创建 siyuan 目录，并在其中放置持久化工作区：

    BASH
    mkdir -p ~/siyuan/workspace
cd ~/siyuan

  2. 编写 docker-compose.yml 配置文件

    在 ~/siyuan 目录下新建 docker-compose.yml 文件：

    BASH
    version: "3.8"

services:
  siyuan:
    image: b3log/siyuan:v3.8.9
    container_name: siyuan
    restart: unless-stopped
    command:
      - "--workspace=/siyuan/workspace/"
      - "--accessAuthCode=请改成你自己的授权码"
    ports:
      - "6806:6806"
    volumes:
      - ./workspace:/siyuan/workspace

  3. 核心配置与参数解析

    这份配置非常简洁，但有两处关键设计决定了整个系统的稳定与安全：

    • 工作区目录（./workspace:/siyuan/workspace）就是全部数据：思源笔记的所有笔记本内容、配置清单、静态资源附件、SQL 缓存以及版本历史，都完整且排他地保存在这个 workspace 目录中。它不依赖外部 MySQL 或 PostgreSQL，真正做到了“数据即目录”。日后无论是整机迁移还是冷备份，只要把这个 workspace 文件夹打包带走，所有笔记毫发无损。
    • 访问授权码（--accessAuthCode）是唯一的锁：在 command 指令中传入的 --accessAuthCode 是保护系统的唯一凭证。首次在浏览器打开服务时，系统会要求你输入此处的授权码，验证成功后才会下发 Cookie 授予读写权限。

  4. 启动容器服务

    检查配置无误后，执行以下命令后台启动容器：

    BASH
    docker compose up -d

    运行 docker compose ps，当看到容器状态显示为 Up 时，说明思源笔记后端已成功初始化并监听在 6806 端口。

思源笔记容器内部默认以非 root 用户权限（用户 ID 1000）运行写入。如果在首次启动时查阅容器日志（docker compose logs -f）遇到类似 permission denied 写入错误，请在宿主机执行 sudo chown -R 1000:1000 ~/siyuan/workspace 为工作区补齐目录读写属主权限。

第二步：解锁访问工作空间

容器成功跑起来之后，打开浏览器，在地址栏输入 http://你的服务器IP:6806。由于在第一步配置了访问授权码，此时系统处于安全锁定状态，页面并不会直接展示工作台，而是会呈现一个简洁清爽的解锁访问校验屏。

在界面中央的密码输入框中，填入刚才在 docker-compose.yml 中配置的 accessAuthCode（访问授权码），然后点击下方的「解锁访问」按钮即可进入系统。如果你是在自己固定的办公电脑或家用设备上访问，强烈建议顺手勾选输入框下方的「记住我 30 天」选项，这样浏览器会写入长效安全 Cookie，接下来一个月内打开网址都能直接进入工作区，省去每次繁琐敲密码的麻烦。

思源笔记解锁访问页
图 2：思源笔记 Web 端解锁访问校验页面（输入访问授权码并可勾选记住我 30 天）
安全提醒：思源笔记的这道访问授权码虽然能挡住公网未授权访问，但它的定位属于轻量级门禁锁。在当前版本的实现中，授权码初始化后会以明文形式直接保存在数据卷工作区目录下的 conf/conf.json 文件中（对应 accessAuthCode 字段）。因此在服务器运维时，请妥善保管好整个持久化 workspace 目录，切勿将配置文件或整包误传到公共 Git 仓库或外部共享盘，避免授权凭证意外泄露。

第三步：新建笔记本和第一篇笔记

解锁进入主控界面后，你会看到一套完全针对知识管理深度打磨的现代化 Web 工作台。思源笔记的核心层级结构非常清晰：从最外层的「工作空间」，向下细分为独立的「笔记本」，笔记本内部容纳层级无限嵌套的「文档」，而文档内部则是由无数个灵活的「内容块」拼装而成。接下来我们花一分钟建一本笔记本，体验第一篇笔记的诞生过程：

  1. 新建专属笔记本

    视线移到左侧边栏顶部的文档大纲树区域，点击工具条上的「新建笔记本」图标（加号按钮）。在弹出的输入框中为你的新笔记本命名，这里我们输入 部署仓演示 并确认。此时左侧边栏就会多出一个以笔记本图标标识的全新分类目录树。

  2. 创建第一篇文档

    鼠标悬浮到刚刚建好的「部署仓演示」笔记本条目上，点击右侧出现的「+」号按钮新建子文档，给文档命名为 演示笔记。完成后中间的主编辑区会自动切换至该文档，光标停在首行正文区域随时准备输入。

  3. 沉浸式体验块级编辑

    在正文区随意敲几行文字、待办列表或者贴一段代码。你会立刻体会到思源笔记最大的特色——一行就是一个独立的块（Block）。当你把鼠标移动到任意一行的左侧边缘时，行首会出现由六个小圆点构成的拖拽手柄（块标）。按住手柄可以像搭积木一样轻松拖动上下调整段落顺序；单机块标还可以呼出该块的专属功能菜单（支持转换为各级标题、生成块超链接、添加引述或嵌入到其他文档）。这种细粒度排版彻底打破了传统线性长文的限制，后续重构知识框架时尤为顺手。

思源笔记演示笔记编辑页
图 3：新建「部署仓演示」笔记本与「演示笔记」正在进行块级内容编辑

踩坑实录

1. 不设授权码等于公网完全裸奔
不少朋友在初次折腾 Docker 配置时，觉得每次输授权码麻烦，索性在启动参数里去掉了 --accessAuthCode。请千万注意：思源笔记容器在没有配置授权码的情况下，公网任何人只要扫到或知道你的服务器 6806 端口，直接就能毫无阻拦地浏览、修改甚至清空你的所有笔记内容！思源本身并不是自带多用户注册系统的博客平台，这道授权码是 6806 端口面对外界唯一且绝对的防盗锁。无论是在家庭宽带打洞还是在云服务器上部署，务必设置高强度的授权码。

2. 自动化脚本与 API 接入报 404：登录接口已改名为 loginAuth
如果你打算编写定时同步脚本、结合浏览器剪藏扩展，或者使用外部程序调用思源丰富的开放 REST API，一定要留意接口更迭。老版本思源的登录接口路径为 /api/system/login，而在较新的稳定版中，该接口已被官方正式重命名为 /api/system/loginAuth，并且底层鉴权逻辑也从原来的直接传参转为更规范的 Cookie 会话机制。如果你从网上抄了较早的 Python 或 Shell 脚本，运行时很可能会遇到 404 找不到端点或 401 未鉴权报错，排查时将请求 URL 更正为 loginAuth 并持久化响应中的 Cookie 即可顺利打通。

3. 内核首次启动用时偏长属正常现象，切莫以为服务崩溃
刚敲完 docker compose up -d 命令的前几十秒甚至一两分钟内，打开浏览器访问有时会遇到页面转圈或连接超时。这是正常表现，并非容器起不来。原因在于思源笔记内核在第一次初始化时，需要在持久化目录中自动生成端对端通讯所需的自签证书文件，并且要对工作空间内置的帮助文档与元数据建立底层的 SQLite 缓存及全文检索索引。遇到这种情况不要急着重启容器，可以在终端执行 docker compose logs -f 观察输出，只要日志里看到内核正在启动的提示，耐心等待片刻，以浏览器最终刷新出解锁授权页面为准。

升级与备份

得益于思源笔记出色的本地优先（Local-first）文件组织架构，后续的版本迭代升级与整机数据迁移格外省心：

平滑滚动升级：
当官方发布新版本镜像时，你无需重新配置复杂的环境变量。只需编辑项目目录下的 docker-compose.yml，将 image: b3log/siyuan:v3.8.9 末尾的版本标签替换为最新的稳定版本号，随后在终端执行以下两条标准命令即可完成升级：

BASH
docker compose pull
docker compose up -d

Docker 会自动拉取最新的镜像文件，并自动停止、重建并拉起新容器。因为所有笔记、配置与插件资产都挂载在宿主机外部，新容器启动后会自动向下兼容读取，几秒钟内便能平滑完成版本更替。

极简整机冷备份：
由于思源笔记完全不依赖外部 MySQL 或复杂数据库集群，你的所有笔记 Markdown 源码、多级块索引、静态图床资源（assets/）、历史版本日志以及个性化配置文件（conf/），全都整整齐齐地收敛在宿主机的 workspace 文件夹里。日常备份只需要对整个目录执行一条简单的打包压缩归档命令：

BASH
tar -czvf siyuan_backup_$(date +%Y%m%d).tar.gz workspace/

你完全可以把这条压缩命令放进系统的 crontab 定时任务中，每天深夜打包一次并同步推送到远程网盘或对象存储。日后哪怕服务器遭遇重置、迁移甚至换新机房，只需把这个压缩包解压回对应目录，重新执行一次 docker compose up -d，整个属于你的知识库大厦就能立刻原地满血复活。