我的主力笔记工具是 Obsidian，本地通过插件直接管理文件，体验很好。但有一个问题：服务器上跑着 AI Agent（Hermes），它需要读写我的笔记库，而 Linux 服务器装不了 Obsidian 桌面客户端。Fast Note Sync 的 MCP 接口解决了这个问题——AI Agent 通过 MCP 协议直接操作笔记，本地依然用 Obsidian 管理，数据在两端实时同步。

两条路径，一个笔记库

整套方案的逻辑很简单：

1
2
3
4
5
6
7
本地（有 Obsidian）          服务器（无 Obsidian）
    ↓                           ↓
Obsidian + FNS 插件            AI Agent (Hermes)
    ↓ WebSocket                 ↓ MCP 协议
Fast Note Sync Service (NAS, Docker)
    ↓ SQLite
本地存储

本地通过 Obsidian 客户端直接管理笔记，实时同步到服务端。服务器上的 AI Agent 通过 MCP 协议读写同一个笔记库。两条路径操作的是同一份数据，通过 WebSocket 保持实时一致。

为什么选 Fast Note Sync

方案 同步延迟 私有部署 AI 可操作 本地体验
Obsidian Sync 毫秒级 否 否 完整
iCloud / 坚果云 秒~分钟 否 否 完整
Git 同步 手动 是 否 完整
Fast Note Sync 毫秒级 是 MCP 原生 完整

关键差异：Fast Note Sync 是唯一同时满足「自托管」「实时同步」「AI 可操作」三个条件的方案。原生 MCP 支持意味着不需要额外写胶水代码，配置即用。

部署服务端

服务端用 Golang 编写，Docker 部署最省事。

Docker Compose

1
2
3
4
5
6
7
8
9
10
11
# /vol1/docker/fast-note-sync/docker-compose.yml
services:
  fast-note-sync-service:
    image: ghcr.io/haierkeys/fast-note-sync-service:latest
    container_name: fast-note-sync-service
    restart: always
    ports:
      - "9000:9000"
    volumes:
      - ./storage:/fast-note-sync/storage
      - ./config:/fast-note-sync/config

服务端配置

config/config.yaml 关键参数：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
server:
  run-mode: release
  http-port: ":9000"
  ext-api-url: "https://your-nas.example.com:自定义端口"

app:
  soft-delete-retention-time: "7d"
  sync-log-retention-time: "30d"
  history-keep-versions: 100
  ws-compression-enabled: true
  fts-bleve-enabled: true  # 全文搜索

database:
  type: sqlite
  path: storage/database/db.sqlite3
  auto-migrate: true

security:
  token-expiry: "365d"
  webgui-login-token-bind-ip: false  # 反向代理时务必关闭

webgui-login-token-bind-ip: false 是关键——使用反向代理时客户端 IP 会变化，开启此项会导致频繁掉线。

反向代理与 SSL

飞牛 OS 的 80/443 端口被 trim_nginx 占用，用 Caddy 监听空闲端口做 SSL 终结：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    auto_https off  # 必须加，否则抢 80 端口
}

your-nas.example.com:自定义端口 {
    tls /path/to/certs/fullchain.crt /path/to/certs/cert.key

    @websockets {
        header Connection *Upgrade*
        header Upgrade    websocket
    }

    reverse_proxy @websockets localhost:9000 {
        header_up X-Real-IP {remote_host}
    }

    reverse_proxy localhost:9000 {
        header_up X-Real-IP {remote_host}
    }
}

两个容易踩的坑：

  1. auto_https off 必须加——否则 Caddy 尝试监听 80 端口，跟现有服务冲突。
  2. WebSocket 升级需要单独匹配——FNS 的 /api/user/sync 使用 WebSocket，Caddy 需要通过 @websockets matcher 正确转发 Upgrade 头。

证书自动续期

飞牛 OS 的 SSL 证书路径含时间戳目录，每次续期会变。用符号链接 + systemd timer 解决：从系统配置读取当前活跃证书路径，每 6 小时检测一次，证书更新时自动重建符号链接并通知 Caddy 重载。

本地配置 Obsidian 客户端

这是日常使用的主路径：

  1. 访问 https://your-nas.example.com:自定义端口/webgui 注册管理员账号
  2. 在 Web UI「笔记库」中创建或选择默认笔记库
  3. 点击「一键授权 Obsidian」获取授权配置
  4. 各端 Obsidian 安装 Fast Note Sync 插件，粘贴授权配置

插件自动监听 Vault 内所有笔记的创建、更新、删除，通过 WebSocket 实时同步。离线期间的操作在重连后自动合并，不会丢数据。日常写笔记、整理知识库，全程在 Obsidian 里完成，同步是无感的。

接入 AI Agent（MCP）

这是解决服务器端问题的关键——服务器没有 Obsidian，但 AI Agent 需要读写笔记。Fast Note Sync 原生支持 MCP 协议，StreamableHTTP 传输，开箱即用。

获取 API Token

Web GUI → 设置 → API Token → 创建新 Token，权限选 p:rest。

安装 MCP SDK

Hermes Agent 的 venv 默认不含 MCP SDK：

1
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python mcp

配置 Hermes

编辑 ~/.hermes/config.yaml，添加：

1
2
3
4
5
6
7
mcp_servers:
  fns:
    url: "http://127.0.0.1:9000/api/mcp"
    headers:
      Authorization: "Bearer <API_Token>"
      X-Default-Vault-Name: "wiki"
    timeout: 180

重启后自动注入 25 个 mcp_fns_* 工具：

类别 工具示例
笔记读写 note_list, note_get, note_create_or_update, note_append
文件操作 file_list, file_read, file_write
笔记库管理 vault_list, vault_create_or_update
回收站 note_restore, file_restore

使用效果

配置完成后，AI Agent 可以直接操作笔记库：

  • “列出 wiki 库所有笔记”
  • “读取某篇笔记并总结要点”
  • “在 daily 目录创建今天的日程”
  • “把这篇文章追加到项目日志末尾”

通过 MCP 修改的笔记实时同步到所有 Obsidian 客户端，本地打开 Obsidian 就能看到 AI 写入的内容。反过来，本地编辑的笔记也能被 AI 读取。

注意事项

  • MCP 工具在新会话中注入，配置完成后需要新开会话才能使用
  • 本地 Obsidian 操作和服务器 MCP 操作是两条独立路径，但操作同一份数据
  • WebSocket 端点 /api/user/sync 需要在反向代理中正确处理 Upgrade 头
  • Token 仅本地使用，不暴露公网
  • user-database 配置中 port 字段必须是整数，留空字符串会导致启动报错

总结

这套方案的核心思路：本地用 Obsidian 管理笔记（完整体验），服务器通过 MCP 让 AI 操作笔记（无桌面环境），Fast Note Sync 作为中间层提供实时同步。两条路径各取所长，数据始终一致。

参考资料