🚀 使用 Docker Compose 部署 Siyuan（思源笔记）

🚀 使用 Docker Compose 部署思源笔记

思源笔记是一款隐私优先的个人知识管理系统，支持完全离线使用，同时也支持端到端加密同步。它融合块、大纲和双向链接，帮助你有效重构和梳理思维。

下面将详细介绍如何使用 Docker Compose 部署思源笔记。

📦 项目简介

思源笔记的核心特点可以概括为下表：

特点类别	具体说明
编辑体验	支持所见即所得的 Markdown 编辑，融合块、大纲和双向链接，重构你的思维。
隐私与同步	采用隐私优先的设计，支持完全离线使用，同时也支持端到端加密同步。
数据存储	数据保存在工作空间文件夹下，`assets` 文件夹保存所有插入的资源文件，用户创建的笔记本文件夹下 `.sy` 后缀的文件用于保存文档数据。
部署方式	支持 Docker 部署，便于跨平台使用和数据集中管理。

📋 部署前准备

1.环境要求确保你的服务器已安装 Docker 和 Docker Compose。

2.资源检查 * 端口：确认 6806 端口未被其他程序占用。 * 磁盘空间：确保挂载目录（如示例中的 ./siyuanworkspace）有足够空间存储笔记数据。 * 权限：确保当前用户对挂载目录有读写权限。

⚙️ 配置 Docker Compose

1.创建项目目录创建一个目录（如 siyuan）用于存放所有相关文件，并进入该目录。

    mkdir -p /path/to/your/siyuan && cd /path/to/your/siyuan

2.创建 docker-compose.yml 文件将以下配置内容保存到新创建的 docker-compose.yml 文件中。此配置定义了思源笔记服务。

#version: '3'
services:
  siyuan:
    image: b3log/siyuan   # 官方最新镜像
    container_name: siyuan  # 容器名称，便于管理
    restart: always  # 容器退出后自动重启，保障服务稳定
    volumes:
      # 数据持久化：本地 ./siyuanworkspace → 容器 /siyuanworkspace（存储所有笔记）
      - ./siyuanworkspace:/siyuanworkspace
    command: [--workspace=/siyuanworkspace,--accessAuthCode=xxxxxx,--lang=zh_CN]
    #命令：[--工作空间=/siyuan工作空间，--访问授权码=xxxxxx，--lang=zh_CN]
    # 1.指定工作目录（与挂载路径一致）2. 必须修改！访问授权码（如 8位数字+字母，用于登录验证，如 Siyuan@2024）登录时需输入此码验证。3. 强制中文界面（可选，默认自动识别）
    network_mode: "host"  # 主机网络模式：直接使用主机端口（6806），无需端口映射
    # 若不使用 host 模式，可注释上方并启用下方端口映射（需确保端口未被占用）
    #ports:
      #- 6806:6806 

#"/home/compose/siyuan/siyuanworkspace/data＆conf"设定的路径链接下工作目录"data"给备份下来，多端同步就好了
#同步软件来搞定，每个客户端都安装一个，路径也同步相同的存放路径＋双向备份＆双向同步。

3.关键配置说明 * 镜像：b3log/siyuan 是思源笔记的官方 Docker 镜像。 * 数据持久化：volumes 部分将容器内的 /siyuanworkspace 目录挂载到宿主机的 ./siyuanworkspace 目录，防止容器重启后数据丢失。 * 网络模式：network_mode: "host" 表示容器使用宿主机的网络，这样可以避免端口映射的麻烦。如果希望使用桥接网络，可以注释掉该行，并取消注释 ports 部分，将宿主机端口映射到容器的 6806 端口。 * 命令参数： * --workspace=/siyuanworkspace：指定工作空间路径，务必与挂载的容器内路径一致。 * --accessAuthCode=xxxxxx：设置访问授权码（登录密码），请务必修改 xxxxxx 为强密码。 * --lang=zh_CN：设置界面语言为中文。

🚀 启动与验证

1.启动服务在 docker-compose.yml 文件所在目录下，执行以下命令来后台启动服务：

    docker-compose up -d

2.检查服务状态使用以下命令查看容器是否正常运行：

    docker-compose ps

如果状态（`State`）栏显示为 `Up`，则表明容器已成功启动。

3.查看日志如果容器启动异常，可以通过日志来排查问题：

    docker-compose logs siyuan

4.访问服务在浏览器中输入 http://你的服务器IP:6806。如果看到思源笔记的登录界面，说明服务已成功部署。使用配置的授权码（密码）登录即可。

🔧 基础配置与使用

初始登录
- 在浏览器中访问 http://你的服务器IP:6806。
- 输入在 docker-compose.yml 中通过 --accessAuthCode 参数设置的授权码（密码）进行登录。
界面语言设置
- 如果启动参数中未设置 --lang=zh_CN，登录后可以点击左上角头像，进入"设置" > "外观"，在"语言"选项中选择"简体中文"。
数据同步方案
- 你可以使用第三方同步软件（如 Syncthing、Resilio Sync 等）同步思源笔记的工作空间目录（例如 /home/compose/siyuan/siyuanworkspace）。
- 在工作空间 data 文件夹下，assets 文件夹保存所有插入的资源文件，其余文件夹是用户自己创建的笔记本文件夹。确保同步软件能正确同步这些内容。
- 建议在所有安装思源笔记（桌面版、移动端或 Docker 服务端）的设备上，设置相同的工作空间路径，并通过同步软件实现该路径的双向同步，这样可以实现多端数据一致。

🔧 基础配置与使用2

Siyuan 的核心操作是 “创建笔记→建立关联→多端同步”，新手可按以下步骤快速上手：

1. 步骤 1：创建与编辑笔记

1.点击左侧 “+” 图标 → 选择 “新建文档”； 2.输入标题（如 “我的第一篇笔记”），按回车创建； 3.在编辑区输入内容（支持 Markdown 语法）：

    # 标题
    这是一段正文，支持 **加粗**、*斜体*、`代码块`。

    ## 块引用示例
    选中一段文字，按 `Ctrl+[` 可转为块引用，支持跨笔记引用：
    > 这是一个块引用，可被其他笔记引用

4.内容会自动保存（实时写入 siyuanworkspace 目录）。

2. 步骤 2：使用双链与块引用（核心功能）

双链：在笔记中输入 [[ 触发搜索，输入已有笔记标题（如 “测试笔记”），生成链接，点击可跳转；
块引用：鼠标悬停在段落左侧，点击 “⊕” 图标复制块 ID，在其他笔记中粘贴 ((块ID)) 即可引用该段落，原内容修改后引用处同步更新。

3. 步骤 3：多端同步与备份

Siyuan 依赖目录同步实现多端访问，推荐通过同步工具将 siyuanworkspace 目录同步到其他设备：

1.备份核心数据：siyuanworkspace/data 目录存储所有笔记内容，定期复制该目录到外部存储（如 U 盘、云盘）； 2.多端同步方法： - 在其他设备安装同步工具（如 Syncthing），将服务器的 siyuanworkspace 目录与本地目录双向同步； - 同步完成后，在本地通过 Docker 部署 Siyuan 或直接使用桌面客户端打开同步后的目录，实现多端实时编辑。

4. 步骤 4：界面个性化设置

点击右上角头像 → “设置”，可配置：

主题：切换浅色 / 深色模式；
编辑器：设置默认格式（如默认标题级别、行高）；
快捷键：自定义常用操作的快捷键（如新建笔记、块引用）。

🔄 维护与管理

1.更新服务当有新版本发布时，可以按以下步骤更新：

    # 进入 docker-compose.yml 所在目录
    cd /path/to/your/siyuan
    # 停止并移除当前容器
    docker-compose down
    # 拉取最新的思源笔记镜像
    docker-compose pull
    # 重新创建并启动容器
    docker-compose up -d
    # 清理无用的旧镜像
    docker image prune

2.数据备份 * 思源笔记的所有数据都保存在工作空间目录（示例中为 ./siyuanworkspace）下。 * 定期备份整个工作空间目录即可备份所有笔记数据。 * 可以使用 tar 或 zip 命令将工作空间目录打包备份到其他安全位置。

3.服务卸载如需卸载思源笔记，在项目目录下执行：

    docker-compose down

如果希望**彻底删除所有数据**（包括笔记数据），在上述命令后移除挂载的目录即可。

🐛 常见问题排查

问题现象	可能原因与解决方案
容器启动失败	1. 检查 `docker-compose.yml` 文件语法是否正确。 2. 执行 `docker-compose logs siyuan` 查看具体错误日志。
无法访问网页	1. 确认服务器防火墙是否开放了 `6806` 端口。 2. 检查 `docker-compose ps` 确认容器是否在运行状态。
通过域名反代后卡在加载界面	使用 Nginx 反向代理时，必须在配置文件中添加 WebSocket 反向代理设置： `location /ws {` `proxy_pass http://127.0.0.1:6806;` `proxy_http_version 1.1;` `proxy_set_header Upgrade $http_upgrade;` `proxy_set_header Connection "upgrade";` `}`
登录授权失败	1. 检查登录时输入的授权码是否与 `docker-compose.yml` 中 `--accessAuthCode` 参数设置的一致。 2. 授权码建议使用强密码，避免使用简单密码。
数据同步冲突	1. 确保同步软件正确同步了工作空间下的所有文件。 2. 如果同时修改了同一文档，可能会产生冲突，请注意协调。

希望这篇教程能帮助你顺利搭建属于自己的思源笔记服务！如果在部署过程中遇到更多问题，思源笔记的官方文档和用户社区是寻求帮助的好去处。

🐛 常见问题排查2

1. 登录失败（提示 “授权码错误”）

原因 1：输入的授权码与 --accessAuthCode 不一致。解决：确认配置中的授权码，注意区分大小写（如 Siyuan123 与 siyuan123 不同）。
原因 2：配置文件修改后未重启容器。解决：执行 docker compose restart 重启服务，使新授权码生效。

2. 笔记无法保存（提示 “权限不足”）

原因：siyuanworkspace 目录权限不足，容器无法写入文件。

解决：重新赋予权限：sudo chmod -R 777 ./siyuanworkspace，重启容器后测试保存。

3. 网页界面加载缓慢或卡顿

原因 1：服务器内存不足（尤其同时打开多个大笔记时）。解决：关闭不必要的容器或进程，释放内存（建议服务器内存 ≥1GB）。
原因 2：浏览器缓存问题。解决：清除浏览器缓存（Ctrl+Shift+Delete），重新访问页面。

4. 多端同步后笔记冲突（内容不一致）

原因：多设备同时编辑同一笔记，同步时未正确合并。

解决： 1. 优先使用 “块级编辑”（减少整页冲突）； 2. 同步前确保所有设备已提交修改，避免同时编辑； 3. 冲突时以服务器端数据为准，手动合并本地修改。

5. 容器启动后无法访问（端口正确但无响应）

原因：network_mode: host 模式下，服务器防火墙未开放 6806 端口。

解决： 1. 检查防火墙规则：sudo ufw status，确认 6806 端口已允许； 2. 若使用云服务器，检查安全组是否开放 6806 端口。

通过以上步骤，新手可快速部署思源笔记并实现本地化知识管理。Siyuan 适合注重数据隐私的用户，结合同步工具可兼顾多端访问需求，后续可探索插件扩展（如思维导图、流程图），具体参考思源笔记官方文档。