在 Ubuntu 上使用 Docker 部署思源笔记：一份详尽的实践教程以及常见错误汇总

一、 准备工作 (Prerequisites)

在开始之前，请确保您拥有：

1. 一台 Ubuntu 服务器（云服务器或本地虚拟机均可）。
2. 拥有服务器的 root 或 sudo 权限。
3. 服务器上已经安装好了 Docker。

如果您的服务器尚未安装 Docker，可以执行以下命令进行安装：

# 更新软件包列表
sudo apt update# 安装 Docker 及其依赖
sudo apt install -y docker.io# 启动 Docker 服务并设置为开机自启
sudo systemctl start docker
sudo systemctl enable docker

二、 一步到位：最终部署命令

对于已经熟悉 Docker 的朋友，可以直接使用下面这行最终的、正确的命令来启动思源笔记。

操作须知：
请将命令末尾的 your_very_secret_password 替换成您自己想设置的密码。这个密码是您首次访问思源笔记时需要输入的“访问授权码”。

docker run -d \--name siyuan \-p 6806:6806 \-v ~/siyuan/data:/siyuan/workspace \b3log/siyuan \--workspace /siyuan/workspace \--accessAuthCode=your_very_secret_password

命令参数详解：

• docker run -d: 在后台（detached mode）运行一个新的容器。
• --name siyuan: 为容器指定一个唯一的名称 siyuan，方便后续管理。
• -p 6806:6806: 将服务器的 6806 端口映射到容器的 6806 端口。
• -v ~/siyuan/data:/siyuan/workspace: 这是最关键的一步。它将您服务器用户主目录下的 siyuan/data 文件夹挂载到容器内部的 /siyuan/workspace 目录。您的所有笔记数据都会保存在服务器的这个文件夹里，实现了数据与程序的解耦，即使容器被删除，数据依然安全。
• b3log/siyuan: 指定使用的 Docker 镜像。
• --workspace /siyuan/workspace: 告知思源笔记程序在容器内的哪个目录存放数据。
• --accessAuthCode=...: 设置首次访问的授权码（密码）。

命令执行成功后，稍等片刻，在浏览器中打开 http://<您的服务器IP地址>:6806，输入您设置的密码，即可开始使用。

三、 常见问题排查 (Troubleshooting)

如果您在访问时遇到问题，或者想了解我们是如何从失败的尝试中得到上面那条最终命令的，这部分内容至关重要。

问题一：浏览器显示“无法访问此页面”或“连接被拒绝”

这是最常见的问题，通常意味着服务没有正常运行或网络不通。

1. 排查思路：检查容器是否正在运行
   执行命令 docker ps -a 查看所有容器的状态。

   如果 STATUS 列显示 Exited，说明容器启动后异常退出了，服务自然无法访问。请直接跳到 问题二。
   

   如果 STATUS 列显示 Up，说明容器正在运行，问题很可能出在网络防火墙上。

2. 解决方案：检查防火墙

   • 云服务商安全组：登录您的云服务提供商（如阿里云、腾讯云、AWS）的控制台，找到您服务器对应的“安全组”或“防火墙”规则，确保 入站规则 已经放行了 TCP 协议的 6806 端口。这是新手最容易忽略的地方。
   • 服务器系统防火墙：如果您在服务器上启用了 ufw 等防火墙，也需要放行该端口 (sudo ufw allow 6806)。

问题二：容器状态为 Exited（已退出）

这说明容器启动失败了，我们需要查看日志来找出失败的原因。

1. 排查思路：查看容器日志
   执行 docker logs <容器名> 命令。

   docker logs siyuan
   

2. 根据日志解决问题（两种典型错误）

   • 错误日志 1：“No such file or directory”
     

     **原因**：这通常是因为 `-v` 参数中，主机目录挂载到了容器内的一个不被启动脚本预期的路径。
     **解决方案**：确保 `-v` 参数的容器内路径与 `--workspace` 参数指定的路径一致，官方镜像推荐使用 `/siyuan/workspace`。

   • 错误日志 2：“access authorization code … must be set”
     

     原因：出于安全考虑，Docker 部署时强制要求设置一个访问密码。
     解决方案：在 docker run 命令的末尾加上 --accessAuthCode=<你的密码> 参数。

问题三：访问授权码（密码）不正确

如果您确定容器正在运行 (STATUS 为 Up)，但输入密码提示错误。

1. 排查思路：再次查看日志
   执行 docker logs siyuan，您可能会在日志末尾看到这样的记录：
   

   W 2025/10/28 10:59:19 session.go:113: invalid auth code [ip=...]
   

   这明确表示服务正在运行，但收到了错误的密码。

2. 解决方案：使用确定的密码重建容器
   最简单直接的方法就是删除旧容器，用一个您百分百确定的密码重新创建一个。详情请看下一章节。

四、 日常维护：如何修改密码与更新版本

1. 如何修改访问授权码？

修改密码需要重建容器，因为密码是在启动时传入的。

# 第一步：停止并删除当前容器
docker stop siyuan
docker rm siyuan# 第二步：使用你的新密码，执行完整的 docker run 命令
docker run -d --name siyuan -p 6806:6806 -v ~/siyuan/data:/siyuan/workspace b3log/siyuan --workspace /siyuan/workspace --accessAuthCode=your_new_password

2. 如何更新思源笔记版本？

Docker 让升级变得异常简单。

# 第一步：拉取最新的镜像
docker pull b3log/siyuan# 第二步：停止并删除旧版容器
docker stop siyuan
docker rm siyuan# 第三步：使用与之前完全相同的 docker run 命令启动新版容器
# 它会自动使用您本地最新的镜像
docker run -d --name siyuan -p 6806:6806 -v ~/siyuan/data:/siyuan/workspace b3log/siyuan --workspace /siyuan/workspace --accessAuthCode=<你之前的密码>

由于您的数据都在 -v 参数指定的 ~/siyuan/data 文件夹里，所以升级过程不会对您的笔记造成任何影响。