我平时用Obsidian记东西,最近又把它当成几个AI工具(Claude Code、Claude Desktop、WorkBuddy等)共用的记忆库,让它们干完活把结论写进去,下次接着用。两台Mac之间原来靠插件同步,AI也是直接改本地文件,结果多端同时写的时候,有笔记被整篇覆盖丢了内容。后来改成自建Fast Note Sync服务,Obsidian客户端走它同步,AI工具通过它自带的MCP接口直接读写服务端,问题就解决了。

Fast Note Sync(GitHub上是 haierkeys/fast-note-sync-service)是一个自建的Obsidian同步服务,Go写的,带网页后台、历史版本、REST API和MCP,开源协议Apache-2.0。

一、Docker部署

我是部署在家里的Debian服务器上,配置和数据都挂载到宿主机目录:

services:
 fast-note-sync-service:
   image: haierkeys/fast-note-sync-service:latest
   container_name: fast-note-sync-service
   restart: always
   ports:
     - "9390:9000"
   volumes:
     - /root/docker/obsidian-sync/config:/fast-note-sync/config
     - /root/docker/obsidian-sync/storage:/fast-note-sync/storage

(端口9390是我自己随便选的,容器里是9000。数据库默认是SQLite,存在storage目录里。)

启动以后改一下 config/config.yaml,有三个地方一定要改:

  1. auth-token-key 和 share-token-key:配置样例里给的是公开的默认值,不改的话程序只会警告,照样能启动,但大家都知道这个值,令牌的保护就靠不住了
  2. register-is-enable: false:自己的账号注册完就把注册关掉
  3. 只让反向代理对外开放HTTPS,不要把9000端口直接开到公网

二、群晖反向代理连不上的问题

我是用群晖DSM的反向代理对外提供HTTPS的。

问题现象

网页后台能正常打开,/api/health 也返回数据库已连接,但是Obsidian插件一直连不上。

问题分析

插件同步走的是WebSocket(/api/user/sync),手动发了一个WebSocket请求,服务端日志里是 gws: handshake error,说明请求到了服务端,但是握手不完整。群晖的反向代理默认不转发WebSocket需要的请求头。

解决方法

DSM 控制面板-登录门户-高级-反向代理服务器,编辑这条规则,在 自定义标题 里点 新增,选 WebSocket,保存。改完再测,/api/user/sync 返回 101 Switching Protocols,WebSocket就能正常连上了。

三、Obsidian客户端

装上配套的Obsidian插件,填服务地址和令牌就行。令牌在网页后台里生成。

插件的设置里有一个 离线同步策略,默认是空的(不合并、保留最新),这个后面会说到。

四、AI工具通过MCP接入

服务自带MCP,地址是:

  • https://你的域名/api/mcp(Streamable HTTP,推荐)
  • https://你的域名/api/mcp/sse(SSE,客户端不支持上面那种的时候用)

连上以后有25个工具,笔记的列出、读取、创建、追加、替换、改名、删除、改frontmatter都有,AI写进去的内容会马上通过WebSocket推给在线的Obsidian客户端。

鉴权有两道检查,都要满足:

  1. 令牌要开了MCP权限。在网页后台新建令牌的时候要勾上MCP,没勾的话连接会报错
  2. 请求头 X-Client 要和令牌绑定的客户端类型一致,我的令牌是给Obsidian插件生成的,所以要写 X-Client: ObsidianPlugin,对不上会返回 code 315

另外两个请求头:X-Default-Vault-Name 填库名,不然每次调用都要带库名;X-Client-Name 可选,写上以后历史版本里能看出是哪个工具改的,不写的话分不清。

建议每个AI工具单独建一个令牌,并且只允许访问需要的那个库,哪个工具出问题了单独作废就行。

Claude Code

写在 ~/.claude.json 的 mcpServers 里:

"fns": {
 "type": "http",
 "url": "https://note.example.com/api/mcp",
 "headers": {
   "Authorization": "Bearer 你的令牌",
   "X-Client": "ObsidianPlugin",
   "X-Default-Vault-Name": "Obsidian",
   "X-Client-Name": "ClaudeCode-MacBookAir"
 }
}

Claude Desktop

Desktop的自定义连接器加不了请求头,要用 mcp-remote 中转一下,写在 claude_desktop_config.json 里:

"fns": {
 "command": "npx",
 "args": [
   "-y", "mcp-remote", "https://note.example.com/api/mcp",
   "--header", "Authorization:${FNS_AUTH}",
   "--header", "X-Client:ObsidianPlugin",
   "--header", "X-Default-Vault-Name:Obsidian",
   "--header", "X-Client-Name:ClaudeDesktop-MacBookAir"
 ],
 "env": {
   "FNS_AUTH": "Bearer 你的令牌"
 }
}

Bearer 和令牌中间有个空格,直接写在args里容易出问题,所以放到env里再引用。

第一次连的时候 mcp-remote 报了一个JSON-RPC校验失败的错误,看着像协议不兼容,其实是服务端返回了业务错误(令牌没开MCP权限),mcp-remote解析不了才报的这个错。去后台给令牌勾上MCP就好了。

WorkBuddy

配置在 ~/.workbuddy/mcp.json(注意不是带点的 .mcp.json,那个是运行时生成的,改了不生效),格式和Claude Code差不多,type写http,加上同样的请求头。保存以后要在连接器管理里手动点一下信任。

五、多端同时写会互相覆盖

这是我换成MCP的原因,翻了一下服务端和插件的源码:

  1. 插件的离线同步策略默认是 不合并、保留最新。客户端上传一篇笔记,只要内容和服务端不一样,就整篇覆盖服务端,不会对比基准版本。所以两边同时改同一篇,后写的那个会把先写的整篇盖掉
  2. MCP的写入是直接改服务端数据库的,每篇笔记写的时候有锁,写完再推送给所有客户端,不经过本地文件对比这一步

所以我现在的做法是:

  • 所有AI工具一律走MCP读写,不再直接改本地文件
  • 能追加的就用追加(note_append),局部修改用替换(note_replace),尽量不整篇覆盖
  • 多人共用的索引类笔记只追加或插入一行,不整篇重写
  • 插件的离线同步策略建议改成 最新才合并 或者 手动合并,别用默认的

还有两个小坑:

  • note_create_or_update 没有版本校验,就是整篇覆盖,覆盖前最好先读一遍
  • note_rename 改名以后不会更新笔记的修改时间,插件是按修改时间增量拉取的,所以其他客户端看不到移动后的笔记,旧位置的文件也不会删。改名以后把这篇笔记读出来原样写回去一次,客户端几秒就能收到,旧位置的文件要在各个客户端手动删掉

每次写入服务端都会保留历史版本,MCP里没有查历史的工具,要去网页后台看。

六、忘记网页后台密码

服务端有一个README里没写的命令,只要用户名就能重置密码,不需要旧密码,也不用重启:

docker exec -it fast-note-sync-service sh -c 'cd /fast-note-sync && ./fast-note-sync-service reset-password -u 用户名 -p 新密码'

一定要先 cd /fast-note-sync,因为配置文件用的是相对路径。

用户名也忘了的话,直接查数据库:

sqlite3 /root/docker/obsidian-sync/storage/database/db.sqlite3 "SELECT uid, username, email FROM user;"

注意:AI工具的令牌是能读整个库的,库里如果有密码之类的笔记,最好移出去或者加密,别和AI共用的库放在一起。

最后修改:2026 年 11 月 17 日
如果觉得我的文章对你有用,请酌情赞赏