三股水
Fast Note Sync 完整介绍与部署教程
插件 1218 字 约 4 分钟
本文从 Obsidian 撰写发布

Fast Note Sync 完整介绍与部署教程

一、项目概述

Fast Note Sync 是一个为 Obsidian 打造的开源、可私有化部署的实时同步插件。它追求"丝般顺滑"的多端同步体验，被社区用户视为官方同步服务的有力替代方案。

核心特点

  • 极速实时同步：通过 WebSocket 协议实现毫秒级同步，笔记的增删改在手机、电脑等设备间瞬间生效
  • 全面数据同步：不仅同步 .md 笔记，还支持图片、视频、PDF 等附件，以及 .obsidian 目录下的插件、主题、快捷键等配置
  • 私有化部署，数据自控：需自建服务端（支持 NAS、云服务器等），所有笔记数据完全由自己掌控
  • 版本历史与回收站：在 Web 管理界面或插件中可查看和恢复历史版本
  • 离线编辑支持：设备离线时的修改，联网后自动合并同步
  • 笔记分享：一键生成分享链接，方便协作

二、核心创新

1. 原生 MCP 支持

原生支持 MCP（模型上下文协议），可接入 Cursor、Cherry Studio 等 AI 客户端，让 AI 读写你的私有笔记和附件。所有 AI 产生的修改会实时同步回你的各端设备。

2. 完善的 API 与生态

提供标准的 REST API 和 WebSocket 协议，支持脚本、自动化工具或自开发程序读写笔记。社区已衍生 CLI 命令行工具、Docker 同步方案等。

3. 全栈式同步策略

  • 语义级合并：离线编辑联网后自动合并，避免内容丢失
  • 配置与附件全同步：插件、主题、快捷键多端体验一致
  • 附件云预览：手机端可预览附件而不下载，节省空间
  • 精细同步规则：支持同步白名单和排除规则

三、开源情况

完全开源，插件端和服务端代码均在 GitHub 上：

组件开源仓库地址
Obsidian 客户端插件https://github.com/haierkeys/obsidian-fast-note-sync
服务端 (Fast Note Sync Service)https://github.com/haierkeys/fast-note-sync-service
  • 服务端采用 Golang 开发，高性能、低内存占用
  • Web 管理面板使用 React 构建
  • 国内访问慢可使用腾讯云镜像：https://cnb.cool/haierkeys/fast-note-sync-service

四、部署教程

整体流程

部署服务端 → 访问 Web 管理面板（http://服务器IP:9000）
→ 注册管理员账号 → 关闭开放注册
→ 在"笔记库"中生成授权配置
→ 配置 Obsidian 客户端插件 → 同步成功 ✅

第一步：部署服务端

方式一：一键脚本（最推荐新手）

在 Linux 或 macOS 终端中运行：

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

# 国内用户使用腾讯云镜像源（速度更快）
bash <(curl -fsSL https://cnb.cool/haierkeys/fast-note-sync-service/-/git/raw/master/scripts/quest_install.sh) --cnb

方式二：Docker 部署（最灵活）

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

# 运行容器（替换路径为你设备上的实际路径）
docker run -tid --name fast-note-sync-service \
    -p 9000:9000 \
    -v /你的宿主机存储路径/storage/:/fast-note-sync/storage/ \
    -v /你的宿主机配置路径/config/:/fast-note-sync/config/ \
    haierkeys/fast-note-sync-service:latest

方式三：手动二进制安装

从 GitHub Releases 页面 下载对应系统版本，解压后直接运行。

第二步：初始化服务与安全设置

  1. 访问管理面板：浏览器打开 http://你的服务器IP地址:9000
  2. 注册管理员账号：首次访问注册，第一个账号自动成为管理员
  3. ⚠️ 关闭开放注册：在配置文件中将 user.register-is-enable 设置为 false，防止他人随意注册
  4. 生成授权配置：在管理面板左侧「笔记库」中，点击「一键授权 Obsidian」或手动生成 Token

第三步：配置 Obsidian 客户端

  1. 在 Obsidian 中：设置 → 社区插件 → 浏览，搜索 Fast Note Sync 并安装
  2. 进入插件设置页面，粘贴 Web 管理面板复制的授权配置
  3. 电脑端通常可使用「一键导入」功能自动完成

第四步：外网访问（可选）

  • 云服务器部署：自带公网 IP 或域名，直接使用该地址
  • 家中 NAS/电脑部署：需通过内网穿透工具（如贝锐花生壳、Tailscale）将内网地址映射为公网域名
安全提示：服务暴露公网后，请为服务端和路由器设置强密码，谨慎管理授权 Token。

五、支持的存储与备份

支持通过 S3 协议接入多种对象存储：

  • 通用 S3 协议：AWS S3、Minio
  • 主流云服务商：阿里云 OSS、Cloudflare R2
  • 其他协议：WebDAV、本地存储

关于七牛云 Kodo

搜索结果中未直接提及内置支持七牛云。但由于七牛云兼容 AWS S3 协议，可尝试通用 S3 模式手动配置：

  1. 获取七牛云对应区域的 S3 Endpoint（如华东：s3.cn-east-1.qiniucs.com）
  2. 准备 AccessKey 和 SecretKey
  3. 在 Fast Note Sync 备份设置中填入上述信息测试连接
注意：七牛云不支持匿名访问，必须携带签名信息。

六、官方信息渠道

渠道用途链接
插件端 GitHub下载、反馈、开发计划https://github.com/haierkeys/obsidian-fast-note-sync
服务端 GitHub部署文档、API 接口https://github.com/haierkeys/fast-note-sync-service
Obsidian 社区插件页安装、查看介绍https://community.obsidian.md/plugins/fast-note-sync
Telegram 用户群交流、求助https://t.me/obsidian_users

七、自定义修改 Web 界面

由于完全开源，你可以修改 Web 管理面板界面：

  1. 克隆源码：

    git clone https://github.com/haierkeys/fast-note-sync-service.git
  2. 定位前端代码：项目基于 React，前端代码通常在 web、frontend 或 ui 目录下
  3. 修改代码：自由调整布局、样式、功能按钮、文案等

  4. 编译部署：

    npm run build   # 或 yarn build

    将生成的静态文件替换服务端使用的对应文件

  5. 贡献上游：如有好的改进，可通过 GitHub Issue 或 Pull Request 与开发者沟通

八、注意事项

  • ⚠️ 服务端依赖：插件无法独立工作，必须搭配服务端
  • ⚠️ 配置同步尚在测试：该功能目前仍处于测试阶段
  • ⚠️ 外网需穿透：需自行配置反向代理或内网穿透，并确保支持 WebSocket 协议
  • 🔜 端到端加密：已在开发路线图中，未来可放心托管他人服务器
  • 🛡️ 安全第一：公网部署务必设置强密码并关闭开放注册

九、总结

Fast Note Sync 是一款功能强大、完全开源、数据自控的 Obsidian 同步方案。其核心优势在于：

  • 实时同步速度极快（WebSocket 毫秒级）
  • 数据完全私有（自建服务端）
  • 生态开放（MCP 支持、REST API、社区衍生工具）
  • 全平台体验一致（同步配置与附件）

适合追求数据掌控、对同步速度和稳定性有高要求的 Obsidian 用户。

部署门槛在于需要一台服务器/NAS，但一键脚本和 Docker 已极大简化流程。未来端到端加密上线后，将惠及更多普通用户。

# Obsidian
😊
提交