目前最好用的obsidian多设备实时同步插件——Fast Note Sync自部署指南

obsidian 同步私有化部署教程

Published on Jun 17, 2026

为什么你需要私有化笔记同步

Obsidian 的用户大概都经历过这个痛苦：

公司电脑写了一堆笔记，回家打开笔记本——没有。手机上随手记的灵感，回到桌面端——也没有。

官方同步服务（Obsidian Sync）一个月要 $5（约 35 人民币），价格谈不上贵，但如果你笔记量大、附件多，或者公司网络环境不允许连外网，就没法用了。

第三方方案像 Remotely Save + S3/WebDAV 也能凑合，但配置麻烦、同步延迟高、经常冲突，用过的都懂。

2026年6月17日_15_15_32.png

这就是 Fast Note Sync 出现的原因。

它是一个开源的全家桶方案：客户端插件 + 私有化服务端，你只需要在自己的服务器上部署一个后端，然后在所有设备上装好插件，就能实现：

✅ 毫秒级实时同步（WebSocket 推送，不是定时轮询）
✅ 全平台支持（Mac / Windows / iOS / Android）
✅ 附件同步（图片、视频、PDF 全部支持）
✅ 笔记历史版本 + 回收站
✅ 一键分享笔记链接
✅ Git 自动备份
✅ MCP 协议支持，AI 可以直接读写你的笔记
✅ 多存储后端（S3/OSS/R2/WebDAV/本地）

而且——完全免费，数据100%在自己手里。

GitHub：https://github.com/haierkeys/obsidian-fast-note-sync

Star 数 2.4k，服务端 1.6k，17 万+ 社区插件下载量，活跃维护中。

下面，我从零开始，带你一步步把它搭起来。

整体架构，先看懂再动手

在动手之前，先用一张图搞清楚这套系统是怎么跑的：

2026年6月17日_15_24_34.png

简单说就是：服务端是你自己的一台服务器（VPS/NAS/甚至树莓派），客户端是 Obsidian 里的一个插件，两者通过 WebSocket 实时通信。 任何一台设备上的笔记变动，毫秒级推送到其他所有在线设备。

第一步：部署服务端（Fast Note Sync Service）

服务端是整个系统的核心，必须先搭好。官方提供了三种部署方式，按推荐程度排列：

方式一：一键脚本（最推荐，适合 Linux/macOS）

这是最简单的方式，一行命令搞定安装、配置、开机自启。

SSH 登录你的服务器后，执行：

bash <(curl -fsSL https://raw.githubusercontent.com/haierkeys/fast-note-sync-service/master/scripts/quest_install.sh)

国内用户建议用腾讯云 CNB 镜像，速度更快：

bash <(curl -fsSL https://cnb.cool/haierkeys/fast-note-sync-service/-/git/raw/master/scripts/quest_install.sh) --cnb

这个脚本会自动做什么？

自动检测你的系统（Linux/macOS）和 CPU 架构
下载对应的预编译二进制
安装到 /opt/fast-note，并在 /usr/local/bin/fns 创建快捷命令
注册 Systemd（Linux）或 Launchd（macOS）服务，开机自启

装完之后，你就可以用 fns 命令来管理服务了：

fns              # 进入交互式菜单（推荐新手用）
fns start        # 启动服务
fns stop         # 停止服务
fns status       # 查看服务状态
fns update       # 升级到最新版

方式二：Docker 部署（适合已有 Docker 环境）

如果你服务器上已经跑了 Docker，这是最省事的方式。

Docker Run 单行命令：

# 拉取镜像
docker pull haierkeys/fast-note-sync-service:latest

# 启动容器
docker run -tid --name fast-note-sync-service \
    -p 9000:9000 \
    -v /data/fast-note-sync/storage/:/fast-note-sync/storage/ \
    -v /data/fast-note-sync/config/:/fast-note-sync/config/ \
    haierkeys/fast-note-sync-service:latest

-p 9000:9000：把容器的 9000 端口映射到宿主机。如果宿主机 9000 被占用了，可以改成 -p 9527:9000 之类的。

-v 挂载：两个目录分别存数据和配置文件，一定要挂载出来，不然容器删了数据就没了。

Docker Compose 方式（推荐团队/长期使用）：

新建一个 docker-compose.yaml：

version: '3'
services:
  fast-note-sync-service:
    image: 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

然后启动：

docker compose up -d

方式三：手动二进制安装

从 Releases 页面下载对应系统的压缩包，解压后直接运行：

tar -xzf fast-note-sync-service_linux_amd64.tar.gz
./fast-note-sync-service run -c config/config.yaml

这种方式不自带进程守护，适合测试体验。长期使用建议配合 systemd 或 screen 来保证服务不挂。

部署后第一件事：开放端口 & 访问管理面板

不管你用哪种方式部署的，服务启动后，浏览器打开：

http://你的服务器IP:9000

如果用的是云服务器（阿里云/腾讯云/AWS 等），记得在安全组/防火墙里放行 9000 端口，否则访问不了。

第一次访问会看到注册页面，输入邮箱和密码注册一个账号。第一个注册的用户建议设为管理员（后面会说怎么配）。

第二步：配置服务端（关键步骤）

注册登录后，进入 Web 管理面板。界面是中文的，比较直观。

2.1 创建笔记仓库（Vault）

左侧导航栏点击「笔记仓库」→ 点击「新建」→ 输入仓库名称（比如 MyNotes）→ 保存。

一个用户可以创建多个仓库，比如把工作笔记和个人笔记分开。

2.2 获取授权配置信息

这是连接客户端的关键一步：

在「笔记仓库」页面，找到你刚创建的仓库，点击「一键授权给 Obsidian」。

桌面端（Mac/Windows）：点击后会自动唤起 Obsidian 并完成授权信息填写

移动端（iOS/Android）：目前不支持一键唤起，需要手动复制——点击「复制 API 配置」，把 JSON 配置复制下来，后面粘贴到手机端插件里

2.3 （可选但推荐）修改关键配置

默认配置开箱即用，但有几项建议按需调整。配置文件在服务端目录的 config/config.yaml：

# === 安全相关 ===
security:
  auth-token-key: fast-note-sync-Auth-Token  # 改成你自己的随机字符串！
  token-expiry: "365d"                        # Token 有效期，365天基本够用

# === 用户管理 ===
user:
  register-is-enable: true   # 如果你一个人用，部署完后改成 false 关闭注册
  admin-uid: 0               # 改成你的用户 UID（在管理面板用户列表里能看到）

# === 日志 ===
log:
  level: warn   # 调试时改成 debug，正常运行用 warn 或 info

# === 存储 ===
storage:
  local-fs:
    is-enable: false        # 默认用本地文件系统就够了
    save-path: "storage/uploads"

重要：改完配置后要重启服务才能生效。用 fns restart 或 docker restart fast-note-sync-service。

2.4 （可选）配置 Nginx 反向代理 + HTTPS

如果你有域名，强烈建议配置反向代理 + SSL 证书。这样你可以用 https://notes.yourdomain.com 来访问，安全又体面。

Nginx 配置示例：

server {
    listen 443 ssl;
    server_name notes.yourdomain.com;

    ssl_certificate     /etc/ssl/certs/yourdomain.pem;
    ssl_certificate_key /etc/ssl/private/yourdomain.key;

    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";       # WebSocket 必须
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400;                    # WebSocket 长连接
    }
}

注意：proxy_read_timeout 一定要设大，否则 WebSocket 长连接会被 Nginx 掐断，导致同步中断。

第三步：安装客户端插件

服务端就绪后，开始给每台设备装插件。

3.1 桌面端（Mac / Windows / Linux）

打开 Obsidian → 设置（齿轮图标） → Community Plugins（社区插件） → 关闭安全模式 → 点击 Browse（浏览） → 搜索 Fast Note Sync → 安装并启用。

如果你刚才在管理面板用了「一键授权」，此时插件已经自动配好了，什么都不用做。

如果你是手动配置，把复制的 API 配置 JSON 粘贴到插件设置页面的配置框里就行。

3.2 移动端（iOS / Android）

同样的流程：设置 → 社区插件 → 搜索安装 Fast Note Sync。

然后在管理面板复制 API 配置，粘贴到手机端插件里。

iOS 用户注意：粘贴时如果发现粘贴不了，可以先粘贴到备忘录里，再复制过来——这是 Obsidian iOS 端的老问题了。

微信图片_20260617154412_49_59.png

看到这个服务已连接说明就配置完成了。

3.3 验证同步是否正常

装好插件后，看 Obsidian 左侧边栏底部会出现 Fast Note Sync 的图标。点击能看到同步状态、日志。

做一个简单的测试：

在桌面端新建一个测试笔记，随便写几行
打开手机端，等几秒，看看笔记有没有出现
在手机端修改同一个笔记
回到桌面端，看看是否实时更新

如果一切正常，恭喜你，你的私有同步系统已经跑起来了 🎉

第四步：进阶功能配置

基础同步跑通后，这些功能能让你的体验再上一个台阶。

4.1 同步排除 & 白名单

有些文件你不想同步（比如 .obsidian/workspace.json、大型附件等），可以在插件设置里配置：

排除规则：支持 glob 模式，比如 **/.obsidian/workspace* 排除工作区文件
白名单模式：只同步特定目录/文件

4.2 笔记历史版本 & 回收站

在管理面板的「笔记仓库」页面，点击任意笔记 → 可以看到 历史版本 列表：

每次修改都会自动保存一个快照（延迟 10 秒防抖）
可以对比差异、回滚到任意历史版本
删除的笔记会进入 回收站，默认保留 7 天，可以恢复

4.3 分享笔记

管理面板中，点击笔记旁的分享按钮：

生成一个分享链接，对方可以直接在线预览（不需要装 Obsidian）
支持设置访问密码
支持生成短链接
可以查看访问统计

非常适合把笔记分享给不熟悉 Obsidian 的朋友或同事。

4.4 Git 自动备份

在 config.yaml 中启用 Git 功能后，每次笔记变动会自动 commit + push 到远程仓库：

git:
  name: "FNS Service"
  email: "fns@email.com"

配合 GitHub 私有仓库，等于多了一层异地容灾备份。

具体步骤：在服务器上的笔记存储目录初始化一个 Git 仓库，配置好 remote，然后重启服务即可。详细文档见 GitHub Repo。

4.5 S3 / OSS / R2 对象存储备份

如果你的笔记附件很多很大，可以把附件存储切换到对象存储：

storage:
  aws-s3:
    is-enable: true
    # ... 填写 S3 的 access key / bucket / region

支持阿里云 OSS、AWS S3、Cloudflare R2、MinIO、WebDAV 等多种后端。配置项在 config.yaml 的 storage 段里都有注释说明。

第五步：MCP 集成——让 AI 直接读写你的笔记

这是 Fast Note Sync 最亮眼的功能之一。

MCP（Model Context Protocol）是 AI 和外部工具之间的标准协议。FNS 支持作为 MCP Server，这意味着 Claude Code、Cursor、Cherry Studio 等 AI 客户端可以直接读写你的 Obsidian 笔记。

配置方法（以 Claude Code / Cursor 为例）

在你的 MCP 客户端配置中添加：

{
  "mcpServers": {
    "fns": {
      "url": "http://你的服务器IP:9000/api/mcp",
      "type": "http",
      "headers": {
        "Content-Type": "application/json",
        "Authorization": "Bearer 你的API Token",
        "X-Default-Vault-Name": "MyNotes",
        "X-Client": "Claude Code",
        "X-Client-Version": "1.0",
        "X-Client-Name": "Mac"
      }
    }
  }
}

API Token：在管理面板「复制 API 配置」的 JSON 里能找到。

然后你就可以：

对 AI 说 “帮我把今天的会议纪要整理成一条 Obsidian 笔记”
“在我的知识库里搜索关于「微服务架构」的所有笔记”
“根据我最近的读书笔记，写一篇总结”

AI 读写的所有内容都会通过 FNS 实时同步到你所有设备。

常见问题排查

Q: 手机端同步时断时续？

A: iOS/Android 对后台进程限制很严格。确保：

iOS：关闭低电量模式，把 Obsidian 加入后台刷新白名单
Android：关闭电池优化，允许 Obsidian 自启动
如果长期不用手机端，打开 Obsidian 时等几秒让它完成同步

Q: 同步出现冲突了怎么办？

A: FNS 的冲突处理策略是最后修改时间优先，同时旧版本会存入历史记录。如果真的覆盖了重要内容，去管理面板的历史版本里找回来即可。

Q: 服务器内存/磁盘占用太高？

默认存储数据库用 SQLite，对个人使用足够了，内存很低
如果附件多，建议配置对象存储，不要把大文件堆在服务器本地磁盘
历史版本数量可以在 app.history-keep-versions 里限制

Q: 能不能不部署服务器直接用？

A: 不能。FNS 是 C/S 架构，必须有一个服务端。但部署成本极低——最便宜的云服务器（1C1G）就够跑，或者用家里的 NAS / 树莓派，甚至你闲置的笔记本装个 Linux 也行。

总结：这套方案的优缺点

优点	说明
🔐 数据私有	所有笔记存在你自己的服务器上，不经过任何第三方
⚡ 实时同步	WebSocket 推送，不是定时轮询，改动秒级同步
💰 完全免费	开源 + 自部署，零订阅费用
🧩 功能全面	历史版本、回收站、分享、备份、MCP 一应俱全
🌐 不依赖境外服务	国内服务器部署，速度飞快，不怕墙

需要注意	说明
🖥️ 需要服务器	你得有一台能 24h 运行的服务器（VPS/NAS/树莓派）
🔧 入门门槛	相比 Obsidian Sync 的开箱即用，需要花半小时搭服务端
📱 iOS 后台限制	苹果的后台策略可能导致移动端唤醒后有几秒同步延迟

写在最后

Obsidian 的核心理念是「你的数据，你的控制权」。如果你已经为这个理念选择了一个本地优先的笔记工具，那同步方案也应该匹配这个理念——数据经过你自己的服务器，而不是别人的云。

Fast Note Sync 是目前开源社区里，把「功能全面」和「部署简单」平衡得最好的方案。服务端写得很扎实（Go + WebSocket + React），客户端体验流畅，而且还在高速迭代中。