高性能、低延迟的笔记同步、在线管理和远程 REST API 服务平台。
High-performance, low-latency note synchronization, online management, and remote REST API service platform
Built with Golang + Websocket + React
Data provisioning requires integration with the client plugin: Obsidian Fast Note Sync Plugin
--- ## Key Features * ** Native MCP (Model Context Protocol) Support**: * `FNS` can be integrated as an MCP server into compatible AI clients such as `Cherry Studio` and `Cursor`. This enables the AI to read and write your personal notes and attachments, with all changes synchronized across all clients in real-time. * ** REST API Support**: * Provides standard REST API interfaces to support programmatic CRUD operations on Obsidian notes (e.g., via automation scripts or AI assistant integrations). * For details, please refer to the [RESTful API Documentation](docs/REST_API.md) or [OpenAPI Documentation](docs/swagger.yaml). * ** Web Admin Panel**: * Built-in modern administration interface to easily create users, generate plugin configurations, and manage vaults and note content. * Supports WebGUI OIDC login. See the [OIDC login runbook](docs/runbook/OIDC.en.md). * ** Multi-Device Note Synchronization**: * Supports automatic creation of `Vaults`. * Supports note management (CRUD), with millisecond-level real-time change distribution to all online devices. * **️ Attachment Sync Support**: * Perfectly supports synchronization of non-note files such as images. * Supports chunked upload and download for large attachments, with configurable chunk sizes to improve sync efficiency. * **⚙️ Configuration Sync**: * Supports synchronization of `.obsidian` configuration files. * Supports `PDF` reading progress synchronization. * ** Note History**: * View historical revision versions of each note via the Web UI or client plugin. * (Requires server v1.2+) * **️ Trash Bin**: * Deleted notes automatically go to the trash bin. * Supports restoring notes from the trash. (Attachment restoration feature will be added sequentially in the future.) * ** Offline Synchronization Strategy**: * Supports automatic merging of offline note edits. (Requires client plugin configuration) * Offline deletions are automatically resolved (re-synced or deleted) upon reconnection. (Requires client plugin configuration) * ** Sharing Feature**: * Easily share or unshare notes. * Automatically parses images, audio, video, and other attachments referenced in shared notes. * Provides sharing access statistics. * Allows password protection for shared notes. * Supports generating short URLs for shared notes. * ** Folder Sync**: * Supports folder synchronization for creation, renaming, moving, and deletion. * ** Git Automation**: * Automatically updates and pushes changes to a remote Git repository when notes or attachments change. * Automatically releases system memory after tasks complete. * **☁️ Multi-Storage Backup & One-way Mirror Sync**: * Adapts to S3, OSS, R2, WebDAV, local filesystem, and other storage protocols. * Supports scheduled full or incremental ZIP archive backups. * Supports one-way mirror synchronization of Vault resources to remote storage. * Automatically cleans up expired backups with custom retention days. * **️ Multi-Database Support**: * Native support for mainstream databases including SQLite, MySQL, and PostgreSQL, meeting deployment needs from individuals to teams. ## ☕ Sponsorship and Support - If you find this plugin useful and want to support its ongoing development, please support me in the following ways: | Ko-fi *Outside China* | | WeChat Pay *China* | |--------------------------------------------------------------------------------------------------|----|------------------------------------------------| | [](https://ko-fi.com/haierkeys) | or | | - Sponsor List: - Support.en.md - Support.en.md (cnb.cool mirror repository) ## ⏱️ Changelog - ♨️ [Click to View Changelog](docs/CHANGELOG.en.md) ## ️ Roadmap - [ ] Add support for WebSocket `Protobuf` transfer format to enhance synchronization efficiency. - [ ] Isolate and optimize the existing authorization mechanism to improve overall security. - [ ] Add real-time note updates to the Web UI. - [ ] Add peer-to-peer message transfer between clients (non-notes & attachments, similar to LocalSend; client-side storage is not supported, but server-side is). - [ ] Improve various help documentations. - [ ] Provide support for more intranet penetration (relay gateway) options. - [ ] Quick deployment plan: * Deploy the FNS server by simply providing the server address (public IP) and account credentials. - [ ] Optimize the existing offline note merging scheme and introduce conflict resolution mechanisms. We are continuously improving, and here is our future development roadmap: > **If you have suggestions for improvement or new ideas, feel free to share them with us by submitting an issue — we will carefully evaluate and adopt suitable ones.** ## Quick Deployment We provide multiple installation methods. We highly recommend using the **One-click Script** or **Docker**. ### Method 1: One-click Script (Recommended) Automatically detects the system environment and completes the installation and service registration. ```bash bash <(curl -fsSL https://raw.githubusercontent.com/haierkeys/fast-note-sync-service/master/scripts/quest_install.sh) ``` For users in China, you can use the Tencent `cnb.cool` mirror source: ```bash bash <(curl -fsSL https://cnb.cool/haierkeys/fast-note-sync-service/-/git/raw/master/scripts/quest_install.sh) --cnb ``` **Main Script Behaviors:** * Automatically downloads the Release binary adapted to the current system. * Installs to `/opt/fast-note` by default and creates a global shortcut command `fns` in `/usr/local/bin/fns`. * Configures and starts Systemd (Linux) or Launchd (macOS) services to enable startup on boot. * **Management commands**: `fns [install|uninstall|start|stop|status|update|menu]` * **Interactive menu**: Run `fns` directly to enter the interactive menu, supporting install/upgrade, service control, startup configuration, and switching between GitHub and CNB mirrors. ----- ### Method 2: Docker Deployment #### Docker Run ```bash # 1. Pull Image docker pull haierkeys/fast-note-sync-service:latest # 2. Start Container 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 Create the `docker-compose.yaml` file: ```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 interface address) volumes: - ./storage:/fast-note-sync/storage # Data storage - ./config:/fast-note-sync/config # Configuration files ``` Start the service: ```bash docker compose up -d ``` ----- ### Method 3: Manual Binary Installation Download the latest version for your system from [Releases](https://github.com/haierkeys/fast-note-sync-service/releases), extract it, and run: ```bash ./fast-note-sync-service run -c config/config.yaml ``` ## User Guide 1. **Access Admin Panel**: Open `http://{Server_IP}:9000` in your browser. 2. **Initial Setup**: Register an account on your first visit. *(To disable registration, set `user.register-is-enable: false` in the configuration file)* 3. **Configure Client**: Log in to the admin panel and click **"Copy API Config"**. 4. **Connect to Obsidian**: Open the Obsidian plugin settings page and paste the configuration information you just copied. ## ⚙️ Configuration Description The default configuration file is `config.yaml`. The application automatically searches in the **root directory** or the **config/** directory. View the complete configuration example: [config/config.yaml](https://github.com/haierkeys/fast-note-sync-service/blob/master/config/config.yaml) ## Nginx Reverse Proxy Example View the complete configuration example: [https-nginx-example.conf](https://github.com/haierkeys/fast-note-sync-service/blob/master/scripts/https-nginx-example.conf) ## MCP (Model Context Protocol) Support FNS now natively supports **MCP (Model Context Protocol)** and provides both **SSE** and **StreamableHTTP** transport protocols. You can integrate FNS as an MCP server directly into compatible AI clients like Cherry Studio, Cursor, Claude Code, and hermes-agent. Once integrated, the AI will gain the ability to read and write your personal notes and attachments. In addition, all modifications made via MCP will be synchronized to your client devices in real-time via WebSocket. For OAuth-protected MCP deployments with Stytch, see [docs/runbook/mcp-oauth-stytch.md](docs/runbook/mcp-oauth-stytch.md) ([简体中文](docs/runbook/mcp-oauth-stytch.zh-CN.md), [繁體中文](docs/runbook/mcp-oauth-stytch.zh-TW.md)). ### Common Request Header Parameters The following request headers are supported regardless of the transport mode used: - **Authorization Header**: `Authorization: Bearer ` (obtained from the Copy API Config option in the WebGUI) - **Optional Header**: `X-Default-Vault-Name: ` (specifies the default Vault name for MCP operations if no `vault` parameter is provided during a tool call) - **Optional Header**: `X-Client: ` (the type of client connecting to MCP, e.g., `Cherry Studio`, `OpenClaw`) - **Optional Header**: `X-Client-Version: ` (the version of the client connecting, e.g., `1.1`) - **Optional Header**: `X-Client-Name: ` (the name of the client connecting, e.g., `Mac`) --- ### Integration Config: StreamableHTTP Mode (Recommended) StreamableHTTP is the standard transport protocol in the MCP ecosystem. A single endpoint can handle all requests, making it more firewall-friendly. It is natively supported by newer MCP clients (such as Claude Code and hermes-agent). - **Interface Address**: `http://:/api/mcp` - **Request Method**: `P暂无开放 Issues，或尚未同步最近议题。