🛣️ dsh-GitRoad

Obsidian 笔记和 GitHub 的免费自动同步：不买官方云、不花一分钱，照着 9 步做完就完事

这是给谁的

Obsidian 用户，笔记不想只待在一台电脑上，又不想买 Obsidian 官方 Sync（一年几百块）。

这条路是我踩完坑之后留给普通人的：GitHub 私有仓库 + 免费社区插件，写完自动同步，多设备自动拉取，一分钱不花。 全程 30-40 分钟，命令行只用 10 条以内，其余都是点按钮。

它和官方 Sync 的区别

维度	Obsidian 官方 Sync	这条免费路
花钱	约 ¥80+/年	0 元
安装	开箱即用	一次性配置 30-40 分钟
同步原理	官方云服务器	GitHub 私有仓库 + Git
数据归谁	Obsidian 公司	你自己（GitHub 仓库）
适合谁	完全不想折腾的人	愿意照着步骤点一次的人

里面有什么

• SKILL.md —— 完整安装指南：从建仓库到自动同步，9 步全流程，含验证清单和 12 条坑的排查表
• files/gen-ssh-key.sh —— 一键生成无密码 SSH key 的脚本（绕开 Windows PowerShell 的一个大坑，详见下文）

怎么把技能装进 DSH

# 1. 获取仓库（国内直连 HTTPS 常被墙，推荐 git+ssh 走 SSH over 443，或网页下载 zip）
git clone git@github.com:iTrimut/dsh-GitRoad.git

# 2. 拷到 DSH 技能目录（$DSH_HOME 默认 ~/.dsh，可被 DSH_HOME 覆盖）
#    注意：SKILL.md 和 files/ 要一起拷（技能第 5 步依赖 files/gen-ssh-key.sh）
mkdir -p "$HOME/.dsh/skills/dsh-gitroad"
cp dsh-GitRoad/SKILL.md dsh-GitRoad/files "$HOME/.dsh/skills/dsh-gitroad/" -r

# 3. 重启 dsh web 后，对 DSH 说"帮我同步 Obsidian 笔记"即会加载本技能

技能目录名必须与 SKILL.md 的 name 字段一致（dsh-gitroad，全小写），否则会被 DSH 忽略。

快速开始（9 步地图）

1. 建 GitHub 私有仓库（2 分钟）—— 网页点几下，别勾任何初始化选项
2. 初始化 Vault 为 git 仓库（3 分钟）—— 三条命令
3. 装 Obsidian Git 插件（3 分钟）—— 设置里搜 Obsidian Git（作者 vinzent）
4. 配置自动备份（5 分钟）—— 注意设置页是分页的，自动备份/拉取在单独页面
5. 生成 SSH key（3 分钟）—— 跑一下 gen-ssh-key.sh，别手敲命令
6. 公钥贴到 GitHub（2 分钟）—— Settings → SSH keys
7. 配 SSH over 443（5 分钟）—— 绕开 22 端口被墙，一劳永逸
8. 推送（3 分钟）—— 两条命令，完成
9. 可选：关联 GitHub Desktop 看提交历史

完整命令和 GUI 步骤全在 SKILL.md，照着点就行。

为什么会有这个仓库

我自己配 Obsidian 同步的时候，把坑踩了个遍：

• 22 端口被墙、hosts 被本地代理劫持，SSH 怎么都连不上
• Windows 的 PowerShell 会把 ssh-keygen -N "" 的空参数吞掉，生成一把带密码的私钥，认证永远失败还找不到原因
• Git 全局配置里藏着 insteadOf 规则，把 SSH 地址悄悄改写成 HTTPS
• GitHub Desktop 关联到了错误的副本路径，界面却毫无提示

每踩一个就记一个，最后整理成这份给普通人的指南。文末有 12 条坑的排查表：现象 → 原因 → 一句话解法，遇到问题先查表。

边界（说清楚）

• 主要验证环境是 Windows；脚本是 bash 的，macOS / Linux 可以直接用
• 同步不是秒传：插件默认 10 分钟一次（设置里可改到 1 分钟）
• 同一时间别在两台设备改同一个文件，会冲突；Git 会在文件里留 <<<<<<< 标记，手动处理即可
• GitHub 仓库务必保持 Private，笔记是隐私

关于

这套东西是给"想同步、又不想折腾和花钱"的 Obsidian 用户准备的，坑都是我实际踩过的。有想法、踩了新坑，欢迎 Issues 里说一声。

---

MIT License · 自由使用 / 修改 / 再分发

Made by @iTrimut