📦 siyuan-note/siyuan：隐私优先、自托管的开源个人知识管理软件

重构你的思维

English | 中文 | 日本語 | Türkçe

---

---

思源笔记是一个隐私优先的个人知识管理系统，支持细粒度的块级引用和 Markdown 所见即所得。

欢迎访问思源英文讨论论坛了解更多。

在线用户指南：英文

大多数功能免费，甚至可商用。

• 内容块
  • 块级引用与双向链接
  • 自定义属性
  • SQL 查询嵌入
  • 协议 siyuan://
• 编辑器
  • 块式编辑
  • Markdown 所见即所得
  • 列表大纲
  • 块级聚焦
  • 百万字大型文档编辑
  • 数学公式、图表、流程图、甘特图、时序图、乐谱等
  • 网页剪藏
  • PDF 标注链接
• 导出
  • 块引用与嵌入
  • 带资源文件的标准 Markdown
  • PDF、Word 和 HTML
  • 复制到微信公众号、知乎和语雀
• 数据库
• 闪卡间隔重复
• 通过 OpenAI API 进行 AI 写作与问答聊天
• Tesseract OCR
• 多标签页，拖拽分屏
• 模板片段
• JavaScript/CSS 片段
• Android/iOS/鸿蒙 OS 应用
• Docker 部署
• API
• 社区集市

部分功能仅对付费会员开放，详情请参阅定价。

🏗️ 架构与生态系统

建议优先通过桌面和移动端的应用市场安装，以便未来一键升级版本。

移动端：

桌面端：

Docker 部署

在服务器上运行思源笔记最简单的方式是通过 Docker 部署。

整体程序位于 /opt/siyuan/ 下，基本结构与 Electron 安装包中 resources 文件夹的结构一致：

• appearance：图标、主题、语言
• guide：用户指南文档
• stage：界面与静态资源
• kernel：内核程序

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

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

注意： 从 v3.7.0 开始，必须显式传递 serve 子命令（例如 docker run b3log/siyuan serve --workspace=...）。运行 docker run --rm b3log/siyuan serve --help 查看所有服务端选项。

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

更多参数可通过 --help 查看。以下是一个使用新环境变量的启动命令示例：

docker run -d \
  -v workspace_dir_host:workspace_dir_container \
  -p 6806:6806 \
  -e PUID=1001 -e PGID=1002 \
  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_dir_host 和 workspace_dir_container 都设为 /siyuan/workspace。对应的启动命令如下：

docker run -d \
  -v /siyuan/workspace:/siyuan/workspace \
  -p 6806:6806 \
  -e PUID=1001 -e PGID=1002 \
  b3log/siyuan \
  serve \
  --workspace=/siyuan/workspace/ \
  --accessAuthCode=xxx

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

version: "3.9"
services:
  main:
    image: b3log/siyuan
    command: ['serve', '--workspace=/siyuan/workspace/', '--accessAuthCode=${AuthCode}']
    ports:
      - 6806:6806
    volumes:
      - /siyuan/workspace:/siyuan/workspace
    restart: unless-stopped
    environment:
      - TZ=${YOUR_TIME_ZONE}    # A list of time zone identifiers can be found at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
      - PUID=${YOUR_USER_PUID}  # Customize user ID
      - PGID=${YOUR_USER_PGID}  # Customize group ID

在此配置中：

• PUID 和 PGID 被动态设置并传入容器
• 如果不提供这些变量，将使用默认值 1000

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

在镜像中，entrypoint.sh 脚本确保...

Refactor your thinking

English | 中文 | 日本語 | Türkçe

---

---

SiYuan is a privacy-first personal knowledge management system, supporting fine-grained block-level reference and Markdown WYSIWYG.

Welcome to SiYuan English Discussion Forum to learn more.

Online user guide: English

Most features are free, even for commercial use.

• Content block
  • Block-level reference and two-way links
  • Custom attributes
  • SQL query embed
  • Protocol siyuan://
• Editor
  • Block-style
  • Markdown WYSIWYG
  • List outline
  • Block zoom-in
  • Million-word large document editing
  • Mathematical formulas, charts, flowcharts, Gantt charts, timing charts, staves, etc.
  • Web clipping
  • PDF Annotation link
• Export
  • Block ref and embed
  • Standard Markdown with assets
  • PDF, Word and HTML
  • Copy to WeChat MP, Zhihu and Yuque
• Database
• Flashcard spaced repetition
• AI writing and Q/A chat via OpenAI API
• Tesseract OCR
• Multi-tab, drag and drop to split screen
• Template snippet
• JavaScript/CSS snippet
• Android/iOS/HarmonyOS App
• Docker deployment
• API
• Community marketplace

Some features are only available to paid members, for more details please refer to Pricing.

🏗️ Architecture and Ecosystem

It is recommended to give priority to installing through the application market on desktop and mobile, so that you can upgrade the version with one click in the future.

Mobile:

Desktop:

Docker Deployment

The easiest way to serve SiYuan on a server is to deploy it through Docker.

The overall program is located under /opt/siyuan/, which is basically the structure under the resources folder of the Electron installation package:

• appearance: icon, theme, languages
• guide: user guide document
• stage: interface and static resources
• kernel: kernel program

The entry point is set when building the Docker image: ENTRYPOINT ["/opt/siyuan/entrypoint.sh"]. This script allows changing the PUID and PGID of the user that will run inside the container. This is especially relevant to solve permission issues when mounting directories from the host. The PUID (User ID) and PGID (Group ID) can be passed as environment variables, making it easier to ensure correct permissions when accessing host-mounted directories.

Use the following parameters when running the container with docker run b3log/siyuan:

Note: Since v3.7.0, the serve subcommand must be passed explicitly (e.g. docker run b3log/siyuan serve --workspace=...). Run docker run --rm b3log/siyuan serve --help to see all serving options.

• --workspace: Specifies the workspace folder path, mounted to the container via -v on the host
• --accessAuthCode: Specifies the lock screen password

More parameters can be found using --help. Here’s an example of a startup command with the new environment variables:

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

• PUID: Custom user ID (optional, defaults to 1000 if not provided)
• PGID: Custom group ID (optional, defaults to 1000 if not provided)
• workspace_dir_host: The workspace folder path on the host
• workspace_dir_container: The path of the workspace folder in the container, as specified in --workspace
  • Alternatively, it's possible to set the path via the SIYUAN_WORKSPACE_PATH env variable. The commandline will always have the priority, if both are set
• accessAuthCode: Lock screen password (please be sure to modify , otherwise anyone can access your data)
  • Alternatively, it's possible to set the lock screen password via the SIYUAN_ACCESS_AUTH_CODE env variable. The commandline will always have the priority, if both are set
  • To disable the lock screen password set the env variable SIYUAN_ACCESS_AUTH_CODE_BYPASS=true
• SIYUAN_LANG: Interface language (optional, defaults to en if unset in Docker). Accepts BCP 47 tags like zh-CN/zh-TW/en/ja/pt-BR; legacy underscore values like zh_CN/en_US are also accepted for backward compatibility. Omit it if you want the language chosen in Settings to persist across restarts; if set, it is applied on every startup and overrides the saved setting
  • Alternatively, use the --lang command-line parameter. If both are set, the command-line takes priority

To simplify things, it is recommended to configure the workspace folder path to be consistent on the host and container, such as having both workspace_dir_host and workspace_dir_container configured as /siyuan/workspace. The corresponding startup command would be:

docker run -d \
  -v /siyuan/workspace:/siyuan/workspace \
  -p 6806:6806 \
  -e PUID=1001 -e PGID=1002 \
  b3log/siyuan \
  serve \
  --workspace=/siyuan/workspace/ \
  --accessAuthCode=xxx

For users running SiYuan with Docker Compose, the environment variables PUID and PGID can be passed to customize the user and group IDs. Here's an example of a Docker Compose configuration:

version: "3.9"
services:
  main:
    image: b3log/siyuan
    command: ['serve', '--workspace=/siyuan/workspace/', '--accessAuthCode=${AuthCode}']
    ports:
      - 6806:6806
    volumes:
      - /siyuan/workspace:/siyuan/workspace
    restart: unless-stopped
    environment:
      - TZ=${YOUR_TIME_ZONE}    # A list of time zone identifiers can be found at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
      - PUID=${YOUR_USER_PUID}  # Customize user ID
      - PGID=${YOUR_USER_PGID}  # Customize group ID

In this setup:

• PUID and PGID are set dynamically and passed to the container
• If these variables are not provided, the default 1000 will be used

By specifying PUID and PGID in the environment, you avoid the need to explicitly set the user directive (user: '1000:1000') in the compose file. The container will dynamically adjust the user and group based on these environment variables at startup.

In the image, the entrypoint.sh script ensures the creation of the siyuan user and group with the specified PUID and PGID. Therefore, when the host creates a workspace folder, pay attention to setting the user and group ownership of the folder to match the PUID and PGID you plan to use. For example:

chown -R 1001:1002 /siyuan/workspace

If you use custom PUID and PGID values, the entrypoint script will ensure that the correct user and group are created inside the container, and ownership of mounted volumes will be adjusted accordingly. There’s no need to manually pass -u in docker run or docker-compose as the environment variables will handle the customization.

Use an NGINX reverse proxy to hide port 6806. Please note:

• Configure the WebSocket reverse proxy for /ws

• Be sure to confirm the correctness of the mounted volume, otherwise the data will be lost after the container is deleted

• Do not use URL rewriting for redirection, otherwise there may be problems with authentication, it is recommended to configure a reverse proxy

• If you encounter permission issues, verify that the PUID and PGID environment variables match the ownership of the mounted directories on your host system

• Does not support desktop and mobile application connections, only supports use on browsers

• Export to PDF, HTML and Word formats is not supported

• Import Markdown file is not supported

Unraid Deployment

Note: First run chown -R 1000:1000 /mnt/user/appdata/siyuan in the terminal

Template reference:

Web UI: 6806
Container Port: 6806
Container Path: /home/siyuan
Host path: /mnt/user/appdata/siyuan
PUID: 1000
PGID: 1000
Publish parameters: serve --accessAuthCode=******(Lock screen password)

TrueNAS Deployment

Note: First, run the commands below in the TrueNAS Shell. Please update Pool_1/Apps_Data/siyuan to match your dataset path.

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

Navigate to Apps - DiscoverApps - More Options (on top right, besides Custom App) - Install via YAML

Template reference:

services:
  siyuan:
    image: b3log/siyuan
    container_name: siyuan
    command: ['serve', '--workspace=/siyuan/workspace/', '--accessAuthCode=2222']
    ports:
      - 6806:6806
    volumes:
      - /mnt/Pool_1/Apps_Data/siyuan:/siyuan/workspace  # Adjust to your dataset path 
    restart: unless-stopped
    environment:
      - TZ=America/New_York  # Replace with your timezone if needed
      - PUID=1001
      - PGID=1002

We release insider preview before major updates, please visit https://github.com/siyuan-note/insider.

⌨️ Command-line Interface

The built-in CLI provides direct access to workspace data — no running server required.

# List all notebooks
siyuan notebook list -w ~/SiYuan

# Full-text search with JSON output
siyuan search "keyword" -w ~/SiYuan -f json

# Export a document as Markdown
siyuan export md --id <block-id> -w ~/SiYuan

Category	Commands
Notebooks & Documents	notebook, document, dailynote — CRUD and daily notes
Content	block, attr, outline — block read/write, attributes, outline
Metadata	tag, bookmark, template — tags, bookmarks, template snippets
Queries	search, sql — full-text and SQL queries
References	ref — backlinks and mentions
Import/Export	export, import, inbox — Markdown, HTML, preview, Word, .sy.zip, Data, cloud inbox
Data Management	repo, history, sync — snapshots, versions, cloud sync
Utilities	asset, file — resources and file system
Database	database — attribute view management
Server	serve — start the kernel HTTP server
Workspace & System	workspace, system — list, inspect, system info

Run siyuan --help for the full command tree. Use -f json (default is -f table) for script-friendly output. Most mutating commands also support --dry-run to preview changes without applying them.

The CLI binary is SiYuan-Kernel under <install>/resources/kernel. Windows installer adds it to PATH automatically. On macOS/Linux, create a symlink manually:

# macOS
ln -s /Applications/SiYuan.app/Contents/Resources/kernel/SiYuan-Kernel /usr/local/bin/siyuan

# Linux
ln -s /path/to/SiYuan/resources/kernel/SiYuan-Kernel /usr/local/bin/siyuan

🏘️ Community

See Development Guide.

How does SiYuan store data?

The data is saved in the workspace data folder:

• assets is used to save all inserted assets
• emojis is used to save emoji images
• snippets is used to save code snippets
• storage is used to save query conditions, layouts and flashcards, etc.
• templates is used to save template snippets
• widgets is used to save widgets
• plugins is used to save plugins
• public is used to save public data
• The rest of the folders are the notebook folders created by the user, files with the suffix of .sy in the notebook folder are used to save the document data, and the data format is JSON

Does it support data synchronization through a third-party sync disk?

Data synchronization through third-party synchronization disks is not supported, otherwise data may be corrupted.

Although it does not support third-party sync disks, it supports connecting with third-party cloud storage (Members' privileges).

In addition, you can also consider manually exporting and importing data to achieve data synchronization:

• Desktop: Settings - Export - Export Data / Import Data
• Mobile: Right column - About - Export Data / Import Data

SiYuan is completely open source, and contributions are welcome:

For more details, please refer to Development Guide.

How to upgrade to a new version?

• If installed via app store, please update via app store
• If it is installed through the installation package on the desktop, you can enable the option of Settings - About - Automatically download update installation package, so that SiYuan will automatically download the latest version of the installation package and prompt to install
• If it is installed by manual installation package, please download the installation package again to install

You can Check update in Settings - About - Current Version, or pay attention to Official Download or GitHub Releases to get the new version.

What if some blocks (such as paragraph blocks in list items) cannot find the block icon?

The block icon is omitted for the first sub-block under the list item. You can move the cursor into this block and trigger its block menu with Ctrl+/ .

What should I do if the data repo key is lost?

• If the data repo key is correctly initialized on multiple devices previously, the key is the same on all devices and can be retrieved in Settings - About - Data repo key - Copy key string

• If it has not been configured correctly before (for example, the keys on multiple devices are inconsistent) or all devices are unavailable and the key string cannot be obtained, you can reset the key by following the steps below:

  1. Manually back up the data, you can use Export Data or directly copy the workspace/data/ folder on the file system
  2. Settings - About - Data repo key - Reset data repo
  3. Reinitialize the data repo key. After initializing the key on one device, other devices import the key
  4. The cloud uses the new synchronization directory, the old synchronization directory is no longer available and can be deleted
  5. The existing cloud snapshots are no longer available and can be deleted

Most features are free, even for commercial use.

Member's privileges can only be used after payment, please refer to Pricing.

The birth of SiYuan is inseparable from many open source projects and contributors. Please refer to the project source code kernel/go.mod, app/package.json and project homepage.

The growth of SiYuan is inseparable from user feedback and promotion. Thank you, everyone, for your help with SiYuan ❤️

Welcome to join us and contribute code to SiYuan together.