server-deploy/siyuan

SiYuan 笔记部署指南

隐私优先的个人知识管理系统，支持块级引用、Markdown 所见即所得编辑器、闪卡间隔重复等功能。

功能特性

• 块级引用和双向链接
• Markdown 所见即所得编辑器
• 数学公式、流程图、甘特图等
• 闪卡间隔重复（Spaced Repetition）
• AI 写作（基于 OpenAI API）
• Web 剪藏（Chrome/Edge 扩展）
• 社区插件市场

技术栈

组件	版本	说明
SiYuan	latest	知识管理系统
Nginx	系统包	反向代理 + HTTPS 接入
Docker	最新版	容器运行环境

Docker 版限制

重要：Docker 部署版与桌面版相比有以下限制：

• 不支持桌面和移动客户端连接，只能通过浏览器使用
• 不支持导出 PDF、HTML、Word 格式
• 不支持导入 Markdown 文件

前置条件

1. 一台 Linux 服务器（Ubuntu 22.04/24.04 推荐）
2. 一个已解析到服务器的域名（如 note.example.com）
3. 服务器 80/443 端口可从外网访问

目录结构

siyuan/
├── docker-compose.yml    # 容器编排
├── .env.example          # 配置模板
├── deploy.sh             # 一键部署脚本
├── backup.sh             # 备份脚本
├── uninstall.sh          # 完全卸载脚本
├── nginx/
│   └── siyuan.conf       # Nginx 反向代理配置
└── README.md             # 本文件

服务器上的数据目录：

/data/siyuan/workspace/   # SiYuan 工作空间（笔记 + 资源文件）
/var/backups/siyuan/      # 备份文件

快速部署

第一步：上传文件到服务器

# 在本地执行，上传 siyuan 目录
scp -r siyuan/ root@<服务器IP>:/opt/siyuan

# 如果服务器上还没有部署过 base（首台服务或全新服务器），还需上传 base
scp -r base/ root@<服务器IP>:/opt/base

第二步：登录服务器执行部署

ssh root@<服务器IP>

# 如果是全新服务器，先安装基础环境
cd /opt/base
cp .env.example .env
bash setup.sh

# 部署 SiYuan
cd /opt/siyuan
bash deploy.sh
# 首次运行会生成 .env，按提示修改配置后重新运行
vi .env
bash deploy.sh

第三步：配置域名解析

在域名服务商（如阿里云 DNS）添加 A 记录：

记录类型	主机记录	记录值
A	note	<服务器公网IP>

第四步：登录使用

1. 浏览器访问 https://note.yourdomain.com
2. 输入 .env 中配置的 SIYUAN_ACCESS_CODE 授权码

配置说明

.env 配置项

变量	说明	默认值
SIYUAN_DOMAIN	访问域名	必填
CERTBOT_EMAIL	Let's Encrypt 邮箱	必填
SIYUAN_ACCESS_CODE	访问授权码	必填
SIYUAN_IMAGE	Docker 镜像	b3log/siyuan:latest
SIYUAN_DATA_DIR	工作空间目录	/data/siyuan/workspace
BACKUP_DIR	备份目录	/var/backups/siyuan
SIYUAN_PUID	容器用户 ID	1000
SIYUAN_PGID	容器组 ID	1000

修改访问授权码

cd /opt/siyuan

# 修改 .env 中的 SIYUAN_ACCESS_CODE
vi .env

# 重新创建容器使新授权码生效
docker compose up -d

用户权限说明

SiYuan 容器通过 PUID 和 PGID 环境变量控制运行用户。部署脚本会自动设置数据目录的所有权。如需手动调整：

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

使用指南

基本操作

1. 浏览器访问 https://note.yourdomain.com，输入授权码登录
2. 点击左上角「笔记本」图标 → 「新建笔记本」
3. 在笔记本中点击「+」新建文档，即可开始编辑

编辑器快捷操作

操作	说明
/	呼出斜杠菜单（插入标题、列表、代码块、公式等）
((	块引用（链接到其他块）
[[	文档引用
Ctrl+E	行内代码
Ctrl+P	全局搜索
Ctrl+Shift+F	替换
Ctrl+/	呼出块菜单

更多快捷键：点击右上角「?」→「快捷键」查看完整列表。

插入资源文件

• 直接拖拽图片到编辑器即可上传（存储在 data/assets/ 下）
• 支持粘贴剪贴板中的图片

安装插件

1. 点击右上角「集市」图标（🏪）
2. 选择「插件」标签页
3. 浏览并安装需要的插件
4. 部分插件需要刷新页面后生效

使用模板

1. 创建模板：新建文档 → 编辑好内容 → 移动到 templates/ 目录
2. 使用模板：编辑器中输入 / → 选择「模板」→ 选择已有模板

闪卡间隔重复

1. 在文档中选中要制作闪卡的块
2. 右键 → 「制作闪卡」（或使用块菜单）
3. 点击顶部工具栏「闪卡」图标开始复习

数据导出

注意：Docker 版不支持导出 PDF/HTML/Word，仅支持导出 Markdown（.md）和 SiYuan 格式（.sy.zip）。

• 单文档导出：右键文档 → 导出 → 选择格式
• 整个笔记本导出：右键笔记本 → 导出

官方文档

• 用户指南：https://b3log.org/siyuan/guide/
• GitHub：https://github.com/siyuan-note/siyuan

日常运维

查看日志

cd /opt/siyuan
docker compose logs -f
docker compose logs --tail 100

备份

cd /opt/siyuan
bash backup.sh

备份内容包括：

• 工作空间数据（笔记、资源文件、插件等）
• 部署配置（docker-compose.yml + .env + nginx/）

备份文件保存在 /var/backups/siyuan/，自动清理 30 天前的旧备份。

恢复备份

# 查看可用备份
ls /var/backups/siyuan/

# 停止服务
cd /opt/siyuan && docker compose down

# 恢复数据
tar xzf /var/backups/siyuan/<日期>/siyuan-workspace.tar.gz -C /data/siyuan/

# 修复权限
chown -R 1000:1000 /data/siyuan/workspace

# 重启服务
cd /opt/siyuan && docker compose up -d

升级

cd /opt/siyuan

# 1. 备份当前数据
bash backup.sh

# 2. 拉取新镜像
docker compose pull

# 3. 停止旧容器并启动新容器
docker compose down
docker compose up -d

# 4. 检查运行状态
docker compose ps
docker compose logs --tail 20

停止 / 启动

cd /opt/siyuan
docker compose down      # 停止
docker compose up -d     # 启动
docker compose restart   # 重启

完全卸载

如果需要从服务器上完全移除 SiYuan，使用卸载脚本：

cd /opt/siyuan
bash uninstall.sh

脚本会交互式确认每个危险操作，按顺序执行：

步骤	操作	确认方式
0	卸载前备份（可选）	y/N
1	停止并删除 SiYuan 容器	输入 YES
2	删除 Docker 镜像	自动
3	删除 Nginx 站点配置并重载	自动
4	删除 Let's Encrypt SSL 证书	自动
5	清理 Certbot 定时任务（仅当无其他证书时）	自动
6	删除数据目录	输入 DELETE
7	删除部署目录 /opt/siyuan	y/N

备份目录 /var/backups/siyuan/ 始终保留，不会被删除。

卸载后如需恢复，参考上方「恢复备份」章节。

手动卸载步骤（不使用脚本）

cd /opt/siyuan

# 1. 建议先备份
bash backup.sh

# 2. 停止并删除容器
docker compose down -v

# 3. 删除 Docker 镜像（可选）
docker image rm b3log/siyuan:latest

# 4. 删除 Nginx 配置
rm -f /etc/nginx/sites-enabled/siyuan /etc/nginx/sites-available/siyuan
nginx -t && systemctl reload nginx

# 5. 删除 SSL 证书
certbot delete --cert-name 你的域名

# 6. 删除数据目录（⚠ 不可恢复）
rm -rf /data/siyuan/workspace

# 7. 删除部署目录（可选）
rm -rf /opt/siyuan

# 备份目录保留在 /var/backups/siyuan/

数据存储结构

SiYuan 的数据存储在工作空间目录下：

workspace/
└── data/
    ├── assets/       # 插入的资源文件（图片等）
    ├── emojis/       # 自定义 Emoji
    ├── snippets/     # 代码片段
    ├── storage/      # 查询条件、布局、闪卡等
    ├── templates/    # 模板片段
    ├── widgets/      # 挂件
    ├── plugins/      # 插件
    ├── public/       # 公共数据
    └── <笔记本>/     # 用户创建的笔记本（.sy 格式 JSON 文件）

故障排查

数据同步警告

不要使用第三方同步盘（Dropbox、OneDrive、坚果云等）同步工作空间目录，否则会导致数据损坏。如需多设备同步，请使用 SiYuan 官方云端同步（付费功能）或手动导出导入。

容器无法启动

# 查看容器状态
docker compose ps

# 查看详细日志
docker compose logs --tail 50

权限问题

如果出现文件读写权限错误：

# 确认 PUID/PGID 与数据目录所有者一致
ls -la /data/siyuan/
chown -R 1000:1000 /data/siyuan/workspace

访问返回 502

# 检查 SiYuan 容器是否运行
docker compose ps

# 检查 6806 端口
curl -I http://127.0.0.1:6806

# 检查 Nginx 配置
nginx -t

WebSocket 连接失败

确认 Nginx 配置中 /ws 路径已正确配置 WebSocket 反向代理（部署脚本已自动配置）。

注意事项

• 不要使用 URL 重写进行重定向，否则可能导致认证出现问题。应当使用反向代理（部署脚本已正确配置）。
• 不要通过第三方同步盘同步数据（如 Dropbox、OneDrive、坚果云等），否则可能导致数据损坏。SiYuan 有自己的云端同步机制（付费功能）。
• 确认挂载卷的路径正确，否则删除容器后数据会丢失。
• 如果遇到权限问题，确认 PUID/PGID 环境变量与宿主机挂载目录的所有者一致。

端口说明

端口	协议	说明
80	TCP	HTTP → HTTPS 重定向
443	TCP	HTTPS（Nginx 反向代理）
6806	TCP	SiYuan HTTP（仅监听 127.0.0.1）