全程只用 File Station + Container Manager，不需要 SSH、不需要命令行。 适用环境：DSM 7.x / Container Manager 项目部署 / 镜像 b3log/siyuan:latest / command 已带 serve。 示例版本：升级到 v3.8.10（2026-11-10 发布的当前稳定版）

一、升级前先记住三件事

要点 说明
:latest 直接重启不会升级 本地已缓存 b3log/siyuan:latest 时，Container Manager 停止 → 启动大概率复用旧镜像，版本纹丝不动。必须改标签或先删本地镜像。
数据全在 workspace 一个文件夹 思源没有独立的数据库容器。笔记、附件、历史、配置、数据仓库全在 ./workspace 下，备份就是备份这整个目录。
serve 子命令不能删 自 v3.7.0 起内核改用 CLI 子命令架构，缺了 serve 会无限重启并报 unknown flag: --accessAuthCode。另外 v2.10.8 起 Docker 部署强制要求访问授权码，删了内核拒绝启动。

官方 Docker 伺服指南的建议是：升级前先备份工作空间；生产环境固定镜像版本号，确认新版正常后再改版本号升级。这份教程就是按这个思路走的。

⚠️ 本文的 compose 含明文访问授权码，存档或分享给别人前记得先脱敏。

二、步骤一：停止项目

Container Manager → 项目 → siyuan → 右上角「停止」。

两个原因：

  1. 项目运行时 YAML 配置页是只读状态（界面底部会提示「项目运行时，配置为只读状态」），停下才能改；
  2. 停了再复制 workspace，里面 sqlite 和 .sy 文件的状态才是一致的。

是「停止」，不是「删除项目」。

三、步骤二：备份工作空间（File Station）

1. 复制整个 workspace

File Station → 进入思源项目目录（如 docker/siyuan）→ 勾选 workspace 文件夹 → 右键「复制到」另一个共享文件夹，或直接「下载」到电脑。

必须整个文件夹一起复制，里面这些都不能少：

子目录 内容
conf 配置、外观、快捷键
data 笔记本 .sy 文档、assets 附件、模板、挂件、插件、闪卡数据
history 文档历史（明文，可回溯）
repo / temp 数据仓库快照、临时文件

只备份 data、或只备份容器本身，都不算完整备份。

2. 再存一份导出包（双保险）

如果旧版还能打开：思源网页 → 设置 → 导出 → 导出 Data，把 zip 下载到电脑。

升级可能涉及数据结构变化，不要把改回旧镜像标签当成退路。真出问题时，靠的是这份备份重新还原工作空间。

四、步骤三：修改 YAML（只改一行）

点项目里的 YAML 配置 分页 → 全选删除 → 贴入下面整份 → 储存。

services:
  siyuan:
    image: b3log/siyuan:v3.8.10
    container_name: siyuan
    restart: unless-stopped
    ports:
      - "6806:6806"
    volumes:
      - ./workspace:/siyuan/workspace
    environment:
      - TZ=Asia/Shanghai
    command:
      - serve
      - '--workspace=/siyuan/workspace/'
      - '--accessAuthCode=Zcp@66778899'

改动只有一行：

- image: b3log/siyuan:latest
+ image: b3log/siyuan:v3.8.10

写死版本号后，本地没有 v3.8.10 这个标签，启动时 Container Manager 必然去拉新镜像——这一步同时解决了「latest 缓存不更新」的问题。

四个「不要动」

  • 不要删 command 里的 serve：删了容器会无限重启。
  • 不要删 --accessAuthCode：Docker 部署的强制项。
  • 不要动 ./workspace:/siyuan/workspace：数据卷路径，改错等于换了个空笔记库。
  • 不要手痒加 PUID / PGID：原本没设也能正常跑，说明属主本来就是对的，加了反而可能把 workspace 权限搅乱。

--accessAuthCode=Zcp@66778899 里的 @ 用单引号包着，YAML 解析没问题，保持原样即可。

如果你当初是「单容器」而不是「项目」部署

Container Manager → 容器 → siyuan → 编辑 → 把映像标签改成 b3log/siyuan:v3.8.10，其余设置（端口、存储空间、命令）一律照旧。改完同样要先确认本地旧的 latest 镜像已被替换，否则可能还是跑旧版。

如果坚持保留 :latest

那就先到 映像 分页找到本地的 b3log/siyuan:latest → 删除 → 再回项目启动，让它重新拉取。但每次升级都要重复这个动作，不如钉版本号省心，也能避免被自动更新机制推到没读过的版本。

五、步骤四：启动

回项目页 → 启动。

可切到「映像」分页看 v3.8.10 的拉取进度。容器重建时：

  • 只有 siyuan 一个容器被重建
  • ./workspace 数据卷保持原样，笔记不会丢
  • 端口仍是 6806

六、步骤五：验证

  1. Container Manager → 项目 → siyuan →「容器」分页，状态亮绿灯、不是反复 Restarting
  2. 浏览器打开 http://192.168.0.51:6806 → 输入访问授权码
  3. 设置 → 关于，版本应显示 v3.8.10
  4. 逐项检查：笔记本树完整、附件图片能打开、双链与搜索正常、历史记录还在

确认无误后，到「映像」分页删掉旧的 latest 镜像腾空间（不删也不影响运行）。

v3.8.10 值得顺手看一眼的新东西

富文本文档标题、数据库子条目与关联视图、工作空间级 AI 长期记忆、内置轻量 Markdown 编辑器、统一的文档与块面包屑、文档树大目录浏览性能优化、集市兼容性筛选。若主题或插件显示异常，到集市里更新一遍即可，个别老插件可能要等作者适配。

七、常见状况

现象 原因 / 处理
启动后版本还是旧的 本地缓存了 latest 镜像。确认 YAML 里是 v3.8.10；或到「映像」删掉 b3log/siyuan:latest 再启动。
容器反复 Restarting 项目 → 容器 → 「日志」分页看最后几行。出现 unknown flag: --accessAuthCode 就是 serve 被误删，贴回原样。
提示工作空间无写入权限 workspace 属主被改过。检查该文件夹权限（容器默认按 1000:1000 运行），别直接给 777，先确认是不是误加了 PUID/PGID。
网页打不开但容器是绿的 先等 1–2 分钟让内核初始化；仍不行再看日志。反代场景记得 /ws 要开 WebSocket。
集市主题／插件异常 到集市更新插件和主题，用新版提供的「集市兼容性筛选」排查。
升级后想退回旧版 别只改标签回退。这版新增了 AI 长期记忆、数据库子条目等结构，降级有风险；退路是步骤二那份 workspace 备份。

八、以后每次升级的固定套路

  1. 先读目标版本的发布说明，重点看「破坏性变更」和 Docker 相关条目
  2. 停止项目 → File Station 复制整个 workspace → 顺手导出一次 Data
  3. YAML 里把 image 的版本号改成新版本 → 启动
  4. 网页「设置 → 关于」确认版本号，再抽查笔记与附件

版本号可以在 GitHub Releases 或 Docker Hub 的 Tags 页查到。*不要用 `-alpha/-rc/-beta` 这类预发布标签。**

附：本次环境速查

项目 值
项目目录 /volume1/docker/siyuan（相对路径 ./workspace 基于此）
数据目录 workspace（conf / data / history / repo / temp）
挂载 ./workspace → /siyuan/workspace
服务端口 6806 → 6806
镜像 b3log/siyuan，由 latest 改为 v3.8.10
启动命令 serve --workspace=/siyuan/workspace/ --accessAuthCode=Zcp@66778899
时区 TZ=Asia/Shanghai
重启策略 unless-stopped
访问地址 http://192.168.0.51:6806