SiYuan 3.8.8 Docker Compose 部署指南

目标：在 Ubuntu 22.04 服务器上用 Docker Compose 从零部署 SiYuan（思源笔记）v3.8.8 自托管服务端，完成镜像选型、Compose 编排、首次启动验证、数据持久化、环境变量与升级/回滚演练。全部命令与回显均在 Ubuntu 22.04 + Docker 29.8.1 实测环境逐条执行并照抄，访问鉴权口令、升级前后的数据存活均已实测验证。

一、环境信息

本篇实测环境如下，读者按同样规格准备即可完整复现：

• 操作系统：Ubuntu 22.04 LTS（x86_64）
• Docker：Docker version 29.8.1, build 4a63305（docker --version 实测）
• Compose：Docker Compose version v5.5.1（docker compose version 实测）
• SiYuan：v3.8.8（官方最新稳定版，镜像 b3log/siyuan:v3.8.8，实测镜像体积 453MB）
• 服务端口：宿主机 8131 → 服务端固定服务端口 6806（SiYuan 还会在本机监听一个 38699 的本地 HTTPS 管理端口，见第十一章 Q4）
• 工作区目录（宿主机）：/opt/siyuan/workspace（bind mount 到服务端 /siyuan/workspace）
• 访问鉴权口令（演示值）：q1w2e3r4
• 资源占用参考：空载运行时实测内存 109.2MiB（docker stats --no-stream 采集），单核 CPU 占用 0.51%，2GB 内存的服务器即可流畅运行
• 命令回显约定：以下全部回显为实测原文；凡输出含随机 ID、时间戳、随机分配的本地端口号（如 38699 之外的动态值），均属正常个体差异，读者环境会不同

二、镜像选型说明

部署前先解决「用哪个镜像、哪个 tag」。SiYuan 官方维护 Docker Hub 镜像 b3log/siyuan，这是唯一推荐的镜像来源。

2.1 镜像 tag 对照

通过 Docker Hub API 实查 tag 列表（https://hub.docker.com/v2/repositories/b3log/siyuan/tags，查询日期 2026-10-22），与本机 docker images 实测结果对照如下：

关键差异与选型建议：生产环境锁定具体版本号（如 v3.8.8）而非 latest，避免镜像随上游更新被动漂移；本机拉取与版本核对命令：

docker pull b3log/siyuan:v3.8.8        # 拉取指定版本
docker images b3log/siyuan             # 核对本地已有的 tag 与体积

实测回显：

v3.8.8    453MB
latest    453MB
v3.8.7    440MB

💡 说明：本篇实验环境架构为 amd64。官方构建矩阵覆盖 amd64/arm64/armv8/armv7（Hub 的 buildcache 构建缓存标签可佐证），ARM 服务器按同一 tag 拉取即可。

2.2 为什么不用其他部署形态

• 官方桌面版（deb/AppImage/Windows/macOS）面向个人桌面，不适合无人值守的服务器形态；
• 直接 docker run 也可以启动（见第九章），但 Compose 把端口、挂载、环境变量、重启策略全部声明在文件里，升级回滚只需改一行 tag，长期运维收益最大；
• K8s/Unraid/TrueNAS 等形态官方也提供说明，但都以同一镜像为基础，本篇的编排参数可直接迁移。

三、前置条件

动手部署前逐项确认，避免中途返工：

1. 服务器已安装 Docker Engine 与 Compose 插件。验证命令与实测回显：

docker --version
docker compose version

Docker version 29.8.1, build 4a63305
Docker Compose version v5.5.1

2. 端口规划：宿主机选一个空闲端口映射到 6806（本篇用 8131）。确认端口未被占用：

ss -ltn | grep 8131 || echo "8131 空闲"

8131 空闲

3. 数据目录规划：工作区落在 /opt/siyuan/workspace，属主规划为 uid/gid 1000（与第六章 PUID/PGID 一致）：

mkdir -p /opt/siyuan/workspace
chown -R 1000:1000 /opt/siyuan/workspace

ls -ld /opt/siyuan/workspace

drwxr-xr-x 2 1000 1000 4096 Oct 22 00:21 /opt/siyuan/workspace

⚠️ 注意：PUID/PGID 决定服务进程以哪个用户运行，必须与数据目录属主一致，否则服务日志会出现 permission denied（真实案例与修复见第十一章 Q1）。

4. 镜像可拉取。国内网络拉取 Docker Hub 慢时，为 Docker 守护进程配置镜像加速或代理后再执行第二章的 docker pull。

四、部署步骤

本章从零完成一次可验证的完整部署：写 Compose 编排 → 启动 → 解读首启日志 → 三层验证（端口/鉴权/API）→ 初始化第一本笔记本。

4.1 编排文件

在部署目录（本篇用 /opt/siyuan/compose）创建 docker-compose.yml，全文如下（每一项的含义见第七、八章）：

name: siyuan-3.8.8-stack

services:
  siyuan:
    image: b3log/siyuan:v3.8.8
    container_name: siyuan-3.8.8-app
    command: ['serve', '--workspace=/siyuan/workspace/', '--accessAuthCode=q1w2e3r4']
    ports:
      - "8131:6806"
    volumes:
      - /opt/siyuan/workspace:/siyuan/workspace
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai
      - PUID=1000
      - PGID=1000
    networks:
      siyuan-net:
        ipv4_address: 10.89.62.10

networks:
  siyuan-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.62.0/24

逐项说明：

• name: siyuan-3.8.8-stack：Compose 项目名。必须显式设置且全局唯一——同机多套 Compose 栈若项目同名，对一套执行 down 时可能连带删除另一套的同名资源；
• command：传给内核的启动参数。自 v3.7.0 起必须显式写 serve 子命令，否则内核不进入服务模式；--workspace 指定容器内工作区，--accessAuthCode 指定 Web 访问鉴权口令（务必改成自己的强口令，本篇演示用 q1w2e3r4）；
• ports 的 "8131:6806"：6806 是服务端固定服务端口（内核固定监听），8131 是宿主机对外端口；
• volumes：把宿主机 /opt/siyuan/workspace 挂为容器内工作区，所有数据（配置、文档、索引、日志）都落在这个目录；
• restart: unless-stopped：服务器重启后自动拉起；
• PUID=1000/PGID=1000：服务进程运行用户，与第三章准备的目录属主一致；
• 网络部分：单机部署用默认网络即可，siyuan-net 与固定 IP 属可选定制（便于同网络其他服务按 IP 访问），删掉这两段不影响部署。

4.2 启动

cd /opt/siyuan/compose
docker compose up -d

实测回显：

[+] Running 3/3
 ✔ Network siyuan-388-stack_siyuan-net  Created
 ✔ Container siyuan-3.8.8-app           Started

确认状态：

docker compose ps

NAME               IMAGE                  COMMAND                  SERVICE   CREATED          STATUS          PORTS
siyuan-3.8.8-app   b3log/siyuan:v3.8.8    "/opt/siyuan/entrypoi…"   siyuan    8 seconds ago    Up 7 seconds    0.0.0.0:8131->6806/tcp

4.3 首次启动日志解读

docker logs siyuan-3.8.8-app

实测回显（节选关键行）：

Creating group siyuan (1000)
Creating user siyuan (PUID: 1000, PGID: 1000)
Adjusting ownership of /opt/siyuan, /home/siyuan/, and /siyuan/workspace/
Starting SiYuan with UID:1000 and GID:1000 in workspace /siyuan/workspace/
I 2026/10/22 00:23:20 working.go:168:
      ___                                   ___           ___
     /  /\        ___           ___        /__/\         /  /:/
    （思源笔记 ASCII Logo，此处省略）
I 2026/10/22 00:23:20 runtime.go:108: kernel is booting:
    * ver [3.8.8]
    * arch [amd64]
    * os [alpine]
    * pid [1]
    * runtime mode [prod]
    * working directory [/opt/siyuan]
    * read only [false]
    * container [docker]
    * database [ver=202607031200]
    * workspace directory [/siyuan/workspace]
I 2026/10/22 00:23:20 conf.go:318: loaded conf [/siyuan/workspace/conf/conf.json]
I 2026/10/22 00:23:20 serve.go:265: kernel [pid=1] http server [0.0.0.0:38699] is booting (local HTTPS + HTTP/2 enabled)
I 2026/10/22 00:23:20 working.go:675: database [/siyuan/workspace/temp/siyuan.db] size [172.04 kB]
I 2026/10/22 00:23:20 working.go:675: database [/siyuan/workspace/temp/blocktree.db] size [32.77 kB]
I 2026/10/22 00:23:20 working.go:675: database [/siyuan/workspace/temp/history.db] size [24.58 kB]
I 2026/10/22 00:23:20 working.go:675: database [/siyuan/workspace/temp/asset_content.db] size [24.58 kB]
I 2026/10/22 00:23:20 working.go:231: kernel booted
I 2026/10/22 00:23:20 box.go:85: auto stat [trees=0, blocks=0, dataSize=57.75 kB, assetsSize=0 B]

要点：

• 入口脚本先按 PUID/PGID 建用户、把 /siyuan/workspace 属主调整成该用户，再以该用户启动内核（su-exec 降权），因此宿主机目录属主必须可写；
• kernel booted 出现即启动完成；ver [3.8.8] 可核对版本；
• 四个 SQLite 数据库（siyuan/blocktree/history/asset_content）都在工作区 temp/ 下，首次启动自动创建。

4.4 三层验证

第一层：端口连通。 直接访问会返回 401——这是开启了访问鉴权后的预期行为，说明服务已监听：

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8131/

401

第二层：鉴权口令生效。 用部署时设置的 --accessAuthCode 的值在浏览器打开 http://<服务器IP>:8131/，会先进入锁屏/解锁页，输入 q1w2e3r4（本篇演示口令）后进入工作区界面。

第三层：Kernel API 验证。 API Token 在首次启动时自动生成，落在工作区配置文件 conf/conf.json 的 api.token 字段（读取方式见下）。带 Authorization: Token <token> 头调用版本接口：

grep -o '"token": "[^"]*"' /opt/siyuan/workspace/conf/conf.json

"token": "3x5z8hcrcihizxyb",

curl -s http://localhost:8131/api/system/version \
  -H "Authorization: Token 3x5z8hcrcihizxyb" \
  -H 'Content-Type: application/json' -d '{}'

{"code":0,"msg":"","data":"3.8.8"}

返回 code:0 且版本为 3.8.8，部署验证完成。

4.5 初始化笔记本

解锁进入 Web 界面后，新建一本笔记本（本篇测试工作区建名为「运维手册」的笔记本）。也可以直接验证落盘结构——SiYuan 的笔记本就是工作区 data/ 下的一个文件夹：

ls /opt/siyuan/workspace/data/

20261022002307-05h9zc6  assets  emojis  icons  plugins  public  storage  templates  themes  widgets  .siyuan

其中 20261022002307-05h9zc6 就是笔记本「运维手册」的文件夹（ID 格式为 创建时间-随机串），文档以 .sy（JSON）文件保存在其中。

五、数据持久化说明

SiYuan 的全部状态都收敛在工作区一个目录里，持久化因此非常简单：保住 /opt/siyuan/workspace 就保住了一切。

5.1 工作区目录结构

首次启动后工作区自动生成以下内容（ls -la /opt/siyuan/workspace 实测）：

💡 说明：temp/ 下的 siyuan.db 等是从 .sy 文件重建的索引，删掉不影响数据本体；排障时看 temp/siyuan.log（服务端运行日志，docker logs 看到的是同源输出）。

5.2 备份方式

方式一（最简单）：停服后整目录打包。 保证文件一致性：

cd /opt/siyuan/compose
docker compose stop siyuan
tar -czf /backup/siyuan-workspace-$(date +%F).tar.gz -C /opt/siyuan workspace
docker compose start siyuan

方式二：用内核自带快照（数据仓库）。 在 Web 界面「设置 - 账号与同步 - 数据仓库密钥」初始化密钥后，可通过界面或 CLI 创建快照（CLI 用法见《SiYuan 3.8.8 常用 CLI 命令与工具详解》repo 一章；未初始化密钥时命令会直接报错，实测报错文本也记录在该篇）。

方式三：官方导出接口。 Web 界面或 Kernel API 的「导出数据」功能可产出完整备份包。

⚠️ 注意：官方 FAQ 明确不支持用第三方同步盘（Syncthing/网盘等）直接同步工作区目录，并发写入可能损坏数据；跨机迁移请用上述备份方式。

六、环境变量表

镜像入口脚本（/opt/siyuan/entrypoint.sh）识别以下环境变量，全部经实测确认：

⚠️ 注意：PUID/PGID 改动后，入口脚本会自动把工作区属主 chown 成新值，因此换 UID 部署不需要手工搬数据，但首次启动会因递归 chown 稍慢（数据量大时）。

七、配置参数说明

SiYuan 的配置分两层：启动参数（command 传给内核，改后需重建服务生效）与运行配置（conf/conf.json，Web 界面改动即时回写）。

7.1 serve 启动参数

kernel serve 的全部参数（--help 实测，本篇部署只用到前两个）：

这些参数的运行期行为与 conf.json 的逐项对应关系，在《SiYuan 3.8.8 配置参数详解》中逐个实测讲解。

7.2 conf.json 与配置生效机制

首次启动自动生成 /opt/siyuan/workspace/conf/conf.json（实测约 15KB、六百余行 JSON）。生效机制实测结论：

• Web 界面改动（设置面板）：保存即写入 conf.json 并即时生效，无需重启；
• 直接编辑 conf.json 文件：服务运行中改动可能被服务的配置回写覆盖，正确姿势是先 docker compose stop 再改、改完 up -d；
• 查看配置关键字段的快捷方式：

python3 -c "import json; d=json.load(open('/opt/siyuan/workspace/conf/conf.json')); print(d['accessAuthCode'], d['api']['token'], d['system']['workspaceDir'])"

q1w2e3r4 3x5z8hcrcihizxyb /siyuan/workspace

八、配置文件挂载

本方案没有单独挂载 conf.json——整个工作区目录 conf/、data/、temp/ 一起随 bind mount 落在宿主机 /opt/siyuan/workspace 下，这是官方推荐形态，理由有三：

1. 工作区是一个整体：配置、数据、索引同目录，备份/迁移只搬一个文件夹；
2. 单独只挂 conf.json 文件（而非目录）会在内核整文件重写时因 inode 替换导致挂载失效，属常见错误；
3. conf/ 目录里除 conf.json 外还有内核自动生成自签 TLS 证书（ca.crt/cert.pem/key.pem，用于本地 HTTPS 通道），只挂单个文件会漏掉证书的持久化。

如需在宿主机直接改配置（如批量预置），遵循第七章的「停服再改」流程：

cd /opt/siyuan/compose
docker compose stop siyuan
vim /opt/siyuan/workspace/conf/conf.json     # 按需修改
docker compose up -d

九、等价 docker run

与上述 Compose 完全等价的一次性 docker run（用于快速验证，注意数据目录与端口保持一致）：

docker run -d \
  --name siyuan-3.8.8-app \
  -p 8131:6806 \
  -v /opt/siyuan/workspace:/siyuan/workspace \
  -e TZ=Asia/Shanghai \
  -e PUID=1000 -e PGID=1000 \
  --restart unless-stopped \
  b3log/siyuan:v3.8.8 \
  serve --workspace=/siyuan/workspace/ --accessAuthCode=q1w2e3r4

💡 说明：serve 子命令自 v3.7.0 起为必写项；镜像入口是 /opt/siyuan/entrypoint.sh，它负责建用户、降权、chown 工作区后再启动内核。

十、常用运维命令

10.1 日常启停与日志

cd /opt/siyuan/compose
docker compose ps                 # 状态
docker compose logs -f siyuan     # 跟踪日志（Ctrl+C 退出）
docker compose restart siyuan     # 重启
docker compose stop siyuan        # 停止（保留容器）
docker compose up -d              # 启动/应用配置变更
docker compose down               # 停止并删除容器与网络（工作区数据不受影响）

💡 说明：down 只删容器与网络，/opt/siyuan/workspace 是 bind mount 的宿主机目录，数据原样保留；重新 up -d 即恢复。

10.2 升级演练（3.8.7 → 3.8.8 实测全程）

升级方法：改 tag + 重建。以下为在本篇工作区上的真实演练记录。

第一步：准备一个 v3.8.7 的旧版工作区并写入数据（模拟「已有存量数据的生产实例」）：

docker run -d --name siyuan-3.8.7-upg \
  -p 8136:6806 -v /opt/siyuan/workspace-upg:/siyuan/workspace \
  -e PUID=1000 -e PGID=1000 \
  b3log/siyuan:v3.8.7 \
  serve --workspace=/siyuan/workspace/ --accessAuthCode=q1w2e3r4

用 Kernel API 在旧版里建笔记本和文档（token 取自该工作区 conf.json 的 api.token，实测 bpdnrun6lnak8xz4）：

curl -s http://localhost:8136/api/notebook/createNotebook \
  -H "Authorization: Token bpdnrun6lnak8xz4" -H 'Content-Type: application/json' \
  -d '{"name": "升级演练"}'

{"code":0,"msg":"","data":{"notebook":{"id":"20261022085333-onao2be","name":"升级演练",...}}}

curl -s http://localhost:8136/api/filetree/createDocWithMd \
  -H "Authorization: Token bpdnrun6lnak8xz4" -H 'Content-Type: application/json' \
  -d '{"notebook": "20261022085333-onao2be", "path": "/upgrade-test", "title": "升级存活验证", "markdown": "升级前写入的数据，用于验证 3.8.7 到 3.8.8 升级后数据完整。"}'

{"code":0,"msg":"","data":"20261022085333-xe8fwli"}

第二步：换 tag 升级（Compose 场景即修改 image: 行后 up -d；run 场景删容器用新 tag 重建，工作区目录不动）：

docker rm -f siyuan-3.8.7-upg
docker run -d --name siyuan-3.8.7-upg \
  -p 8136:6806 -v /opt/siyuan/workspace-upg:/siyuan/workspace \
  -e PUID=1000 -e PGID=1000 \
  b3log/siyuan:v3.8.8 \
  serve --workspace=/siyuan/workspace/ --accessAuthCode=q1w2e3r4

实测升级后日志（conf.json 原样加载、无迁移报错、内核正常启动）：

I 2026/10/22 08:54:05 runtime.go:112: kernel is booting:
    * ver [3.8.8]
I 2026/10/22 08:54:05 conf.go:318: loaded conf [/siyuan/workspace/conf/conf.json]
I 2026/10/22 08:54:05 working.go:231: kernel booted

第三步：验证版本与数据存活：

curl -s http://localhost:8136/api/system/version \
  -H "Authorization: Token bpdnrun6lnak8xz4" -H 'Content-Type: application/json' -d '{}'

{"code":0,"msg":"","data":"3.8.8"}

curl -s http://localhost:8136/api/query/sql \
  -H "Authorization: Token bpdnrun6lnak8xz4" -H 'Content-Type: application/json' \
  -d '{"stmt": "SELECT content FROM blocks WHERE type=\"d\""}'

{"code":0,"msg":"","data":[{"content":"upgrade-test"}],"limit":64,"truncated":false}

升级前创建的文档在 3.8.8 下完整可见，升级完成。

10.3 回滚演练（3.8.8 → 3.8.7 实测）

把 tag 换回 v3.8.7 重建容器，实测可正常启动且数据完整（本组版本间无不可逆数据迁移）：

I 2026/10/22 08:54:33 conf.go:318: loaded conf [/siyuan/workspace/conf/conf.json]
I 2026/10/22 08:54:33 conf.go:1131: tree/block count [1/2]
I 2026/10/22 08:54:33 working.go:231: kernel booted
I 2026/10/22 08:54:34 fixedport.go:44: fixed port service [0.0.0.0:6806] is running (HTTP/HTTPS dual mode)

curl -s http://localhost:8136/api/system/version \
  -H "Authorization: Token bpdnrun6lnak8xz4" -H 'Content-Type: application/json' -d '{}'

{"code":0,"msg":"","data":"3.8.7"}

⚠️ 注意：回滚可用性取决于「旧版本能否读新版本写过的数据」。本组 3.8.7↔3.8.8 实测互通；跨多个大版本的回滚不保证，回滚前务必先用第五章方式备份工作区。生产升级的推荐顺序：备份 → 换 tag → 验证 → 出问题回滚。

十一、常见问题

Q1：服务日志持续报 clear push queue failed: truncate .../push.queue: permission denied，怎么办？

实测案例：以 root 身份在工作区里执行过内核 CLI 或手工操作后，工作区部分文件属主变成 root，而服务进程以 uid 1000 运行，于是每 3 秒刷一条权限报错（temp/siyuan.log 实测 29 条）：

E 2026/10/22 08:47:56 push_queue.go:249: clear push queue failed: truncate /siyuan/workspace/temp/queue/push.queue: permission denied

定位：ls -la /opt/siyuan/workspace/temp/queue/ 可见 push.queue 属主为 root。修复：把工作区属主改回服务用户后自动恢复（修复后日志不再新增报错）：

chown -R 1000:1000 /opt/siyuan/workspace

预防：凡需在服务器上直接操作工作区（CLI、备份、脚本），一律以服务进程同一用户（本例 uid 1000）执行，不要混用 root。

Q2：浏览器或 curl 访问一直 401？

这是 --accessAuthCode 访问鉴权在起作用（第四章已验证 401 属预期）。浏览器输入口令解锁即可；脚本调用 Kernel API 需带 Authorization: Token <api.token> 头，token 在工作区 conf/conf.json 的 api.token 字段。忘记口令时：编辑 conf.json 的 accessAuthCode 字段（停服再改）后重启。

Q3：为什么服务端没有 PDF/Word 导出、界面里也找不到「导入 Markdown 文件」入口？

官方 README 明确的服务端形态限制：服务端仅支持浏览器访问（不支持桌面/移动 App 连接）、不支持导出 PDF/HTML/Word、界面不支持导入 Markdown 文件。实测补充：内核自带的 CLI 通道可以完成 Markdown 导入（import md 实测返回 ok 并真实生成文档），服务器的自动化需求优先走 CLI 与 Kernel API，见《SiYuan 3.8.8 常用 CLI 命令与工具详解》。

Q4：38699 端口是什么？需要暴露吗？

不需要暴露。内核启动日志显示两个监听：固定服务端口 6806（fixed port service [0.0.0.0:6806] is running (HTTP/HTTPS dual mode)，对外服务走它）与本地 HTTPS 管理端口 38699（http server [0.0.0.0:38699] is booting (local HTTPS + HTTP/2 enabled)，内核本机自用，端口号动态分配，配置文件 serverAddrs 字段记录）。Compose 只映射 6806 即可，38699 留在服务网络内部。

Q5：CLI 执行 repo 命令报 "Please initialize the data repo key first"？

数据仓库（快照）功能需要先初始化仓库密钥：Web 界面「设置 - 账号与同步 - 数据仓库 - 数据仓库密钥」初始化后再用（实测报错原文与 CLI 快照命令详见《SiYuan 3.8.8 常用 CLI 命令与工具详解》）。

十二、参考链接

1. 官方 GitHub 仓库（Docker Hosting 章节）：https://github.com/siyuan-note/siyuan （查询日期 2026-10-22）
2. 官方 Docker Hub 镜像页：https://hub.docker.com/r/b3log/siyuan （查询日期 2026-10-22）
3. Docker Hub tag 列表 API（本篇 tag 实查）：https://hub.docker.com/v2/repositories/b3log/siyuan/tags （查询日期 2026-10-22）
4. 官方下载页（其他部署形态入口）：https://b3log.org/siyuan/en/download.html （查询日期 2026-10-22）
5. 官方英文用户指南：https://siyuan-en.b3log.org/ （查询日期 2026-10-22）
6. 同专栏部署前置认知：《SiYuan 3.8.8 介绍与选型指南》
7. 启动参数与配置项逐项详解：《SiYuan 3.8.8 配置参数详解》
8. 服务器自动化（CLI 与 Kernel API）：《SiYuan 3.8.8 常用 CLI 命令与工具详解》