Obsidian 同步服务器搭建教程：自建笔记同步与知识库

摘要

Obsidian 的笔记以本地 Markdown 文件形式存放，跨设备同步需要自己解决。本文给出两种自建同步方案：基于 WebDAV 的通用方案，以及基于 Git 的版本化方案，分别说明部署步骤、客户端配置、冲突处理和适用场景，并补充多端验证与备份策略。两种方案都能让笔记数据完全保留在自己的服务器上。

一、两种方案怎么选

Obsidian 的笔记本质上是一个装满 Markdown 文件的文件夹，所以任何能同步文件夹的方式都能用。自建常见的是下面两条路径。

WebDAV 同步：服务端提供标准文件协议，客户端按文件修改时间同步。优点是移动端支持较好、配置直观、对非技术用户友好。缺点是没有版本历史，冲突处理依赖插件策略，多端同时编辑同一文件时可能覆盖。

Git 同步：把笔记库作为一个代码仓库管理，每次同步产生一次提交。优点是完整的版本历史，任何一次修改都能回溯，冲突有成熟的合并机制。缺点是移动端体验一般，需要理解基本的版本控制概念。

选择建议：

本文两种都讲，可以按需选择或组合使用。

二、配置要求

笔记同步的数据量通常不大，纯文本笔记几年积累也就几十 MB，主要体积来自图片附件。

需要放通的端口：

三、方案一：WebDAV 同步

用一个轻量 WebDAV 服务端即可，不需要部署完整的网盘程序。

部署服务端

mkdir -p ~/apps/webdav && cd ~/apps/webdav
mkdir -p data

编写 compose.yaml：

services:
  webdav:
    image: hacdias/webdav:v5
    ports:
      - "127.0.0.1:6065:6065"
    volumes:
      - ./data:/data
      - ./config.yml:/config.yml:ro
    command: -c /config.yml
    restart: unless-stopped

创建配置文件 config.yml：

address: 0.0.0.0
port: 6065
prefix: /
directory: /data

users:
  - username: notes
    password: "替换为强密码"
    permissions: CRUD

端口绑定到 127.0.0.1 意味着外部无法直接访问，必须经过反向代理。这样可以统一由代理层处理 HTTPS。

启动服务：

docker compose up -d
docker compose ps

配置反向代理

notes.example.com {
    reverse_proxy 127.0.0.1:6065
    request_body {
        max_size 2GB
    }
}

request_body max_size 需要覆盖笔记中最大的附件。默认限制偏小时，插入大图片会同步失败。

客户端配置

Obsidian 本身不内置 WebDAV 功能，需要安装社区同步插件：

1. 在 Obsidian 中打开设置，进入第三方插件，关闭安全模式。
2. 浏览社区插件，搜索支持 WebDAV 的同步插件并安装启用。
3. 在插件设置中填入服务地址 https://notes.example.com、用户名和密码。
4. 设置同步方向和冲突处理策略。

冲突策略建议选择保留两份而非自动覆盖。 笔记是不可再生的内容，宁可留下两个版本手动合并，也不要让自动覆盖悄悄丢掉一段文字。

在每台设备上重复同样的配置，服务地址和账号保持一致。

四、方案二：Git 同步

Git 方案需要先有一个 Git 服务端。如果已经部署了自建代码托管服务，直接用它即可；没有的话，用系统自带的 Git 加 SSH 就能满足需求。

创建裸仓库

在服务器上：

sudo useradd -m -s /bin/bash git
sudo su - git
mkdir -p ~/repos/notes.git
cd ~/repos/notes.git
git init --bare
exit

配置密钥登录

在本地电脑生成密钥（如果已有可跳过）：

ssh-keygen -t ed25519 -C "obsidian-sync"

把公钥添加到服务器：

sudo su - git
mkdir -p ~/.ssh && chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys   # 粘贴本地公钥内容
chmod 600 ~/.ssh/authorized_keys
exit

验证连接：

ssh -T git@服务器IP

初始化本地笔记库

在 Obsidian 笔记库目录下：

cd ~/Documents/MyVault
git init
git remote add origin git@服务器IP:~/repos/notes.git

创建 .gitignore，排除不需要同步的内容：

.obsidian/workspace.json
.obsidian/workspace-mobile.json
.trash/
.DS_Store

workspace.json 记录的是窗口布局和打开的标签页，每台设备都不一样，纳入同步会导致频繁冲突。这个文件必须排除。

首次提交：

git add .
git commit -m "初始化笔记库"
git branch -M main
git push -u origin main

客户端配置

在 Obsidian 中安装 Git 同步插件，设置自动提交间隔和自动拉取间隔。建议开启启动时拉取、关闭前提交，减少手动操作。

其他设备上先克隆仓库，再用 Obsidian 打开该目录：

git clone git@服务器IP:~/repos/notes.git MyVault

移动端对 Git 的支持较弱，如果手机使用频繁，建议移动端改用 WebDAV 方案访问同一目录。

五、验证同步是否可用

不要只在一台设备上测试，多端验证才能发现真正的问题。

基础连通性

WebDAV 方案：

curl -u notes:密码 -X PROPFIND https://notes.example.com --data ''

返回 XML 格式的目录信息说明服务正常。

Git 方案：

ssh -T git@服务器IP
git ls-remote origin

单向同步：在设备 A 上新建一条笔记并触发同步，在设备 B 上拉取后确认能看到该笔记。

双向同步：在设备 B 上修改这条笔记并同步回去，在设备 A 上确认改动已生效。

附件同步：在笔记中插入一张图片并同步，确认另一端图片能正常显示。图片路径问题在纯文字测试中不会暴露。

冲突处理：这一项建议主动测试。断开网络，在两台设备上分别修改同一条笔记，再恢复网络同步。观察是提示冲突、生成副本还是直接覆盖。了解实际行为后才能放心使用。

移动端可用：在手机上完成一次完整的编辑加同步流程。移动端的表现往往与桌面端有差异。

六、常见问题与排查

WebDAV 连接失败

检查服务地址是否包含 https 前缀、证书是否有效、用户名密码是否正确。部分客户端对自签名证书支持不佳，建议使用受信任的证书。

同步后笔记内容丢失或被覆盖

多为冲突策略设置为自动覆盖所致。改为保留两份，并在发现冲突副本时手动合并。这类问题一旦发生难以挽回，所以事前配置比事后补救重要。

Git 推送被拒绝

通常是远端有本地没有的提交。先拉取再推送：

git pull --rebase origin main
git push origin main

每次同步都产生大量变更

检查 .gitignore 是否正确排除了工作区状态文件。workspace.json 每次打开 Obsidian 都会变化，不排除会造成持续冲突。

附件太大导致同步缓慢

Git 不擅长处理大二进制文件，仓库体积会随历史累积膨胀。笔记中图片较多时，建议：WebDAV 方案直接同步；Git 方案考虑把附件目录排除，改用其他方式同步附件。

移动端同步不稳定

移动系统会限制后台进程。建议在应用处于前台时手动触发同步，不要完全依赖后台自动同步。

多端时间不一致导致同步判断错误

WebDAV 方案依赖文件修改时间判断新旧。确认服务器和各客户端的时间设置正确，时区偏差会导致同步逻辑出错。

七、备份与维护

笔记是长期积累的个人资产，价值随时间增长，备份不能省。

服务端备份

WebDAV 方案直接打包数据目录：

sudo tar -czf ~/notes-$(date +%Y%m%d).tar.gz -C ~/apps/webdav data

Git 方案备份裸仓库：

sudo tar -czf ~/notes-repo-$(date +%Y%m%d).tar.gz -C /home/git/repos notes.git

写成脚本加入定时任务，并把备份同步到对象存储。留在同一台服务器上的备份，在服务器故障时会一起丢失。

本地副本也是一层保护

这两种方案都有个天然优势：每台客户端设备上都保存着完整的笔记副本。即使服务端完全损坏，任何一台设备的本地文件都能作为恢复来源。这是文件型笔记相比纯云端服务的一大优势，日常无需过度担心。

但要注意：如果误删操作被同步到了所有设备，本地副本也会跟着消失。这正是 Git 方案的价值所在——历史提交里还留着删除前的版本。

恢复演练

用备份数据在另一个目录还原一份，确认笔记结构完整、附件能打开。建议在正式依赖这套方案前完成一次。

变更前创建快照

调整服务配置或升级前给实例创建快照。回滚会把整块系统盘恢复到快照时间点，之后的数据变更会被清除，运行中的实例会自动关机。使用存储型套餐的实例不支持创建快照。

日常检查

• 每周确认备份任务执行成功。
• 留意同步日志中的错误提示，不要忽略反复出现的冲突警告。
• 定期检查磁盘剩余空间，附件会持续增长。
• 服务端保持 HTTPS，账号密码足够强。

内容边界

笔记中可能包含个人隐私和工作资料。自建方案的优势是数据留在自己手里，但仍要注意：服务端账号密码要足够强；不要在防火墙中把服务端口对全网无限制开放；共享知识库给他人时，确认内容不包含不应外传的信息。

部署完成后，如果还想为多个自建服务配置统一的域名入口，或把附件归档到对象存储以控制服务器磁盘增长，可以作为下一步方向。

笔记同步这类轻量服务，轻量应用服务器的入门规格即可承载，配合快照能快速恢复环境；备份归档可以使用对象存储 COS，按实际用量计费。