SiYuan 笔记部署指南
隐私优先的个人知识管理系统，支持块级引用、Markdown 所见即所得编辑器、闪卡间隔重复等功能。
功能特性
- 块级引用和双向链接
- Markdown 所见即所得编辑器
- 数学公式、流程图、甘特图等
- 闪卡间隔重复（Spaced Repetition）
- AI 写作（基于 OpenAI API）
- Web 剪藏（Chrome/Edge 扩展）
- 社区插件市场
技术栈
| 组件 | 版本 | 说明 |
|---|---|---|
| SiYuan | latest | 知识管理系统 |
| Nginx | 系统包 | 反向代理 + HTTPS 接入 |
| Docker | 最新版 | 容器运行环境 |
Docker 版限制
重要：Docker 部署版与桌面版相比有以下限制：
- 不支持桌面和移动客户端连接，只能通过浏览器使用
- 不支持导出 PDF、HTML、Word 格式
- 不支持导入 Markdown 文件
前置条件
- 一台 Linux 服务器（Ubuntu 22.04/24.04 推荐）
- 一个已解析到服务器的域名（如
note.example.com） - 服务器 80/443 端口可从外网访问
目录结构
siyuan/
├── docker-compose.yml # 容器编排
├── .env.example # 配置模板
├── deploy.sh # 一键部署脚本
├── backup.sh # 备份脚本
├── nginx/
│ └── siyuan.conf # Nginx 反向代理配置
└── README.md # 本文件
服务器上的数据目录：
/data/siyuan/workspace/ # SiYuan 工作空间（笔记 + 资源文件）
/var/backups/siyuan/ # 备份文件
快速部署
第一步：上传文件到服务器
# 在本地执行，上传 base 和 siyuan 目录
scp -r base/ siyuan/ root@<服务器IP>:/opt/
第二步：登录服务器执行部署
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> |
第四步：登录使用
- 浏览器访问
https://note.yourdomain.com - 输入
.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
日常运维
查看日志
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 的数据存储在工作空间目录下：
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） |