# Silverbullet 部署指南

> 2026-08-05 记录。目标：在远程 Linux 服务器上用 Docker 部署自托管笔记服务，实现"随时随地在任意设备用浏览器查看编辑笔记"。

---

## 背景与选型

**需求**：远程服务器部署，随时随地任意设备查看、编辑笔记。

**选型结论**：Silverbullet（浏览器直接编辑 + Linux/Docker）。

### 为什么选 Silverbullet

- 任何设备浏览器打开网址即可**查看 + 编辑**，无需安装 App
- 支持 `[[]]` 双链、反向链接（**与 Obsidian 语法兼容**，现有笔记可直接用）
- 笔记是纯 Markdown 文件，存在服务器目录，备份 = 复制文件夹
- PWA 支持，手机浏览器可离线编辑
- Docker 一条命令部署，开源

### 备选：code-server（VS Code Web）

如果更想要完整 VS Code 体验，用 codercom/code-server。缺点：移动端体验差、无双链支持。**先用 Silverbullet，不够再补。**

---

## 一、服务器部署

### 创建 docker-compose.yml

```yaml
services:
  silverbullet:
    image: ghcr.io/silverbulletmd/silverbullet:latest
    container_name: silverbullet
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./space:/space          # 笔记存储目录，备份就是复制这个文件夹
    environment:
      - SB_USER=admin:改成你的强密码   # 登录认证，必填！
```

### 启动

```bash
docker compose up -d
```

访问 `http://服务器IP:3000` → 输入 admin/密码 → 完成。

### 常用环境变量

| 变量 | 说明 | 默认 |
|---|---|---|
| `SB_FOLDER` | Markdown 文件目录 | `/space` |
| `SB_PORT` | 内部端口 | `3000` |
| `SB_USER` | Basic auth（`user:pass`） | 无认证 |
| `SB_AUTH_TOKEN` | Bearer token API 访问 | 无 |
| `SB_READ_ONLY` | 只读模式 | `0` |

---

## 二、迁移现有笔记

本机笔记在 `d:\onedrive\note`（Windows），用 Git Bash 一次性传到服务器：

```bash
# 服务器上先建目录
ssh user@server "mkdir -p /path/to/space"

# rsync 上传（排除 Obsidian 配置目录，Silverbullet 用不上）
rsync -avP --exclude ".obsidian" "/d/onedrive/note/" user@server:/path/to/space/
```

---

## 三、HTTPS + 域名（强烈建议）

裸 HTTP 下密码明文传输，不安全。用 Caddy 做反向代理 + 自动 TLS 证书（Let's Encrypt）。

### 前提条件

- 一个已备案/可用的域名，如 `notes.yourdomain.com`
- 域名 A 记录已指向服务器公网 IP
- 服务器 80 和 443 端口未被占用（云服务器需在安全组放行这两个端口）

### 整合后的 docker-compose.yml

将 Caddy 和 Silverbullet 放在同一个 compose 文件中，让它们共享同一个 Docker 网络，容器间用服务名互相访问：

```yaml
services:
  silverbullet:
    image: ghcr.io/silverbulletmd/silverbullet:latest
    container_name: silverbullet
    restart: unless-stopped
    volumes:
      - ./space:/space
    environment:
      - SB_USER=admin:改成你的强密码
    # 不暴露 ports，只允许 Caddy 通过内部网络访问

  caddy:
    image: caddy:latest
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data          # 证书和密钥持久化，避免重启重新申请
      - caddy_config:/config      # Caddy 自身配置

volumes:
  caddy_data:
  caddy_config:
```

> **关键**：`caddy_data` 和 `caddy_config` 用 named volume 而非 bind mount，避免权限问题，且证书重启不丢失。

### Caddyfile 配置

在 `docker-compose.yml` 同级目录创建 `Caddyfile`（纯文本，无后缀）：

```caddyfile
# 基础版：自动 HTTPS + 反向代理
notes.yourdomain.com {
    reverse_proxy silverbullet:3000
}
```

**常用增强配置**：

```caddyfile
notes.yourdomain.com {
    # 反向代理
    reverse_proxy silverbullet:3000

    # 访问日志（排查问题时打开）
    log {
        output file /var/log/caddy/access.log
    }

    # 限制请求体大小（上传大文件时调大）
    request_body {
        max_size 50MB
    }

    # 安全头（可选）
    header {
        X-Content-Type-Options nosniff
        X-Frame-Options DENY
        -Server
    }
}
```

### 启动与验证

```bash
# 启动
docker compose up -d

# 查看 Caddy 日志（确认证书申请是否成功）
docker compose logs caddy -f
```

正常日志中应能看到类似 `certificate obtained successfully` 的输出。然后浏览器访问 `https://notes.yourdomain.com` 即可。

### 排错

| 问题 | 检查项 |
|---|---|
| 证书申请失败 | 确认域名 A 记录已生效（`dig notes.yourdomain.com` 或 `nslookup`），且 80 端口能从公网访问 |
| 502 Bad Gateway | `docker compose ps` 确认 silverbullet 容器在运行；确认 Caddyfile 中 `reverse_proxy` 的目标容器名与 compose 中 service 名一致 |
| 端口被占用 | 如果服务器已有 nginx/apache，先停掉再启 Caddy，或让 Caddy 监听其他端口 |
| 国内服务器 | 80/443 端口需备案；若无备案可用非标端口 + DNS 验证，但 Caddy 默认 HTTP-01 验证仍需 80 端口可达 |

> 无域名临时方案：frp / 路由侠等内网穿透工具把 3000 端口暴露出去。

---

## 四、数据备份

笔记是纯 Markdown → 备份 = 压缩目录：

```bash
# 手动备份
tar czf notes-backup-$(date +%F).tar.gz /path/to/space/

# cron 定时备份 + 保留最近 7 份
0 3 * * * tar czf /backup/notes-$(date +%F).tar.gz /path/to/space/ && ls -t /backup/notes-*.tar.gz | tail -n +8 | xargs rm -f
```

---

## 五、使用方式转变（关键）

选浏览器编辑 → **服务器目录成为唯一权威版本**，本地 OneDrive 降级为离线备份：

| 场景 | 操作 |
|---|---|
| 日常编辑 | 浏览器打开 Silverbullet，直接改服务器文件 |
| 本地离线备份 | `rsync user@server:/path/to/space/ /d/onedrive/note/` |
| 多设备 | 全部走浏览器，无需装任何东西 |

---

## 相关链接

- [[大模型架构基础]] — 本笔记库的正式学习内容
- [[AI编译器现状与前景]] — 技术趋势分析

---

*最后更新：2026-08-05*