我平时用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,有三个地方一定要改:
auth-token-key和share-token-key:配置样例里给的是公开的默认值,不改的话程序只会警告,照样能启动,但大家都知道这个值,令牌的保护就靠不住了register-is-enable: false:自己的账号注册完就把注册关掉- 只让反向代理对外开放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客户端。
鉴权有两道检查,都要满足:
- 令牌要开了MCP权限。在网页后台新建令牌的时候要勾上MCP,没勾的话连接会报错
- 请求头
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的原因,翻了一下服务端和插件的源码:
- 插件的离线同步策略默认是 不合并、保留最新。客户端上传一篇笔记,只要内容和服务端不一样,就整篇覆盖服务端,不会对比基准版本。所以两边同时改同一篇,后写的那个会把先写的整篇盖掉
- 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共用的库放在一起。