siyuan

概述

在服务器上伺服思源最简单的方案是通过 Docker 部署。

• 镜像名称 b3log/siyuan
• 镜像地址

文件结构

整体程序位于 /opt/siyuan/ 下，基本上就是 Electron 安装包 resources 文件夹下的结构：

• appearance：图标、主题、多语言
• guide：帮助文档
• stage：界面和静态资源
• kernel：内核程序

启动入口

入口点在构建 Docker 镜像时设置：ENTRYPOINT ["/opt/siyuan/entrypoint.sh"]。该脚本允许更改将在容器内运行的用户的 PUID 和 PGID。这对于解决从主机挂载目录时的权限问题尤为重要。PUID 和 PGID 可以作为环境变量传递，这样在访问主机挂载的目录时就能更容易地确保正确的权限。

使用 docker run b3log/siyuan 运行容器时，请指定以下参数：

• --workspace：指定工作空间文件夹路径，在宿主机上通过 -v 挂载到容器中
• --accessAuthCode：指定锁屏密码

注意： 自 v3.7.0 起，必须显式传入 serve 子命令（例如 docker run b3log/siyuan serve --workspace=...）。运行 docker run --rm b3log/siyuan serve --help 可查看全部伺服参数。

更多的参数可参考 --help。下面是一条启动命令示例：

docker run -d
  -v workspace_dir_host:workspace_dir_container \
  -p 6806:6806 "}
  -e PUID=1001 -e PGID=1002 "}
  -e SIYUAN_LANG=zh-CN \
  b3log/siyuan \
  serve \
  --workspace=workspace_dir_container \
  --accessAuthCode=xxx

• PUID: 自定义用户 ID（可选，如果未提供，默认为 1000）
• PGID: 自定义组 ID（可选，如果未提供，默认为 1000）
• workspace_dir_host：宿主机上的工作空间文件夹路径
• workspace_dir_container：容器内工作空间文件夹路径，和后面 --workspace 指定成一样的
  • 另外，也可以通过 SIYUAN_WORKSPACE_PATH 环境变量设置路径。如果两者都设置了，命令行的值将优先
• accessAuthCode：锁屏密码，请务必修改，否则任何人都可以读写你的数据
  • 另外，也可以通过 SIYUAN_ACCESS_AUTH_CODE 环境变量设置锁屏密码。如果两者都设置了，命令行的值将优先
  • 可通过设置环境变量 SIYUAN_ACCESS_AUTH_CODE_BYPASS=true 禁用锁屏密码
• SIYUAN_LANG：界面语言（可选，Docker 下未设置时默认为 en）。接受 BCP 47 标签如 zh-CN/zh-TW/en/ja/pt-BR；旧下划线值如 zh_CN/en_US 也兼容。若希望设置中选择的语言在重启后仍生效，部署时请去掉该变量；若设置了，每次启动都会应用该值并覆盖已保存的语言设置
  • 也可通过 --lang 命令行参数设置。如果两者都设置了，命令行的值将优先

为了简化，建议将 workspace 文件夹路径在宿主机和容器上配置为一致的，比如将 workspace_dir_host 和 workspace_dir_container 都配置为 /siyuan/workspace，对应的启动命令示例：

docker run -d
  -v /siyuan/workspace:/siyuan/workspace \
  -第6806页：6806 \
  -e PUID=1001 -e PGID=1002 "}
  -e SIYUAN_LANG=zh-CN \
  b3log/siyuan \
  serve \
  --workspace=/siyuan/workspace/ \
  --accessAuthCode=xxx

Docker 组合

对于使用 Docker Compose 运行思源的用户，可以通过环境变量 PUID 和 PGID 来自定义用户和组的 ID。下面是一个 Docker Compose 配置示例：

版本: "3.9"
服务：
  主体：
    image： b3log/siyuan 命令： ['serve'， '--workspace=/siyuan/workspace/'， '--accessAuthCode=${AuthCode}']
    移植版本：
      - 6806:6806
    卷:
      - /siyuan/workspace:/siyuan/workspace 重启: 除非停止 环境:
      - TZ=${YOUR_TIME_ZONE}    # 时区标识符列表见 https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
      - PUID=${YOUR_USER_PUID}  # 自定义用户 ID
      - PGID=${YOUR_USER_PGID}  # 自定义组 ID
      - SIYUAN_LANG=zh-CN       # 界面语言（与本文档一致）

在此设置中：

• PUID “和 ”PGID "是动态设置并传递给容器的
• 如果没有提供这些变量，则使用默认的 1000

在环境中指定 PUID 和 PGID 后，就无需在 compose 文件中明确设置 user 指令（user: '1000:1000'）。容器将在启动时根据这些环境变量动态调整用户和组。

用户权限

在镜像中，“entrypoint.sh ”脚本确保以指定的 “PUID ”和 “PGID ”创建 “siyuan ”用户和组。因此，当主机创建工作区文件夹时，请注意设置文件夹的用户和组所有权，使其与计划使用的 PUID 和 PGID 匹配。例如

chown -R 1001:1002 /siyuan/workspace

如果使用自定义的 PUID 和 PGID 值，入口点脚本将确保在容器内创建正确的用户和组，并相应调整挂载卷的所有权。无需在 docker run 或 docker-compose 中手动传递 -u，因为环境变量会处理自定义。

隐藏端口

使用 NGINX 反向代理可以隐藏 6806 端口，请注意：

• 配置 WebSocket 反代 /ws
• 普通请求和 /ws 的反向代理都需要保留原始 Host 请求头及端口，在 NGINX 的两处代理配置中均设置 proxy_set_header Host $http_host;。使用 $host 会丢失非标准端口（如 8443），可能导致来源校验失败，表现为登录后停留在 LOGO 并反复刷新、接口返回 401 或 WebSocket 连接失败

注意

• 请务必确认挂载卷的正确性，否则容器删除后数据会丢失
• 不要使用 URL 重写进行重定向，否则鉴权可能会有问题，建议配置反向代理

限制

• 不支持桌面端和移动端应用连接，仅支持在浏览器上使用
• 不支持导出 PDF、HTML 和 Word 格式
• 不支持导入 Markdown 文件

HelmForge 思源 Chart 由 HelmForge 社区维护，使用官方 b3log/siyuan 镜像，并非思源官方 Chart。Chart 相关问题请反馈至 HelmForge。

准备好 Helm、kubectl，以及默认 StorageClass 能够动态创建 10Gi ReadWriteOnce 存储卷的 Kubernetes 集群后，执行以下命令：

helm 仓库添加 helmforge  https://repo.helmforge.dev
helm 仓库更新 helm 安装 siyuan helmforge/siyuan --namespace siyuan --create-namespace --wait kubectl -n siyuan 获取 secret siyuan-siyuan-auth -o go-template='{{index .data "access-code" | base64decode}}{{"
"}}'
kubectl -n siyuan port-forward service/siyuan-siyuan 6806:6806

打开 http://localhost:6806，输入生成的锁屏密码。请妥善保管该密码；它与 API Token 不同。以上资源名称以 Chart 默认配置和 Helm 实例名称 siyuan 为前提。

远程访问时，请使用独立的 HTTPS 域名，以及支持代理 /ws WebSocket 连接的 Ingress 控制器，不要进行 URL 重写。配置 ingress，并通过 networkPolicy.ingressFrom 允许控制器所在命名空间的流量；默认策略仅允许同命名空间的入站流量和 DNS 出站流量。云端同步等外部服务需要显式配置出站规则。TLS、现有 Secret 和存储配置请参阅 Chart 指南及生产环境示例。

• 一个工作区只能有一个写入实例： 不要增加副本数，也不要将同一工作区挂载到另一个运行中的实例，即使使用 ReadWriteMany 存储也不例外。Chart 使用 Recreate 策略，升级时会先停止旧实例，再启动新实例，因此会有服务中断。
• 持久化： 完整工作区挂载在 /siyuan/workspace。默认情况下，卸载 Chart 会保留其创建的 PVC，但删除命名空间或 PVC 仍可能导致数据丢失。可通过 persistence.existingClaim 复用保留或恢复后的存储卷声明。
• 备份与升级： 备份完整工作区前，请正常停止写入实例，或使用能够保证应用一致性的备份流程。仅复制运行中的 SQLite 索引文件无法保证备份完整且一致。请妥善保管保存锁屏密码的 Secret、加密密钥和加密笔记本恢复密码，并在独立 PVC 上测试恢复。升级前先备份，并确认新版本是否涉及存储格式变更：Helm 回滚不会撤销数据迁移。

Docker 部署的限制同样适用：仅支持浏览器访问，不支持桌面端和移动端应用连接，不支持导出 PDF、HTML 和 Word 格式，也不支持导入 Markdown 文件。

注意：首先终端运行 chown -R 1000:1000 /mnt/user/appdata/siyuan

模板参考：

Web 用户界面: 6806
容器端口：6806
容器路径：/home/siyuan
主机路径: /mnt/user/appdata/siyuan
PUID：1000
PGID: 1000
思远语言：中文（简体）
Publish parameters: serve --accessAuthCode=******（锁屏密码）

注意：首先在 TrueNAS Shell 中运行下面的命令。请将 Pool_1/Apps_Data/siyuan 更新为与你的应用数据集对应的路径。

zfs 创建 Pool_1/Apps_Data/siyuan
chown -R 1001:1002 /mnt/Pool_1/Apps_Data/siyuan
chmod 755 /mnt/Pool_1/Apps_Data/siyuan

进入 Apps - DiscoverApps - More Options（右上，除 Custom App 外）- 通过 YAML 安装

模板参考：

服务:
  思源：
    image: b3log/siyuan
    container_name: siyuan
    command: ['serve', '--workspace=/siyuan/workspace/', '--accessAuthCode=2222']
    端口：
      - 6806:6806
    卷数：
      - /mnt/Pool_1/Apps_Data/siyuan:/siyuan/workspace  # 调整为你的数据集路径  restart: unless-stopped environment:
      - TZ=Asia/Shanghai  # 按需替换为你的时区
      - PUID=1001
      - PGID=1002
      - SIYUAN_LANG=zh-CN

前提

• 仅适用于宝塔面板9.2.0及以上版本
• 安装宝塔面板，前往宝塔面板官网，选择正式版的脚本下载安装

部署

1. 登录宝塔面板，在左侧菜单栏中点击 Docker
2. 首次会提示安装 Docker 和 Docker Compose 服务，点击立即安装，若已安装请忽略
3. 安装完成后在 Docker-应用商店-实用工具 中找到 思源笔记，点击安装，也可以在搜索框直接搜索
4. 设置域名等基本信息，点击 确定
   • 名称：应用名称，默认 siyuan_随机字符
   • 版本选择：默认 latest
   • 域名：如你需要通过域名访问，请在此处填写你的域名
   • 允许外部访问：如你需通过 IP+Port 直接访问，请勾选，如你已经设置了域名，请不要勾选此处
   • 端口：默认 6806，可自行修改
   • 锁屏密码：默认随机生成
   • 内存限制：0为不限制，根据实际需要设置
5. 提交后面板会自动进行应用初始化，大概需要1-3分钟，初始化完成后即可访问

访问思源笔记

• 如果你填写了域名，请在浏览器输入域名访问
• 如你选择了 IP+端口，请在浏览器地输入 http://<宝塔面板IP>:6806 访问

前提

• 需要安装小皮面板，前往小皮面板，选择对应的脚本执行安装

部署

1. 登录小皮面板后，点击左侧菜单的 Docker
2. 首次打开会提示安装 Docker，点击 点击安装 Docker
3. 按照提示安装 Docker
4. 点击 应用商店，找到 思源笔记，点击 安装 -> 立即安装
5. 等待安装结束后，可在 任务队列 界面的 已结束 中点击 详情 查看安装信息

访问思源笔记

• 在浏览器输入 http://<小皮面板机器IP>:6806 访问

前提

• 仅适用于1Panel面板v1.10.32-lts及以上版本
• 安装1Panel面板，前往1Panel官网，选择正式版安装脚本下载安装

部署

1. 登录1Panel面板，在左侧菜单栏中点击 应用商店
2. 在 应用商店-实用工具 中找到 思源笔记，点击安装，也可以在搜索框直接搜索

3. 配置锁屏密码等基本信息，点击 确定

   • 名称：应用名称，默认 siyuan
   • 版本：默认最新发行版
   • 端口：默认 6806
   • 锁屏密码：访问笔记时需要使用的锁屏密码
   • 端口外部访问：如你需通过 IP+Port 直接访问，请勾选，同时会开放服务器防火墙端口
   • CPU限制：默认为0，不限制，可根据实际需要设置
   • 内存限制：默认为0，不限制，可根据实际需要设置
4. 提交后面板会自动进行应用安装启动，应用状态会变为安装中，大概需要1-3分钟，耐心等待安装完成
5. 当应用状态变为已启动后，点击左侧的网站，首次使用需要安装OpenResty，点击安装
6. 安装完成后，点击网站菜单栏左上角创建，在弹出的页面中选择反向代理
7. 在主域名填入你的域名，网站代号会自动生成，代理选择http，代理地址填写127.0.0.1:6806，点击确定
8. (可选) 配置你创建的网站，可根据需要配置https访问增强访问安全性

访问思源笔记

• 如果你通过OpenResty反向代理反代了网站，并且填写了域名，请在浏览器输入域名访问
• 如你选择了 端口外部访问，请在浏览器地输入 http://<1Panel面板IP>:6806 访问