1. 项目概述为什么我们需要一个免费的 Obsidian 同步方案如果你和我一样是一个重度依赖 Obsidian 进行知识管理和写作的人那么“同步”这个问题大概率是你心头的一根刺。Obsidian 官方推出的 Sync 服务功能固然稳定强大但每月几十元的订阅费对于个人用户尤其是学生或笔记量不大的用户来说长期来看也是一笔不小的开销。更关键的是我们的笔记数据往往非常私密将它们完全托管在云端服务上心里总有些不踏实。于是寻找一个免费、安全且可控的同步方案就成了很多 Obsidian 玩家的刚需。Git这个程序员们再熟悉不过的版本控制工具自然就进入了视野。它天生就是为了管理文件变更而生的每一次修改都有记录可以轻松回滚到任意历史版本还能在不同设备间同步。但 Git 本身的使用门槛以及需要搭配 GitHub、Gitee 等代码托管平台对于非技术背景的用户来说配置过程显得有些晦涩难懂。而“Hermes Agent LLM Wiki”这个项目的出现恰好为这个痛点提供了一个优雅的解决方案。它本质上是一个智能的本地知识库助手能够理解你的笔记内容并进行智能问答和检索。但更重要的是它项目结构中倡导的“Git 同步”工作流为我们提供了一套现成的、经过验证的配置范式。我们不需要从零开始研究如何用 Git 同步 Obsidian 仓库而是可以直接参考甚至复用这个成熟项目的配置。所以这篇教程的核心目的就是手把手带你走通这条路利用 Git 和参考 Hermes Agent LLM Wiki 的实践为你的 Obsidian 笔记库搭建一个完全免费、自主可控的同步系统。无论你是在 Windows、macOS 还是 Linux 上无论你之前是否接触过 Git跟着步骤走都能搞定。2. 核心思路与方案选型Git 同步的底层逻辑在动手之前我们必须先理解这套方案的核心思路。这不仅仅是点几下鼠标更是理解一种更可靠的数据管理哲学。2.1 为什么是 Git而不是网盘同步很多人的第一反应可能是我用百度网盘、iCloud 或者 Dropbox 同步 Obsidian 的仓库文件夹不就行了吗确实可以但这存在几个显著问题冲突处理能力弱当你在手机和电脑上同时修改了同一篇笔记网盘通常只会机械地保留最后同步的那个版本或者生成一堆“冲突副本”你需要手动合并非常麻烦。而 Git 能清晰地告诉你哪里发生了冲突并提供了成熟的合并工具。版本历史缺失网盘虽然可能有“历史版本”功能但往往有期限、数量限制且回溯不够直观。Git 的每一次提交Commit都是一个完整的快照你可以随时查看任何时间点的笔记状态甚至可以轻松对比两个版本之间的具体差异。数据安全与隐私使用国内的 Git 服务如 Gitee或自建 Git 服务器数据完全在可控范围内。而某些网盘服务的隐私条款和数据存储位置可能让你有所顾虑。跨平台一致性Git 是标准工具在 Windows、macOS、Linux 上行为一致。而不同网盘客户端的同步策略和性能可能差异很大。Git 同步的本质是把你的 Obsidian 笔记库变成一个代码仓库。你在一台设备上“提交”修改然后“推送”到远程仓库如 Gitee在另一台设备上“拉取”远程的更新到本地。这个过程精准、可追溯。2.2 Hermes Agent LLM Wiki 项目给我们的启示Hermes Agent LLM Wiki 是一个典型的基于本地文档的智能问答项目。它的文档明确指出了使用 Git 进行版本管理和同步。我们从它的项目结构中能学到什么.gitignore文件这个文件定义了哪些文件不需要被 Git 跟踪。对于 Obsidian我们同样需要忽略缓存文件如.obsidian/workspace、临时文件以及某些插件生成的数据避免将无关内容同步上去也能提升同步速度。我们可以直接参考或复用它的忽略规则。清晰的提交约定一个好的 Git 使用习惯是每次提交都有清晰的信息。Hermes 项目的提交历史通常是“添加功能 X”、“修复问题 Y”、“更新文档 Z”。对于笔记同步我们也应该养成习惯比如“更新《读书笔记-深度工作》”、“整理日记 2023-11”、“添加新笔记模板”这样历史记录一目了然。分支策略的简化应用对于个人笔记我们可能不需要复杂的分支。但理解“主分支main/master”保存稳定版本偶尔可以开一个“草稿分支”来写一些不成熟的想法写完后合并回去这是一种非常清爽的内容管理方式。基于以上思路我们的方案选型就非常明确了以 Git 为核心同步工具以国内访问速度快的 Gitee码云作为免费远程仓库在 Obsidian 中通过命令行或图形化工具完成日常的提交与同步操作。整个方案的成本为 0且完全自主。3. 环境准备安装与配置 Git这是最基础也是最重要的一步。我们将以 Windows 平台为例macOS 和 Linux 用户也可以找到对应的安装方法核心配置命令是通用的。3.1 下载与安装 Git访问官网打开 Git 的官方网站找到下载页面。对于 Windows 用户直接下载 “Standalone Installer” 即可。运行安装程序双击下载好的.exe文件启动安装向导。关键安装选项选择组件保持默认确保 “Git Bash Here” 和 “Git GUI Here” 被选中这会在右键菜单添加快捷入口。选择默认编辑器推荐选择 “Use Visual Studio Code as Git‘s default editor”这样在需要输入提交信息时会用 VSCode 打开比内置的 Vim 友好得多。如果你没有安装 VSCode可以选择 Notepad 或其他你熟悉的编辑器。调整 PATH 环境选择“Git from the command line and also from 3rd-party software”。这是最关键的一步它会把 Git 添加到系统的 PATH 环境变量中让你可以在任何命令行窗口如 CMD、PowerShell中直接使用git命令。选择 HTTPS 传输后端选择 “Use the OpenSSL library”。配置行尾转换选择“Checkout Windows-style, commit Unix-style line endings”。这个选项能最好地处理 Windows 和 macOS/Linux 之间换行符的差异避免出现大量不必要的修改提示。选择终端模拟器选择 “Use MinTTY”这是 Git Bash 的默认终端体验更好。其他选项剩余选项如 “Enable file system caching”、 “Enable Git Credential Manager” 都保持默认推荐即可。注意行尾符配置是跨平台同步笔记时的一个经典坑。如果配置不当你可能会发现明明没改内容Git 却提示整个文件都被修改了。上述选择能最大程度避免这个问题。点击 “Install” 完成安装。3.2 初始全局配置安装完成后在开始菜单找到 “Git” - “Git Bash”打开一个黑底绿字的命令行窗口。我们需要进行一些基本的全局配置这些配置只需要做一次。# 配置你的用户名和邮箱这将会记录在你的每一次提交中 git config --global user.name 你的名字或昵称 git config --global user.email 你的邮箱地址 # 让 Git 命令输出带颜色更容易阅读 git config --global color.ui auto # 设置默认分支名为 main现代 Git 的推荐做法 git config --global init.defaultBranch main # 检查配置是否成功 git config --global --list请务必将上面的你的名字或昵称和你的邮箱地址替换成你自己的信息。这个邮箱最好与你后续注册 Gitee 或 GitHub 的邮箱一致。实操心得很多人会随便填一个邮箱这没问题。但如果你未来某天想将这个仓库公开或者参与开源项目这个身份信息就会变得重要。建议使用一个常用的、真实的邮箱。4. 创建远程仓库与本地初始化我们需要一个“云端保险箱”来存放笔记。这里选择 Gitee因为它在国内访问速度快且稳定。4.1 在 Gitee 上创建新仓库注册并登录 Gitee。点击页面右上角的 “” 号选择 “新建仓库”。填写仓库信息仓库名称例如my-obsidian-notes。起一个容易识别的名字。路径会自动填充一般和仓库名一致。介绍可选填写“我的 Obsidian 笔记同步仓库”。仓库类型选择“私有”。这是最重要的你的笔记很可能包含个人隐私务必设为私有。其他选项不勾选“使用 Readme 文件初始化这个仓库”。因为我们打算从一个已有的本地文件夹初始化。不勾选“选择模型”。保持空白。在 “.gitignore” 模板中可以选择Node.js或直接留空我们后面会自己配置更精确的。在 “开源许可证” 中选择 “不指定”。点击“创建”按钮。创建成功后你会看到一个空仓库的页面页面上会显示仓库的 HTTPS 地址格式如https://gitee.com/你的用户名/my-obsidian-notes.git。复制这个地址稍后会用到。4.2 初始化本地 Obsidian 仓库现在我们回到你的电脑对你现有的 Obsidian 笔记库Vault进行操作。如果你还没有笔记库先在 Obsidian 里创建一个。打开你的 Obsidian 笔记库所在的文件夹。你可以在 Obsidian 左下角点击“打开其他仓库”查看当前仓库的路径。在这个文件夹的空白处右键单击选择 “Git Bash Here”。这会直接打开一个 Git Bash 终端并且工作路径就在你的笔记库根目录。在 Git Bash 中依次执行以下命令# 1. 初始化本地 Git 仓库 git init # 2. 将本地仓库与远程的 Gitee 仓库关联起来 # 将下面的 URL 替换成你刚刚复制的 Gitee 仓库地址 git remote add origin https://gitee.com/你的用户名/my-obsidian-notes.git # 3. 创建并配置 .gitignore 文件 # 这个文件告诉 Git 哪些文件不需要跟踪。我们先创建一个基础版本。 echo -e .obsidian/workspace*\n.trash/\n*.tmp\n.DS_Store\nThumbs.db .gitignore让我们解释一下.gitignore文件里的内容.obsidian/workspace*忽略 Obsidian 的窗口布局、打开文件状态等缓存信息这些是纯本地偏好不需要同步。.trash/忽略 Obsidian 的回收站文件夹。*.tmp忽略所有临时文件。.DS_StoremacOS 系统生成的文件夹元数据文件。Thumbs.dbWindows 系统生成的缩略图缓存文件。注意事项.obsidian文件夹本身是需要同步的因为它里面包含了你的核心配置、插件、主题和自定义片段。我们只忽略其中的workspace等动态缓存文件。你可以用文本编辑器打开.gitignore文件根据实际情况增删规则。5. 核心同步流程实操环境搭好了仓库联通了接下来就是日常使用的核心操作。我们将模拟一个完整的“在电脑A上写笔记然后在电脑B上获取更新”的工作流。5.1 日常提交与推送在电脑A上操作假设你刚在电脑A上写完或修改了一些笔记。打开 Git Bash在你的 Obsidian 仓库根目录右键打开 “Git Bash Here”。检查状态首先用git status命令看看哪些文件被修改、新增或删除了。这会给你一个清晰的概览。git status你会看到红色的文件名表示这些是已修改但未暂存未准备提交的文件。添加变更到暂存区你可以添加所有变更也可以添加特定文件。# 添加所有变更最常用 git add . # 或者只添加特定文件 git add 日记/2023-11-01.md 读书笔记/深度工作.md执行git add .后再运行git status你会看到文件名变成了绿色表示它们已进入暂存区等待被提交。提交变更给这次提交写一个清晰的说明信息。git commit -m 更新完成《深度工作》读书笔记第三章新增11月日记模板-m后面的字符串就是提交信息。养成写清晰提交信息的习惯未来的你会感谢现在的自己。推送到远程仓库Giteegit push -u origin main第一次推送时需要使用-u参数它将本地main分支与远程origin仓库的main分支关联起来。以后再次推送只需要简单的git push即可。 这时Git Bash 会弹出一个窗口让你输入 Gitee 的用户名和密码或令牌。输入后你的本地提交就被上传到 Gitee 的私有仓库了。5.2 在另一台设备电脑B上克隆与拉取现在换到电脑B你想继续工作。安装并配置 Git重复第3部分的步骤在电脑B上安装 Git 并进行同样的全局配置用户名和邮箱。克隆远程仓库这不是打开一个现有文件夹而是“下载”整个仓库。在电脑B上找一个合适的位置比如D:\Notes或~/Documents。在此处打开 Git Bash。运行克隆命令URL 还是你那个仓库地址git clone https://gitee.com/你的用户名/my-obsidian-notes.git命令执行后会生成一个my-obsidian-notes文件夹里面就是你所有的笔记和.obsidian配置。用 Obsidian 打开这个仓库打开 Obsidian选择“打开文件夹为仓库”然后选择刚刚克隆下来的my-obsidian-notes文件夹。你会发现你的笔记、插件、主题甚至设置都一模一样地过来了日常拉取更新当你在电脑A上又推送了新的修改后在电脑B上只需要在仓库目录打开 Git Bash执行git pull这个命令会自动从 Gitee 拉取最新的变更并合并到你的本地。然后你在 Obsidian 里刷新一下就能看到最新的内容。5.3 处理冲突当两台电脑同时修改了同一行这是 Git 同步中最需要小心的情况但处理起来并不难。场景你在电脑A上修改了“购物清单.md”的第一行提交并推送了。与此同时你在电脑B上还没执行git pull也修改了同一文件的第一行然后尝试提交。会发生什么在电脑B上你先执行git pull想获取最新更新。Git 会告诉你CONFLICT (content): Merge conflict in 购物清单.md。用文本编辑器或 Obsidian 打开这个文件你会看到类似这样的标记 HEAD 电脑B上修改的内容 电脑A上修改的内容 commit-id-from-remote HEAD和之间是你本地电脑B的修改和之间是远程电脑A的修改。如何解决手动编辑文件打开冲突文件仔细看两处修改决定是保留其中一个还是将两者合并。删除 HEAD commit-id-from-remote这些标记行并整理成你最终想要的内容。# 例如合并后的内容 电脑A和电脑B修改合并后的新内容标记冲突已解决保存文件后回到 Git Bash。# 将解决冲突后的文件添加到暂存区 git add 购物清单.md # 完成合并提交 git commit -m “解决合并冲突购物清单.md”推送合并结果git push现在远程仓库就包含了合并后的正确版本。避坑技巧养成好习惯在开始写一篇笔记前尤其是可能在其他设备上打开过的笔记先执行一次git pull确保本地是最新版本可以极大减少冲突概率。6. 进阶配置与自动化基础流程跑通后我们可以追求更优雅、更自动化的体验。6.1 使用 SSH 密钥替代密码认证每次push都要输密码很麻烦配置 SSH 密钥可以实现免密操作也更安全。生成 SSH 密钥对在任意一台电脑上操作一次即可ssh-keygen -t ed25519 -C “你的邮箱地址”连续按回车接受默认保存路径和不设置密码或为了安全设置一个密码。查看并复制公钥cat ~/.ssh/id_ed25519.pub复制终端输出的全部内容从ssh-ed25519开始到邮箱结束。在 Gitee 上添加公钥登录 Gitee点击头像 - 设置 - SSH 公钥。标题栏随便填如 “My Laptop”。将复制的公钥粘贴到“公钥”栏。点击“确定”。测试连接ssh -T gitgitee.com如果看到 “Hi XXX! You‘ve successfully authenticated...” 的欢迎信息说明成功。修改远程仓库地址为 SSH 协议# 先查看当前的远程地址 git remote -v # 如果是 https 开头将其改为 ssh 地址 git remote set-url origin gitgitee.com:你的用户名/my-obsidian-notes.git之后再进行git push就不再需要输入密码了。6.2 在 Obsidian 中集成 Git 操作可选虽然命令行很强大但如果你希望在 Obsidian 界面内点点按钮就完成同步可以借助插件。安装 “Obsidian Git” 插件在 Obsidian 中打开“设置” - “社区插件” - “浏览”搜索 “Obsidian Git”。安装并启用它。基本配置启用插件后在设置中会出现 “Obsidian Git” 的选项。你可以设置自动拉取的间隔如每分钟、自动提交的间隔谨慎使用、提交信息模板等。左侧边栏会出现一个 Git 图标通常是分支形状点击它可以快速执行PullCommitPush等操作并查看文件状态。个人建议对于新手我强烈建议先熟练使用命令行一段时间。图形化插件虽然方便但一旦出现冲突等复杂情况命令行给你的控制力和清晰度是无可替代的。等你完全理解了流程再使用插件作为快捷操作辅助。6.3 优化 .gitignore 文件一个精准的.gitignore可以保持仓库清洁。以下是针对 Obsidian 的更完整示例# Obsidian 缓存和临时文件 .obsidian/workspace* .obsidian/workspaces.json .obsidian/graph.json .obsidian/trash/ .obsidian/core-plugins-migration.json # 操作系统生成的文件 .DS_Store .DS_Store? ._* .Spotlight-V100 .Trashes ehthumbs.db Thumbs.db desktop.ini # 编辑器或IDE生成的文件 *.swp *.swo *~ *.log # 特定插件可能生成的不需要同步的数据 # 例如 ‘Dataview’ 的缓存 .obsidian/plugins/dataview/data.json # 例如 ‘Templater’ 的脚本缓存 .obsidian/plugins/templater-obsidian/scripts/.cache/ # 你的笔记中可能包含的附件缓存目录如果附件是外链或动态生成 assets/.cache/你可以根据自己安装的插件查看其文档或观察其生成的文件将不需要同步的路径添加进来。7. 常见问题与故障排查实录即使按照教程一步步来也可能会遇到一些问题。这里记录了几个我亲自踩过的坑和解决方法。7.1 问题执行git push时提示 “Authentication failed”可能原因与解决密码错误HTTPS 方式下Gitee 的密码不是你网站的登录密码而是账户密码在设置-安全设置中查看或者你专门生成的私人令牌。更推荐使用私人令牌。去 Gitee 设置 - 安全设置 - 私人令牌生成一个具有“仓库”权限的令牌。在执行git push输入密码时粘贴这个令牌。认证信息缓存错误Windows 凭据管理器里可能存了旧的、错误的密码。打开“控制面板” - “用户账户” - “管理 Windows 凭据”。在“普通凭据”里找到git:https://gitee.com相关的条目将其删除。再次执行git push重新输入正确的密码或令牌。未使用 SSH如果配置了 SSH 但还在用 HTTPS 地址也会失败。确保git remote -v显示的地址是gitgitee.com:...开头。7.2 问题.obsidian文件夹下的插件没同步过去排查步骤检查.gitignore文件是否误将整个.obsidian目录忽略了。确保忽略的只是workspace*等特定子项。在 Git Bash 中进入仓库目录运行git status查看.obsidian/plugins/下的插件文件夹是否被显示为未跟踪红色??或已修改红色M状态。如果没有说明它们没有被 Git 感知。手动添加并提交git add .obsidian/plugins/ git commit -m “添加 Obsidian 插件” git push在另一台设备上git pull后需要重启 Obsidian或点击“重新加载应用程序”插件才会被加载。7.3 问题执行git pull后Obsidian 里看不到新文件原因与解决 Obsidian 的文件列表有时不会自动刷新。解决方法很简单点击 Obsidian 左侧文件列表上方的刷新按钮一个循环箭头图标。或者直接按CtrlR(CmdR on Mac) 重新加载整个应用。7.4 问题我想回退到某个旧版本这是 Git 最强大的功能之一。查看历史git log --oneline这会显示简洁的提交历史每行前面有一串唯一的提交 ID如a1b2c3d。回退到指定版本软回退仅移动HEAD指针不改变工作区文件。相当于“撤销提交但保留修改”。git reset --soft a1b2c3d混合回退默认移动HEAD指针并重置暂存区但不改变工作区文件。修改还在但需要重新git add。git reset a1b2c3d硬回退危险彻底回退到那个版本丢弃之后的所有修改。除非你100%确定否则不要用。git reset --hard a1b2c3d如果已经推送了错误的版本在本地回退后强制推送到远程会覆盖远程历史谨慎操作确保只有你一个人在用这个仓库。git push -f origin main7.5 问题仓库越来越大同步变慢优化方法检查大文件使用工具查找仓库中的大文件。git rev-list --objects --all | git cat-file --batch-check%(objecttype) %(objectname) %(objectsize) %(rest) | grep blob | sort -k3 -n | tail -10这个命令会列出最大的10个文件。看看是否有不应该被跟踪的大文件比如视频、压缩包。从历史中移除大文件高级操作如果错误提交了大文件可以使用git filter-branch或BFG Repo-Cleaner工具将其从历史中彻底删除。但这会改变所有提交ID如果其他设备已经克隆了仓库会比较麻烦。操作前务必备份整个仓库。常规维护Git 会自动进行垃圾回收你也可以手动触发git gc --aggressive --prunenow这套基于 Git 的 Obsidian 同步方案我从两年前开始使用至今稳定可靠。它不仅仅是一个同步工具更让我养成了对知识资产进行版本管理的好习惯。每一次清晰的提交信息都是一次对知识脉络的梳理。当你可以随时回到三个月前某个灵光一现的笔记版本时那种安全感是任何付费云服务都无法完全给予的。