398 lines
9.8 KiB
Markdown
398 lines
9.8 KiB
Markdown
# 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/ # 备份文件
|
||
```
|
||
|
||
## 快速部署
|
||
|
||
### 第一步：上传文件到服务器
|
||
|
||
```bash
|
||
# 在本地执行，上传 siyuan 目录
|
||
scp -r siyuan/ root@<服务器IP>:/opt/siyuan
|
||
|
||
# 如果服务器上还没有部署过 base（首台服务或全新服务器），还需上传 base
|
||
scp -r base/ root@<服务器IP>:/opt/base
|
||
```
|
||
|
||
### 第二步：登录服务器执行部署
|
||
|
||
```bash
|
||
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` |
|
||
|
||
### 修改访问授权码
|
||
|
||
```bash
|
||
cd /opt/siyuan
|
||
|
||
# 修改 .env 中的 SIYUAN_ACCESS_CODE
|
||
vi .env
|
||
|
||
# 重新创建容器使新授权码生效
|
||
docker compose up -d
|
||
```
|
||
|
||
### 用户权限说明
|
||
|
||
SiYuan 容器通过 `PUID` 和 `PGID` 环境变量控制运行用户。部署脚本会自动设置数据目录的所有权。如需手动调整：
|
||
|
||
```bash
|
||
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>
|
||
|
||
## 日常运维
|
||
|
||
### 查看日志
|
||
|
||
```bash
|
||
cd /opt/siyuan
|
||
docker compose logs -f
|
||
docker compose logs --tail 100
|
||
```
|
||
|
||
### 备份
|
||
|
||
```bash
|
||
cd /opt/siyuan
|
||
bash backup.sh
|
||
```
|
||
|
||
备份内容包括：
|
||
- 工作空间数据（笔记、资源文件、插件等）
|
||
- 部署配置（`docker-compose.yml` + `.env` + `nginx/`）
|
||
|
||
备份文件保存在 `/var/backups/siyuan/`，自动清理 30 天前的旧备份。
|
||
|
||
### 恢复备份
|
||
|
||
```bash
|
||
# 查看可用备份
|
||
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
|
||
```
|
||
|
||
### 升级
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
### 停止 / 启动
|
||
|
||
```bash
|
||
cd /opt/siyuan
|
||
docker compose down # 停止
|
||
docker compose up -d # 启动
|
||
docker compose restart # 重启
|
||
```
|
||
|
||
## 完全卸载
|
||
|
||
如果需要从服务器上完全移除 SiYuan，使用卸载脚本：
|
||
|
||
```bash
|
||
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/` 始终保留**，不会被删除。
|
||
|
||
> 卸载后如需恢复，参考上方「恢复备份」章节。
|
||
|
||
<details>
|
||
<summary>手动卸载步骤（不使用脚本）</summary>
|
||
|
||
```bash
|
||
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/
|
||
```
|
||
|
||
</details>
|
||
|
||
## 数据存储结构
|
||
|
||
SiYuan 的数据存储在工作空间目录下：
|
||
|
||
```
|
||
workspace/
|
||
└── data/
|
||
├── assets/ # 插入的资源文件（图片等）
|
||
├── emojis/ # 自定义 Emoji
|
||
├── snippets/ # 代码片段
|
||
├── storage/ # 查询条件、布局、闪卡等
|
||
├── templates/ # 模板片段
|
||
├── widgets/ # 挂件
|
||
├── plugins/ # 插件
|
||
├── public/ # 公共数据
|
||
└── <笔记本>/ # 用户创建的笔记本（.sy 格式 JSON 文件）
|
||
```
|
||
|
||
## 故障排查
|
||
|
||
### 数据同步警告
|
||
|
||
> **不要**使用第三方同步盘（Dropbox、OneDrive、坚果云等）同步工作空间目录，否则会导致数据损坏。如需多设备同步，请使用 SiYuan 官方云端同步（付费功能）或手动导出导入。
|
||
|
||
### 容器无法启动
|
||
|
||
```bash
|
||
# 查看容器状态
|
||
docker compose ps
|
||
|
||
# 查看详细日志
|
||
docker compose logs --tail 50
|
||
```
|
||
|
||
### 权限问题
|
||
|
||
如果出现文件读写权限错误：
|
||
|
||
```bash
|
||
# 确认 PUID/PGID 与数据目录所有者一致
|
||
ls -la /data/siyuan/
|
||
chown -R 1000:1000 /data/siyuan/workspace
|
||
```
|
||
|
||
### 访问返回 502
|
||
|
||
```bash
|
||
# 检查 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） |
|