思源笔记是一款块级引用做得非常出色的知识管理工具，虽然官方提供了云端同步服务，但不少用户更希望把工作空间放在自己的服务器上。用Docker部署思源笔记是当前最流行的自托管方案之一，整个流程不复杂，但涉及数据持久化、权限和鉴权几个容易出错的环节。本文从零开始讲解完整部署过程，并把常见误区逐一说明，帮助大家一次部署成功。
一、部署前的环境准备
思源笔记官方镜像对内核版本有一定要求，建议宿主机系统内核不低于3.10，实际生产环境推荐使用Ubuntu 20.04以上或者Debian 11以上的发行版。首先确认Docker已经安装好，执行docker --version能看到版本号即可。如果还没安装，可以用官方脚本一键完成：
curl -fsSL https://get.docker.com | bash systemctl enable --now docker docker --version
其次要想清楚数据放哪里。思源笔记的所有笔记内容都保存在一个工作空间目录里，Docker容器本身是无状态的，一旦容器被删除，没挂载出来的数据就全没了。所以部署前先规划好宿主机目录，比如/siyuan/workspace，并确保该目录的归属用户正确，这是后面避免权限问题的关键伏笔。
另外需要确认端口占用情况。思源默认监听容器内部的6806端口，如果宿主机的6806已被其他程序占用，映射时换成其他端口即可，比如16806。可以用ss -tlnp | grep 6806提前检查。
二、启动容器的完整命令
官方镜像名称是b3log/siyuan，直接从Docker Hub拉取即可。启动命令有几个参数必须理解清楚后再执行，最常用的写法如下：
docker run -d \ --name siyuan \ --restart always \ -p 6806:6806 \ -u 1000:1000 \ -v /siyuan/workspace:/siyuan/workspace \ -e AUTH_CODE=你的访问密码 \ b3log/siyuan \ --workspace=/siyuan/workspace/ \ --accessAuthCode=你的访问密码
逐个解释这些参数。-u 1000:1000指定容器内运行的用户，这个UID要和宿主机上工作空间目录的属主一致，否则容器启动后没有写入权限，界面会一直报错。-v把宿主机目录挂载到容器的/siyuan/workspace，实现数据持久化。AUTH_CODE环境变量和--accessAuthCode参数设置的是浏览器访问时的鉴权码，公网部署时这一项千万不能省，否则任何知道地址的人都能看到你的笔记。
如果想用Docker Compose管理，写成YAML文件更方便后续维护和升级：
version: "3.8"
services:
siyuan:
image: b3log/siyuan
container_name: siyuan
restart: always
ports:
- "6806:6806"
user: "1000:1000"
volumes:
- /siyuan/workspace:/siyuan/workspace
command:
- --workspace=/siyuan/workspace/
- --accessAuthCode=你的访问密码启动后执行docker logs -f siyuan观察日志，看到服务监听信息后，浏览器访问http://服务器IP:6806，输入鉴权码就能进入笔记界面了。客户端可以通过接入自托管服务器的方式连上这个实例，手机端同样支持。
三、常见误区与踩坑提醒
第一个高频坑是权限问题。很多人直接用root创建目录，然后容器用默认用户启动，结果容器内进程写不进工作空间，表现为打开后无法新建文档或者设置保存失败。解决办法很简单：用id -u查一下当前用户的UID，目录用chown -R改成该用户所有，然后启动命令里加-u参数保持一致。
第二个坑是数据备份意识不足。虽然挂载了目录，但磁盘损坏、误删除等风险依然存在。建议定期把工作空间目录打包备份，或者用rclone同步到对象存储。思源笔记也支持在设置里配置S3/WebDAV备份，两者结合更稳妥。
第三个误区是公网裸奔部署。有些人为了图方便不设置访问鉴权码，或者用弱密码，这在公网环境下非常危险。正确的做法是配置鉴权码之外，再套一层反向代理加上HTTPS，例如用Nginx或者Caddy：
siyuan.ippipp.com {
reverse_proxy 127.0.0.1:6806
}第四个坑是升级方式不对。升级时不要直接删掉旧容器重建而不检查数据目录，正确流程是先备份数据，再docker pull b3log/siyuan拉取新镜像，然后删除旧容器并用相同参数重新启动。只要工作空间目录挂载正确，数据不会受影响。如果升级后客户端连接异常，多半是客户端和服务器版本差距过大，把客户端也更新到对应版本即可。
最后一个细节：容器内的时间如果不对，日记类功能的时间戳会错乱，可以在启动时加上-e TZ=Asia/Shanghai环境变量，或者在compose文件里配置tzdata相关挂载，保证时区正确。
四、部署完成后的使用建议
服务跑起来之后，建议第一时间在工作空间设置里确认数据目录路径，并开启定期备份。日常使用中，桌面客户端在设置里选择自托管伺服地址，填入服务器地址和鉴权码就能同步编辑。多设备同时编辑时要留意冲突提示，思源会保留历史版本方便恢复。
性能方面，思源笔记对内存的需求不算高，1核1G的小机器也能流畅跑个人笔记库，但如果文档数量超过几万块、且有多人同时访问，建议给到2G以上内存并使用SSD磁盘，索引重建速度会明显更快。按照以上步骤操作，配合避坑要点，一套属于自己的私有笔记服务就稳定搭建完成了。
Docker部署思源笔记思源笔记教程Docker自托管笔记修改时间：2026-09-13 19:56:49