你是否曾想过除了将代码托管在 GitHub、Gitee 这些中心化平台我们是否还能拥有一个完全由自己掌控、无需网络、甚至能实现多人实时协作的“个人代码仓库”这听起来像是一个矛盾的组合既要像 Git 一样管理版本历史又要像在线文档一样支持实时协同。今天我们将探讨一个融合了Git的版本控制思想、CRDT的无冲突协同技术以及Markdown的轻量级文档格式的构想——“My Own GitHub”。这不是一个具体的软件而是一种架构思路和技术选型方案。它旨在解决个人或小团队在知识管理、代码片段归档、文档写作时面临的几个核心痛点数据自主性、离线可用性以及轻量级的实时协作能力。本文将为你详细拆解如何利用现有的成熟技术栈构建一个属于你自己的、去中心化的文档与代码协同工作流。我们将从核心概念讲起逐步深入到环境搭建、工具链配置并通过一个完整的示例项目展示如何将 Git 仓库变成一个支持 Markdown 实时编辑与合并的“个人知识库”。无论你是独立开发者、技术写作者还是小型开源团队的维护者这篇文章都将为你提供一套可落地的实践方案。1. 核心问题我们为什么需要“自己的GitHub”在深入技术细节之前我们首先要回答现有的工具链Git GitHub已经如此强大为什么还要折腾原因在于控制权与工作流的错配。Git 本身是分布式的但我们的协作平台如 GitHub是中心化的。这带来了几个具体问题网络依赖与延迟每次git push/pull都需要网络在弱网环境下体验不佳。对于纯文档写作频繁的提交、推送、拉取流程显得笨重。协作实时性差Git 的协作模型是“提交-合并-解决冲突”这对于代码很合适但对于正在共同起草一份设计文档或会议纪要就显得过于“异步”和“沉重”。数据不在本地虽然代码在本地但 Issues、Wiki、项目文档如果用 GitHub Pages等内容其“权威数据源”在云端。平台服务变化或网络中断会影响访问。过度设计对于个人笔记或小范围共享的文档搭建一整套 Git 服务器如 Gitea或使用重量级的协同工具如 Google Docs可能杀鸡用牛刀。“My Own GitHub”构想的目标就是取三者之长Git提供强大的版本历史、分支管理和数据备份能力。CRDT提供无冲突的实时合并体验让你和你的伙伴可以同时编辑同一份 Markdown 文档而无需担心“锁”或复杂的冲突解决。Markdown作为通用、纯文本的内容载体既便于人类阅读写作也便于被 Git 追踪和 CRDT 算法处理。最终我们希望实现的效果是在本地文件夹里用任何编辑器写 Markdown更改能自动被记录类 Git并能与同事的更改无缝实时合并类 CRDT同时所有历史可追溯。2. 基础概念Git, CRDT, Markdown 如何协同工作要理解这个方案需要先厘清三个核心技术的角色。2.1 Git版本历史的“时光机”Git 是一个分布式版本控制系统。它的核心价值在于为文件尤其是文本文件创建可回溯的快照历史。在本方案中的作用作为底层的数据存储和版本回溯引擎。CRDT 处理实时同步而 Git 负责为每一次重要的同步节点或手动保存点打上“标签”允许我们随时回到历史上的任何一个版本。关键概念仓库 (Repository)、提交 (Commit)、分支 (Branch)、合并 (Merge)。在本方案中我们可能会弱化“分支”的复杂用法更侧重于线性历史与合并。2.2 CRDT无冲突合并的“魔法”CRDT 是“无冲突复制数据类型”的缩写。它是一种数据结构其设计保证了在网络延迟、任意顺序接收更新的情况下所有副本最终都能收敛到一致的状态且无需解决冲突。在本方案中的作用处理实时协作。当两个用户同时编辑一个 Markdown 文档时CRDT 算法通常是针对文本的如 Automerge、Yjs 使用的算法能自动、正确地合并他们的修改即使他们修改了同一行。与 Git Merge 的区别Git Merge 可能产生冲突需要人工解决。CRDT 从数据结构层面避免了冲突的产生实现了“自动合并”。你可以把它想象成一个永远自动解决冲突的、更智能的git merge。2.3 Markdown理想的内容“容器”Markdown 是一种轻量级标记语言用简单的语法如#、-、**) 定义格式最终可转换为 HTML 等格式。在本方案中的作用协作内容的载体。选择 Markdown 是因为纯文本这是最关键的一点。Git 和 CRDT 都能高效处理纯文本的差异比较与合并。通用性几乎所有编辑器和平台都支持。结构清晰标题、列表、代码块等结构便于组织和阅读。专注内容让作者专注于写作本身而非排版。三者关系图[用户A编辑Markdown] --CRDT实时同步-- [用户B编辑Markdown] | | v v [CRDT状态同步] [CRDT状态同步] | | v v [本地Git仓库] -------Git Pull/Push------ [本地Git仓库] | | (定期提交) (定期提交) | | v v [版本历史] [版本历史]简单来说CRDT 负责“实时同步当前状态”Git 负责“持久化历史状态”。Markdown 则是被同步和持久化的内容。3. 环境准备构建技术栈我们不会从头发明 CRDT 算法或写一个 Git。我们将选择成熟的开源库和工具进行集成。3.1 核心运行时与库Node.js ( 16)作为主要的 JavaScript 运行时环境许多优秀的 CRDT 库基于它。Git确保系统已安装 Git并完成基本的用户配置 (git config --global user.name/email)。3.2 关键 CRDT 库选型我们将选用automerge库作为 CRDT 实现。它是一个高性能、纯 JavaScript 实现的 CRDT 库特别适合文本和结构化数据的协同。另一个流行选择是yjs它功能更强大、生态更丰富如直接集成到编辑器但automerge的 API 对初学者更直观且与我们的“类 Git”模型更契合。安装命令# 在你的项目目录中初始化并安装 automerge mkdir my-own-github cd my-own-github npm init -y npm install automerge3.3 编辑器与工具VS Code推荐使用的编辑器。我们将利用其强大的扩展生态。VS Code 插件Markdown All in One提供 Markdown 写作的快捷键、目录生成等功能。Markdown Preview Enhanced提供实时预览。可选GitLens增强 Git 功能便于查看历史。3.4 项目结构初始化创建基本的项目结构和 Git 仓库# 初始化 Git 仓库 git init # 创建项目结构 mkdir docs mkdir scripts touch .gitignore touch README.md # 在 .gitignore 中忽略 node_modules echo node_modules .gitignore echo .DS_Store .gitignore # 进行首次提交 git add . git commit -m 初始提交项目结构4. 核心流程拆解从编辑到同步的闭环我们的目标是实现以下工作流本地编辑用户在 VS Code 中打开一个 Markdown 文件进行编辑。实时同步编辑动作通过 CRDT 库Automerge实时转换为操作并可以通过某种通道如 WebSocket、本地文件轮询发送给其他协作者。自动合并其他协作者端的 Automerge 库接收到操作后自动合并到本地文档副本中实现实时更新。历史快照每隔一段时间或当用户点击“保存版本”时将当前 CRDT 文档的状态序列化为文本提交到 Git 仓库生成一个版本历史。冲突解决由于使用 CRDT步骤2和3中不会产生需要人工解决的文本冲突。但可能存在“意图冲突”例如两人同时重写了同一段话这需要通过版本历史回溯和沟通来解决而不是解决 HEAD标记。5. 完整示例构建一个简单的协同 Markdown 编辑器我们将构建一个极简的、基于 Node.js 的命令行演示程序来模拟双人协同编辑一个 Markdown 文件并同步到 Git 的过程。5.1 项目结构my-own-github/ ├── package.json ├── .gitignore ├── README.md ├── docs/ │ └── example.md # 我们要协同编辑的Markdown文件 ├── scripts/ │ ├── editor.js # 模拟编辑器应用CRDT更改 │ ├── syncServer.js # 模拟同步服务器极简版 │ └── snapshotToGit.js # 将当前状态快照并提交到Git └── node_modules/5.2 初始化 CRDT 文档 (scripts/initDoc.js)首先创建一个脚本来初始化一个受 Automerge 管理的 Markdown 文档。// scripts/initDoc.js const Automerge require(automerge) const fs require(fs).promises const path require(path) const DOCS_PATH path.join(__dirname, .., docs, example.md) async function initDoc() { let initialText # 协同设计文档 这是一个通过 CRDT 和 Git 协同维护的文档。 ## 目标 * 实现去中心化实时协作 * 保留完整的版本历史 * 使用 Markdown 格式 --- 文档初始化于: ${new Date().toISOString()} // 1. 创建 Automerge 文档并初始化文本 let doc Automerge.init() doc Automerge.change(doc, 初始化文档, (d) { if (!d.content) d.content Automerge.Text.from() // Automerge.Text 是一个 CRDT 文本类型 d.content.insertAt(0, ...initialText.split()) }) // 2. 将 Automerge 二进制状态保存到文件用于后续加载 const binary Automerge.save(doc) await fs.writeFile(DOCS_PATH .automerge, binary) // 3. 也将当前文本内容写入普通的 .md 文件便于查看和编辑 await fs.writeFile(DOCS_PATH, initialText) console.log(文档已初始化并保存至: ${DOCS_PATH}) console.log(Automerge 状态保存至: ${DOCS_PATH}.automerge) } if (require.main module) { initDoc().catch(console.error) } module.exports { initDoc }运行node scripts/initDoc.js后你会看到docs/example.md纯文本和docs/example.md.automergeAutomerge 二进制状态两个文件。5.3 模拟编辑与本地合并 (scripts/editor.js)这个脚本模拟一个用户对文档进行编辑。在真实场景中这部分逻辑会嵌入到你的编辑器中。// scripts/editor.js const Automerge require(automerge) const fs require(fs).promises const path require(path) const DOCS_PATH path.join(__dirname, .., docs, example.md) const AUTOMERGE_PATH DOCS_PATH .automerge async function simulateEdit(userName, changes) { // 1. 加载现有的 Automerge 文档 const binary await fs.readFile(AUTOMERGE_PATH) let doc Automerge.load(binary) // 2. 应用更改 // changes 是一个数组格式如 {type: insert, pos: 10, text: 新内容} 或 {type: delete, pos: 5, length: 2} doc Automerge.change(doc, ${userName} 的编辑, (d) { changes.forEach(change { if (change.type insert) { d.content.insertAt(change.pos, ...change.text.split()) } else if (change.type delete) { d.content.deleteAt(change.pos, change.length) } }) }) // 3. 保存更新后的状态 const newBinary Automerge.save(doc) await fs.writeFile(AUTOMERGE_PATH, newBinary) // 4. 同时更新纯文本 .md 文件方便查看 const currentText doc.content.toString() await fs.writeFile(DOCS_PATH, currentText) console.log([${userName}] 编辑已应用。当前文档片段, currentText.substring(0, 100) ...) return newBinary // 返回新的二进制状态可用于“同步” } // 模拟两个并发编辑 async function main() { console.log(--- 模拟用户 Alice 和 Bob 的编辑 ---) // 假设 Alice 先启动在文档末尾添加一行 const aliceChanges [ { type: insert, pos: 200, text: \n\n**Alice**: 我建议我们采用 WebSocket 进行实时同步。 } ] const aliceState await simulateEdit(Alice, aliceChanges) // 模拟 Bob 在 Alice 保存前基于旧版本也做了编辑位置可能重叠 // 注意为了模拟并发我们需要重新加载编辑前的状态 const oldBinary await fs.readFile(AUTOMERGE_PATH) // 重新读取实际上应该读旧备份 let bobDoc Automerge.load(oldBinary) // Bob 在另一个位置插入 const bobChanges [ { type: insert, pos: 150, text: \n**Bob**: 前端框架可以考虑用 Vue 3。 } ] bobDoc Automerge.change(bobDoc, Bob 的编辑, (d) { bobChanges.forEach(c { if (c.type insert) { d.content.insertAt(c.pos, ...c.text.split()) } }) }) // 关键步骤合并 Alice 和 Bob 的更改 console.log(\n--- 开始合并 Alice 和 Bob 的更改 ---) const mergedDoc Automerge.merge(bobDoc, Automerge.load(aliceState)) // 保存合并后的状态 await fs.writeFile(AUTOMERGE_PATH, Automerge.save(mergedDoc)) const finalText mergedDoc.content.toString() await fs.writeFile(DOCS_PATH, finalText) console.log(合并成功最终文档内容) console.log(---) console.log(finalText) console.log(---) console.log(注意Alice和Bob的编辑被自动合并没有冲突。) } if (require.main module) { main().catch(console.error) } module.exports { simulateEdit }运行node scripts/editor.js。你会看到尽管模拟了并发编辑但最终文档合并了 Alice 和 Bob 的内容而没有产生 Git 中那种冲突标记。这就是 CRDT 的威力。5.4 创建 Git 快照 (scripts/snapshotToGit.js)这个脚本负责将当前 CRDT 文档的状态作为一个“版本”提交到 Git。我们可以在每次协同会话结束后或者定期执行它。// scripts/snapshotToGit.js const { exec } require(child_process) const util require(util) const fs require(fs).promises const path require(path) const execPromise util.promisify(exec) const DOCS_PATH path.join(__dirname, .., docs, example.md) async function createGitSnapshot() { const timestamp new Date().toISOString() const commitMessage docs: 自动快照 ${timestamp} try { // 1. 确保我们拿到了最新的纯文本内容editor.js 已更新 // 2. 添加到 Git 暂存区 await execPromise(git add ${DOCS_PATH}) // 3. 提交到本地仓库 const { stdout, stderr } await execPromise(git commit -m ${commitMessage}) console.log(Git 提交成功: ${commitMessage}) if (stdout) console.log(stdout) // 4. 可选获取提交哈希用于引用 const { stdout: hashStdout } await execPromise(git rev-parse --short HEAD) const commitHash hashStdout.trim() console.log(本次提交哈希: ${commitHash}) // 5. 将 Automerge 的二进制状态文件也作为数据存档可选但建议 const automergePath DOCS_PATH .automerge const backupDir path.join(__dirname, .., .automerge_backup) await fs.mkdir(backupDir, { recursive: true }) await fs.copyFile(automergePath, path.join(backupDir, ${commitHash}.automerge)) console.log(Automerge 状态已备份至: ${backupDir}/${commitHash}.automerge) } catch (error) { // 如果没有任何更改git commit 会失败这是正常的 if (error.stderr error.stderr.includes(nothing to commit)) { console.log(没有检测到文档更改跳过提交。) } else { console.error(创建 Git 快照时出错:, error) } } } if (require.main module) { createGitSnapshot().catch(console.error) } module.exports { createGitSnapshot }运行node scripts/snapshotToGit.js。如果example.md有更改它会被提交到 Git 仓库并且 Automerge 的二进制状态文件也会被备份。这相当于为我们的实时协作状态创建了一个“存档点”。6. 运行结果与效果验证6.1 验证协同编辑运行node scripts/initDoc.js初始化文档。运行node scripts/editor.js模拟协同编辑。打开docs/example.md文件你将看到类似以下内容# 协同设计文档 这是一个通过 CRDT 和 Git 协同维护的文档。 ## 目标 * 实现去中心化实时协作 * 保留完整的版本历史 * 使用 Markdown 格式 **Bob**: 前端框架可以考虑用 Vue 3。 --- 文档初始化于: 2023-10-27T08:00:00.000Z **Alice**: 我建议我们采用 WebSocket 进行实时同步。关键验证点Bob 和 Alice 的评论被插入到了文档的不同位置且合并过程没有人工干预。如果这是在 Git 中直接合并两个分支的文本文件很可能会产生冲突。6.2 验证版本历史运行node scripts/snapshotToGit.js创建第一个版本。再次修改docs/example.md或通过 editor.js 模拟然后再次运行snapshotToGit.js。使用 Git 命令查看历史cd /path/to/my-own-github git log --oneline -- docs/example.md你应该能看到类似以下的输出a1b2c3d (HEAD - main) docs: 自动快照 2023-10-27T08:05:00.000Z e4f5g6h docs: 自动快照 2023-10-27T08:00:00.000Z 7890abc 初始提交项目结构这证明了所有编辑历史都被 Git 完整地记录了下来。你可以使用git diff commit-hash-1 commit-hash-2来查看任意两个版本之间的差异。6.3 验证状态恢复假设你想回到第一个快照时的状态。首先用 Git 恢复文本文件git checkout e4f5g6h -- docs/example.md然后从备份中恢复对应的 Automerge 状态文件cp .automerge_backup/e4f5g6h.automerge docs/example.md.automerge现在你的 CRDT 文档状态和文本内容都回滚到了那个时间点。你可以继续基于这个历史状态进行新的编辑。7. 常见问题与排查思路问题现象可能原因排查方式解决方案运行editor.js时报Automerge.load错误docs/example.md.automerge文件不存在或损坏。检查文件是否存在并尝试用initDoc.js重新初始化。运行node scripts/initDoc.js重新创建初始文档和状态文件。协同编辑后example.md文件内容混乱或重复editor.js中的编辑位置 (pos) 计算有误或者合并逻辑错误。仔细检查simulateEdit函数中pos参数是否基于正确的文档长度。在真实编辑器中位置应由编辑器本身提供。在真实应用中应使用编辑器集成如 CodeMirror、ProseMirror 的 Automerge 适配器它们能正确处理位置索引。snapshotToGit.js总是提示“nothing to commit”1. 文档内容确实未变。2. 文件未被 Git 跟踪。3. 文件已在.gitignore中。1. 检查docs/example.md内容。2. 运行git status查看文件状态。3. 检查.gitignore文件。确保文件已通过git add加入跟踪且不在忽略列表中。脚本中已包含git add。多人实时同步无法工作示例中只有本地模拟合并没有真正的网络同步层。本示例仅演示核心合并逻辑未实现网络传输。需要实现一个同步层。可考虑1.WebSocket 服务器用于实时广播更改。2.使用y-websocket如果换用 Yjs 库其生态提供开箱即用的 WebSocket 服务端和客户端。3.对等网络使用 WebRTC 实现点对点同步。Automerge 二进制文件 (*.automerge) 体积增长很快Automerge 默认保存完整历史以支持时间旅行等功能。查看文件大小。1. 定期清理旧历史Automerge.emptyChange相关操作需谨慎。2. 或换用yjs它有不同的状态管理策略。3. 对于纯版本历史依赖 Git 即可可配置 Automerge 不保存过多历史。合并结果不符合预期如段落顺序错乱CRDT 算法如 Automerge 的文本算法在处理某些并发插入时其最终顺序可能由内部ID决定而非绝对位置。理解 CRDT 的“最终一致性”与“意图一致性”的区别。它保证内容不丢失且副本一致但顺序可能不是用户直觉顺序。1. 对于强顺序要求的场景可能需要更复杂的数据结构如列表CRDT。2. 通过 UI/UX 设计来缓解例如在高冲突可能区域提供视觉提示。8. 最佳实践与工程建议将“Git CRDT Markdown”的思路产品化需要考虑更多工程细节。8.1 架构选择轻量级个人使用可以直接使用Obsidian社区插件如obsidian-sync-share的某些版本或VS Code Live Share它们部分实现了类似思想。核心是找到支持 Git 版本历史和某种实时同步的 Markdown 编辑器。小团队协作可以考虑yjsy-websocketProseMirror的技术栈。Yjs 生态更成熟有现成的服务端 (y-websocket) 和富文本编辑器集成方案。后端用 Git 钩子如post-receive在每次同步后自动提交快照。自建服务使用上述技术栈搭建一个私有服务。将 Yjs 的同步服务器、Git 仓库管理和一个简单的 Web 前端集成 Markdown 编辑器部署在内网或私有云上。8.2 数据安全与备份Git 作为唯一信源确保所有最终状态都定期、可靠地提交到 Git。可以将 Git 仓库推送到一个私有远程服务器如自建的 Gitea作为备份。加密敏感数据如果文档包含敏感信息应在客户端进行加密后再通过 CRDT 同步或确保同步通道如 WebSocket使用 TLS。状态恢复点除了 Git 提交定期导出 CRDT 文档的完整状态并进行备份。8.3 性能优化差分同步CRDT 库如 Automerge, Yjs本身会生成高效的二进制差分数据。确保网络传输的是这些差分数据而非整个文档状态。历史清理如前述对于长生命周期的文档注意清理 CRDT 内部的历史状态防止内存和存储膨胀。大文档处理对于非常大的 Markdown 文档考虑将其拆分为多个小文档基于章节每个文档用一个独立的 CRDT 实例管理。8.4 集成到现有工作流CI/CD 集成可以利用 Git 钩子在每次快照提交后自动触发 CI 流程例如将 Markdown 构建成静态网站用 MkDocs, Docusaurus、进行拼写检查或链接验证。编辑器强化在 VS Code 中可以开发一个扩展将 CRDT 同步逻辑和 Git 快照功能集成到侧边栏或状态栏提供一键保存版本、查看协作者光标位置等功能。9. 总结与后续方向通过本文的探讨和示例我们验证了将Git、CRDT 和 Markdown三者结合构建一个去中心化、支持实时协作、且拥有完整版本历史的“个人知识库”或“团队文档库”在技术上是完全可行的。核心收获Git 负责“历史”它提供了坚如磐石的版本回溯能力是数据的最终备份和审计依据。CRDT 负责“现在”它解决了实时协作中最令人头疼的冲突问题让协同写作像编辑本地文件一样流畅。Markdown 负责“内容”其纯文本特性是连接前两者的完美桥梁。这不仅仅是一个技术演示更是一种工作流理念的转变从依赖中心化 SaaS 服务转向构建由开源工具组合而成、数据自主可控的个性化协作环境。你可以立即尝试的下一步深入一个库仔细阅读automerge或yjs的官方文档理解其 API 和设计哲学。尝试现有产品体验一下LiveShare、Obsidian的同步社区插件感受实时协作 Markdown 的体验。改造你的笔记流程为你现有的本地 Markdown 笔记文件夹可能用 Typora、VS Code 编辑加上一个自动化的 Git 提交钩子实现每5分钟或每次保存自动提交先获得“版本历史”的好处。构建最小原型基于本文的y-websocket建议搭建一个最简单的网页让你和同事能同时编辑一段文本并看到实时更新。技术的最终目的是服务于人。在这个数据所有权日益受到重视的时代掌握一套将强大开源工具组合起来、打造符合自己需求的工作流的能力或许比单纯使用某个流行产品更为重要。希望“My Own GitHub”这个构想能为你开启一扇新的门。
