haierkeys/fast-note-sync-service
GitHub: haierkeys/fast-note-sync-service
基于 Go + WebSocket + React 构建的 Obsidian 笔记实时同步与管理服务器，支持多设备、附件、配置同步及 AI 集成。
Stars: 1338 | Forks: 118
[简体中文](https://github.com/haierkeys/fast-note-sync-service/blob/master/docs/README.zh-CN.md) / [English](https://github.com/haierkeys/fast-note-sync-service/blob/master/README.md) / [日本語](https://github.com/haierkeys/fast-note-sync-service/blob/master/docs/README.ja.md) / [한국어](https://github.com/haierkeys/fast-note-sync-service/blob/master/docs/README.ko.md) / [繁體中文](https://github.com/haierkeys/fast-note-sync-service/blob/master/docs/README.zh-TW.md)
如有任何问题，请创建新的 [issue](https://github.com/haierkeys/fast-note-sync-service/issues/new)，或加入我们的 Telegram 群组寻求帮助：[https://t.me/obsidian_users](https://t.me/obsidian_users)
中国大陆用户强烈推荐使用腾讯 `cnb.cool` 镜像仓库：[https://cnb.cool/haierkeys/fast-note-sync-service](https://cnb.cool/haierkeys/fast-note-sync-service)
## 🎯 核心功能
* **🧰 原生 MCP（Model Context Protocol）支持**：
* `FNS` 可作为 MCP 服务器连接到兼容的 AI 客户端（如 `Cherry Studio` 和 `Cursor`），使 AI 能够读写私有笔记和附件，所有更改实时同步到各个终端。
* **🚀 REST API 支持**：
* 提供标准 REST API 端点，支持编程操作（如自动化脚本、AI 助手集成），对 Obsidian 笔记执行 CRUD 操作。
* 详情请参考 [RESTful API 文档](/docs/REST_API.md) 或 [OpenAPI 文档](/docs/swagger.yaml)。
* **💻 Web 管理面板**：
* 内置现代化仪表盘，可轻松创建用户、生成插件配置、管理仓库及浏览笔记内容。
* **🔄 多设备笔记同步**：
* 支持自动创建 **Vault**。
* 支持笔记管理（创建、读取、更新、删除），毫秒级实时更新分发到所有活跃设备。
* **🖼️ 附件同步**：
* 完美支持图片等非笔记文件的同步。
* 支持大附件的分块上传/下载，可配置分块大小以提升同步效率。
* **⚙️ 配置同步**：
* 支持同步 `.obsidian` 配置。
* 支持同步 `PDF` 阅读进度状态。
* **📝 笔记历史**：
* 可直接从网页或插件客户端查看每条笔记的历史修改版本（需要服务器 v1.2+）。
* **🗑️ 回收站**：
* 删除的笔记自动进入回收站。
* 支持从回收站恢复笔记（附件恢复将在后续更新中推出）。
* **🚫 离线同步策略**：
* 支持离线笔记编辑的自动冲突解决合并（需要插件配置）。
* 支持重新连接时自动清理或恢复离线删除的内容（需要插件配置）。
* **🔗 分享功能**：
* 创建/取消笔记分享。
* 自动解析分享笔记中引用的附件，如图片、音频和视频。
* 提供分享笔记的访问统计。
* 为分享笔记设置访问密码。
* 为分享笔记生成短链接。
* **📂 目录同步**：
* 支持文件夹的创建、重命名、移动和删除同步。
* **🌳 自动化 Git 集成**：
* 当附件和笔记发生更改时，自动更新并推送到远程 Git 仓库。
* 任务完成后自动释放系统内存。
* **☁️ 多存储备份与单向镜像同步**：
* 兼容多种存储协议，包括 S3、阿里云 OSS、Cloudflare R2、WebDAV 和本地文件系统。
* 支持定时全量/增量 ZIP 归档备份。
* 支持将 Vault 资源单向镜像同步到远程存储。
* 自动清理过期备份，保留周期可自定义。
* **🗄️ 多数据库支持**：
* 原生支持 SQLite、MySQL 和 PostgreSQL，满足从个人到团队环境的不同部署规模需求。
## ⏱️ 更新日志
- ♨️ [查看更新日志](/docs/CHANGELOG.en.md)
## 🗺️ 路线图
- [ ] 添加 WebSocket `Protobuf` 传输支持以提升同步效率。
- [ ] 隔离和优化授权机制以提高整体安全性。
- [ ] 实现实时 WebGui 笔记更新。
- [ ] 添加客户端之间的点对点消息传输（用于笔记/附件以外的消息，类似 LocalSend；保存到服务器，不保存到本地）。
- [ ] 完善所有文档和帮助指南。
- [ ] 提供更多内网穿透（中继网关）集成。
* 快速部署设置：只需提供服务器地址、用户名和密码即可轻松部署 FNS 服务器。
- [ ] 优化现有的离线笔记合并策略并引入冲突解决系统。
我们正在持续改进，以上代表了我们未来的路线图计划：
## 🚀 快速部署
我们提供多种安装方式。强烈推荐使用**一键脚本**或 **Docker**。
### 方式一：一键脚本（推荐）
自动检测系统环境，完成安装并注册服务。
```
bash <(curl -fsSL https://raw.githubusercontent.com/haierkeys/fast-note-sync-service/master/scripts/quest_install.sh)
```
中国大陆用户可使用腾讯 `cnb.cool` 镜像：
```
bash <(curl -fsSL https://cnb.cool/haierkeys/fast-note-sync-service/-/git/raw/master/scripts/quest_install.sh) --cnb
```
**脚本主要操作：**
* 自动下载适配当前操作系统的发行版二进制文件。
* 默认安装到 `/opt/fast-note`，并在 `/usr/local/bin/fns` 下创建全局快捷命令 `fns`。
* 配置并启动 Systemd（Linux）或 Launchd（macOS）服务以实现开机自启。
* **管理命令**：`fns [install|uninstall|start|stop|status|update|menu]`
* **交互式菜单**：直接运行 `fns` 进入交互式菜单，支持安装/升级、服务控制、开机配置以及在 GitHub 和 CNB 镜像源之间切换。
### 方式二：Docker 部署
#### Docker 运行
```
# 1. 拉取镜像
docker pull haierkeys/fast-note-sync-service:latest
# 2. 启动容器
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
```
#### 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" # RESTful API & WebSocket port, where /api/user/sync is the WebSocket endpoint
volumes:
- ./storage:/fast-note-sync/storage # Data storage
- ./config:/fast-note-sync/config # Configuration files
```
启动服务：
```
docker compose up -d
```
### 方式三：手动二进制安装
从 [Releases](https://github.com/haierkeys/fast-note-sync-service/releases) 下载适用于您操作系统的最新版本，解压后运行：
```
./fast-note-sync-service run -c config/config.yaml
```
## 📖 使用指南
1. **访问管理面板**：
在浏览器中打开 `http://{服务器IP}:9000`。
2. **初始设置**：
首次访问时注册账户。（如需禁用公开注册，请在配置文件中设置 `user.register-is-enable: false`）
3. **配置客户端**：
登录管理面板，点击**"复制 API 配置"**。
4. **连接 Obsidian**：
打开 Obsidian，进入插件设置页面，粘贴复制的配置。
## ⚙️ 配置
默认配置文件为 `config.yaml`。应用程序会自动在**根目录**或 **config/** 目录中搜索。
查看完整配置示例：[config/config.yaml](https://github.com/haierkeys/fast-note-sync-service/blob/master/config/config.yaml)
## 🌐 Nginx 反向代理示例
查看完整配置示例：[https-nginx-example.conf](https://github.com/haierkeys/fast-note-sync-service/blob/master/scripts/https-nginx-example.conf)
## 🧰 MCP（Model Context Protocol）支持
FNS 现已原生支持 **MCP（Model Context Protocol）**，提供 **SSE** 和 **StreamableHTTP** 两种传输协议。
您可以将 FNS 作为 MCP 服务器直接连接到兼容的 AI 客户端，如 Cherry Studio、Cursor、Claude Code 和 hermes-agent。连接后，AI 即可读写您的私有笔记和附件。同时，MCP 集成生成的所有编辑将通过 WebSocket 实时同步到您的所有设备终端。
### 通用头部参数
无论使用哪种传输模式，均支持以下头部：
- **Authorization 头部**：`Authorization: Bearer <您的 API Token>`（从 WebGUI 的复制 API 配置中获取）
- **可选头部**：`X-Default-Vault-Name: `（指定 MCP 操作的默认 Vault。如果工具调用未指定 Vault 参数，则使用此值）
- **可选头部**：`X-Client: <客户端类型>`（连接到 MCP 的客户端类型，如 Cherry Studio / OpenClaw）
- **可选头部**：`X-Client-Version: <客户端版本>`（客户端版本，如 1.1）
- **可选头部**：`X-Client-Name: <客户端名称>`（客户端设备名称，如 Mac）
### 集成：StreamableHTTP 模式（推荐）
StreamableHTTP 是 MCP 生态系统的标准传输协议。单个端点处理所有请求，对防火墙友好，且被较新的 MCP 客户端（如 Claude Code 和 hermes-agent）原生支持。
- **端点 URL**：`http://<您的服务器IP或域名>:<端口>/api/mcp`
- **请求方法**：`POST`（发送请求/通知）、`GET`（监听服务端推送通知）、`DELETE`（终止会话）
#### 示例：Claude Code / hermes-agent / Cursor 等
*（注意：请将 ``、``、`` 和 `` 替换为您的实际信息）*
```
{
"mcpServers": {
"fns": {
"url": "http://:/api/mcp",
"type": "http",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ",
"X-Default-Vault-Name": "",
"X-Client": "",
"X-Client-Version": "",
"X-Client-Name": ""
}
}
}
}
```
### 集成：SSE 模式（向后兼容）
SSE 模式是传统的传输协议，完全保留以实现向后兼容。适用于仅支持 SSE 的 MCP 客户端（如 Cherry Studio）。
- **端点 URL**：`http://<您的服务器IP或域名>:<端口>/api/mcp/sse`
#### 示例：Cherry Studio / Cline 等
*（注意：请将 ``、``、`` 和 `` 替换为您的实际信息）*
```
{
"mcpServers": {
"fns": {
"url": "http://:/api/mcp/sse",
"type": "sse",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ",
"X-Default-Vault-Name": "",
"X-Client": "",
"X-Client-Version": "",
"X-Client-Name": ""
}
}
}
}
```
## 🔗 客户端与客户端插件
* Obsidian Fast Note Sync 插件
* [Obsidian Fast Note Sync 插件](https://github.com/haierkeys/obsidian-fast-note-sync) / [cnb.cool 镜像](https://cnb.cool/haierkeys/obsidian-fast-note-sync)
* 第三方客户端
* [FastNodeSync-CLI](https://github.com/Go1c/FastNodeSync-CLI) 基于 Python 和 FNS WebSocket 协议实现的命令行客户端，支持双向实时同步。适用于无头 Linux 服务器（如 OpenClaw），提供与 Obsidian 桌面/移动端客户端同等的同步能力。
* [go-fast-note-sync](https://github.com/erichll/go-fast-note-sync) 基于 Go 和 FNS WebSocket 协议的 Go CLI 后台同步守护进程，主要针对无头 Linux 环境，同时支持 macOS 和 Windows。
* [Fast-note-sync-docker](https://github.com/youpingfang/obsidian-note-sync-docker) 基于 Docker、Python 和 FNS WebSocket 协议的快速容器化部署方案，实现笔记 Vault 和配置文件同步到远程服务器。
Fast Note Sync Service
高性能、低延迟的笔记同步、在线管理及远程 REST API 服务平台
基于 Golang + WebSocket + React 构建
客户端数据提供需要：Obsidian Fast Note Sync 插件
标签：API服务, CNB镜像, EVTX分析, GitHub开源项目, Golang, Go语言, Obsidian插件, React, REST API, SaaS, Syscalls, WebSocket, 云同步, 低延迟, 依赖分析, 分布式存储, 即时同步, 后端服务, 在线笔记管理, 多语言支持, 威胁情报, 安全测试框架, 安全编程, 实时同步, 客户端数据同步, 幻觉检测, 开发者工具, 效率工具, 数据同步服务, 日志审计, 测试用例, 漏洞探索, 程序破解, 笔记同步, 笔记应用, 笔记管理, 网络安全研究, 脚本检测, 自托管笔记服务, 请求拦截, 远程服务