企业官网建设流程全解析

“笔记越攒越多，真正用到的时候却翻不出来”——这句话我听了太多次，也踩了太多坑。我从 2019 年开始用 Obsidian 管理个人知识库，刚开始图它本地存储、Markdown 写起来舒服，后来笔记量一上来，检索和整理就成了大问题。直到我把 AI 能力接进来，用 Obsidian + WorkBuddy + Gitee 这套组合重新搭了一遍，才体会到“知识库”和“文件堆”的差别。

这套组合的定位很清晰：Obsidian 负责本地化存储和双链笔记，Gitee 负责 Git 版本管理与私有仓库同步，WorkBuddy 这类 AI 工作台负责把静态笔记变成可问答、可归纳、可复用的知识资产。适合那些不想把笔记锁在某个封闭平台、又想用 AI 盘活存量笔记的人。下面我把思路、配置和踩坑过程完整写出来。

1. 为什么是这三件套：先拆解这套组合的逻辑

1.1 Obsidian：本地优先的 Markdown 底座

Obsidian 的核心优势不在于界面上的图谱动画，而在于它的数据形态。你的所有笔记就是一个普通文件夹里的一堆.md文件，加上少量配置文件。这意味着没有厂商锁定，文本内容永远能被其他工具读取，也意味着 Git 可以直接对这个文件夹做版本管理。这一点是整个组合的根基：如果笔记是纯文本，那后面接 Git、接 AI 工具都会顺畅得多。

我见过不少朋友一上来就被 Obsidian 的双链和图谱吸引，疯狂装插件，结果库结构一团乱。真实长期可用的库，一般只需要核心的 daily notes、模板、大纲、关系图谱和少数几个必要插件。知识管理这件事，稳定大于功能堆砌，文件结构一旦乱掉，后面无论是 Git 同步还是 AI 索引，都会跟着出问题。

还有一个容易忽略的点：Obsidian 的库是“文件夹即库”，一个库占用一个根文件夹，库里可以再建子文件夹。这决定了我们后面给 Gitee 建仓库时，直接把库根目录当作 Git 仓库根目录即可，天然是一一对应的关系。这也是这套组合能成立的前提之一——存和同步的对象始终是同一个文件夹，不存在格式转换或路径漂移。

1.2 Gitee：版本管理而非简单同步

很多人把“同步”和“版本管理”混为一谈。网盘同步解决的是“文件在多设备间保持一致”，但它不解决“改错了想回滚”“两台设备同时改了怎么办”的问题。Git 的思路不一样：每次修改都被记录为一个提交，你可以随时查看历史、对比差异、回退到任意版本。对文字类知识资产来说，这个能力非常关键。写过书、维护过文档项目的人应该深有体会，一个“撤销到三天前”的按钮，比任何自动备份都让人安心。

为什么选 Gitee 而不是其他 Git 托管平台？对我这种网络环境不稳定的情况来说，Gitee 的国内访问速度确实体验更好，私有仓库免费，个人笔记规模完全够用。同时 Gitee 对 SSH 密钥、仓库管理这类常规 Git 操作支持得很完整。你也可以换成 GitHub、GitLab 或自建 Gitea，整体思路不变。这里想强调：不要把工具神化，Gitee 在本方案里的角色就是一个“远程存储 + 历史版本”的托管端。

需要提醒的是，Gitee 的免费仓库有容量限制，单文件大小也有上限。好在笔记主体是纯文本，几百 KB 已经是很大的文档了，真正要小心的是插图、PDF、视频这类大文件。我的策略是：库里面只放压缩过的图，大附件一律不进 Git 仓库。后面我会专门写一节怎么处理附件，这里先立下这条铁律。

1.3 WorkBuddy：给知识库接上 AI 大脑

有了存和同步，知识库还缺最后一环：用起来。我当前在用的 WorkBuddy 版本，核心能力就是把一个本地文件夹当作知识源接入工作台，然后通过对话方式对这个知识库提问。举个例子，以前我想查“之前看到过的 Docker 多阶段构建那段笔记”，得在几十个 md 文件里翻；现在直接在 WorkBuddy 里问一句，它定位到文件并给出上下文，效率完全不同。

WorkBuddy 还支持 Skill 技能机制，可以把你常用的整理动作固化成技能，比如“把本周新增笔记按领域归类”“检查所有笔记中过期链接”“对某个主题生成一份综述”。这些技能本质上是一段结构化的指令，数据源指向 Obsidian 的库目录，运行完直接给出结构化输出。听起来复杂，实际配置起来就几步，后面我会放一个我自己在用的示例。

这套组合的核心逻辑是“各管一段”：Obsidian 管文件的存放与组织，Gitee 管文件的历史与异地副本，WorkBuddy 管文件的理解与再加工。三者互不冲突，又互为补充。想清楚这个分工之后，很多具体配置就不需要照搬别人的模板，你完全能根据自己习惯组合出合适的节奏。

2. 动手前的准备：目录结构、仓库与密钥这些细节

2.1 先用一套目录结构把“家底”理顺

我强烈建议在建仓库之前先想清楚目录结构，因为笔记量大了再迁移非常痛苦。我用的是一套简化版 PARA：

这套结构的好处是边界清晰，任何新笔记都能在 30 秒内找到归属。每天随手记的东西先进 Inbox，每周整理一次，决定是放进项目、领域还是归档。别看结构简单，它直接影响两个环节：Obsidian 图谱的聚类效果，以及 WorkBuddy 对“某项内容属于哪个主题”的判断准确度。

除了顶层目录，还要立几条命名规矩：文件名尽量用短横线分隔的英文，或者确保中文文件名不含有/ : * ? " < > |这类特殊字符；日期统一用 YYYY-MM-DD；同一个主题的笔记在文件名上保持统一前缀，这样 AI 工具在索引时更容易识别聚类。别小看这些细节，WorkBuddy 的检索精度和文件命名规范高度正相关。

目录结构定下来后，我会顺手在每个顶层目录下建一个_index.md作为入口索引，写上“这个目录里有什么、怎么用”。这不仅是给人看的，也是给 AI 看的。WorkBuddy 在问答时会优先命中这种索引文件，输出质量明显更高。这一步的成本极低，收益却很持久。

2.2 创建 Gitee 私有仓库并配置 SSH 密钥

Gitee 仓库创建没什么难度，登录后在右上角点“新建仓库”，填写仓库名，比如my-knowledge-base，可见性选择“私有”，不要勾选“使用 README 初始化仓库”（勾了也行，但会多一个需要处理的初始提交）。创建完成后，复制 SSH 形式的仓库地址，形如git@gitee.com:用户名/仓库名.git。

SSH 密钥配置是新手最容易卡住的地方。打开终端，先看自己的用户目录下有没有~/.ssh/id_ed25519或id_rsa，没有就执行：

ssh-keygen -t ed25519 -C "你的邮箱@example.com"

一路回车即可，不用设 passphrase（设了的话每次 push 都要输密码，个人本地用没必要）。然后把id_ed25519.pub的内容复制，粘贴到 Gitee 的“设置 → SSH 公钥”里。验证是否成功：

ssh -T git@gitee.com

看到欢迎提示就说明密钥生效了。

这一步容易踩的坑有两个：一是用 HTTPS 方式操作仓库，每次都要输密码，虽然也能用，但自动同步体验很差；二是把私钥也当成公钥传上去了。记住：上传到平台的是.pub后缀那个文件的内容，私钥永远留在本地。

2.3 Obsidian 本体与同步插件的设置

Obsidian 方面，我建议先只装一个社区插件：Obsidian Git。这个插件的作用是把常用的 Git 操作集成到 Obsidian 里面，你不需要在笔记软件和终端之间来回切换。安装路径是“设置 → 第三方插件 → 社区插件 → 浏览 → 搜索 Obsidian Git → 安装并启用”。

启用后进入插件设置，我会这样配置：自动备份间隔设为 15 分钟，打开“启动时自动拉取”，打开“每次提交后自动推送”。简单理解：Obsidian 每隔 15 分钟把当前所有改动 commit 成一条记录并 push 到 Gitee；每天第一次打开 Obsidian 时自动从 Gitee 拉取最新内容。这套配置可以让多设备工作流基本无感运行。

还有个细节是.gitignore。我建议在库根目录建一个.gitignore文件，把.DS_Store、.obsidian/workspace.json、.obsidian/cache排除掉，因为工作区状态和缓存是设备相关的，同步它们只会制造冲突；但.obsidian/plugins目录建议保留，这样多台设备的插件列表可以保持一致。这类“创建即配置”的工作，越早做代价越低。

3. 从 0 到 1 的完整实操记录

3.1 本地仓库初始化并推送到 Gitee

如果 Obsidian 库已经存在，第一步是进入库根目录初始化 Git：

cd /path/to/your/vault git init git add . git commit -m "first commit" git remote add origin git@gitee.com:用户名/my-knowledge-base.git git push -u origin main

这里要注意默认分支名。新版本 Git 默认分支是main，Gitee 新仓库默认也是main，两边保持一致最省心。如果 Gitee 仓库创建时勾选了 README，本地第一次 push 之前建议先git pull origin main --allow-unrelated-histories合并一次，再 push。

首次 push 之后，用git log --oneline可以看到提交历史。对我这种习惯性改完就忘的人来说，每次打开历史记录都能看到知识库一点一点积累，心里很有底。如果一个人从来没有用 Git 管过笔记，第一次体验“回滚到旧版本”操作之后，就会明白为什么网盘同步替代不了版本管理。

仓库推完后，记得在 Gitee 网页上把仓库描述写清楚，比如“个人 Obsidian 知识库，存储 Markdown 笔记”。这一步看似无关紧要，但如果你以后有多个仓库、或者想让其他工具接入 Gitee 数据，清晰的描述能帮你快速识别。

3.2 用 Obsidian Git 接管自动同步

手动 Git 命令没问题之后，就可以把 Obsidian Git 插件指到当前库。插件不需要额外配置仓库地址，因为它默认就是“当前 Obsidian 库所在的 Git 仓库”，也就是我们刚刚初始化好的那个目录。启用插件后，左侧边栏会出现一个源控制面板，能直观看到未提交的文件列表。

我建议第一次用插件时不要立刻依赖自动备份，而是先手动点一次“备份”，确认 push 成功，再看自动备份是否按 15 分钟节奏执行。这里有个心得：Obsidian Git 在自动 commit 时的默认提交信息会比较粗糙，如果你参与了某个长期项目，可以在设置里自定义提交信息模板，把当前时间和简单说明带上，后续回溯会方便很多。

自动同步跑通之后，整个工作流就变成：在电脑上写完笔记，后台自动 commit 并 push；在手机上想查看时，用手机上的 Git 客户端或 Obsidian 的同步方案拉取最新版。这套方案的前提是每一端都配置好同一个 SSH 密钥，准确说是每一台设备都要完成一次“生成密钥 + 添加到 Gitee”的动作。

3.3 WorkBuddy 工作台接入知识库并测试问答

WorkBuddy 的接入逻辑通常分三步：新建工作区、指定数据源目录、开始索引。以我当前手上的版本为例，新建一个工作区后，在“数据源”里选择“本地文件夹”，路径指向 Obsidian 的库根目录，然后触发索引。索引过程会读取所有 Markdown 文件，构建检索词条和上下文关联，这一步的时间和笔记数量成正比，几百篇笔记通常几十秒就能完成。

接入后先做三轮测试。第一轮问“库里面有哪些项目？”看它能不能从目录结构和_index.md中给出宏观回答；第二轮问一个具体主题，比如“Docker 多阶段构建的笔记在哪”，看它定位是否准确；第三轮让它做归纳，“把笔记里提到的所有数据库优化技巧列出来”，看它对分散内容的聚合能力。三轮测试能快速暴露目录结构、命名规范和数据源接入的问题。

如果某些笔记始终检索不到，优先检查三处：一是该文件是否被.gitignore或 WorkBuddy 自身规则忽略了；二是文件是否藏在嵌套过深的目录里；三是文件名是否用了辨识度很低的词如“新建文档.md”。这也是我前面反复强调命名规范的原因，AI 工具对“模糊的文件名”同样无能为力。

3.4 把 Skill 技能写进日常流程

WorkBuddy 真正让知识库“活”起来的是 Skill 技能。拿我固定使用的“周度知识回顾”技能举例，它的大致指令是：检索近 7 天修改过的所有笔记，按顶层目录分组，输出每组的要点、关联主题和需要进一步整理的内容。设置方法不复杂：在技能列表里新建一个技能，选择数据源为 Obsidian 库，写好执行逻辑，保存之后即可一键运行。

技能指令没有必要写得太玄。我用一个纯文本格式就能跑得很好：

技能：周度知识回顾 数据源：全部笔记 步骤： 1. 筛选最近7天有改动的 Markdown 文件 2. 按 00-Inbox / 01-Projects / 02-Areas / 03-Resources 分组 3. 对每组输出：新增内容摘要、关键主题、建议下一步动作 输出格式：Markdown 列表

重点是“步骤明确、输出格式明确”。Skill 本质上是一次结构化的指令调用，理解这个后你完全可以写出自己的“每日卡片整理”“主题综述生成”“过期链接检查”等技能。

用熟练之后，我的建议是每个技能只聚焦一个动作，宁可多建几个也不要把一堆逻辑塞进同一个技能。清洗一个动作的技能的运行结果更可控，排错时也更容易定位问题所在。技能是规则的外壳，知识库内容是血肉，两者搭配才是完整工作流。

4. 常见问题与排错实录

4.1 多设备同步冲突

Obsidian Git 自动同步最常见的翻车现场就是“拉取时提示冲突”。典型场景：你在电脑上改了A.md并 push，之后在手机上又把同文件的旧版本改了并尝试 push，或者两台设备在未拉取最新版的情况下各自提交。Git 会在文件中插入冲突标记，比如<<<<<<<、=======、>>>>>>>，看到这些标记就说明该文件需要人工决策。

我的处理流程是：先用git pull或插件里的“拉取”把远端改动拉到本地，打开冲突文件，逐段决定保留哪部分，删掉冲突标记后保存，再提交推送。避免冲突的纪律更重要：每天第一次在设备上打开库时，先让 Obsidian Git 完成“启动时拉取”，再开始写笔记；不要同时开两台设备编辑同一个文件；如果某次 push 被拒，先看本地落后了多少，再决定 rebase 还是 merge。

还有一个容易忽略的点：不要手动去改.obsidian下的插件配置文件来试图“解决冲突”，那不解决问题，只会把插件配置搞坏。真正把冲突降低靠的是提交纪律，不是靠迁移工具。

4.2 Gitee 仓库容量与单文件限制

Gitee 免费私有仓库的容量和单文件大小都有上限，这是很多笔记用户第一次 push 大附件时才会突然发现的。我见过有人把整个 Obsidian 附件目录塞进仓库，里面有几百 MB 的 PDF 和录屏，结果 push 到一半提示文件过大。与其等报错，不如在一开始就把“大文件不进入 Git”定成铁律。

我的附件策略是：图片统一压缩为 JPG/PNG，单张控制在 500KB 以内再放入附件目录；PDF、视频、音频一律不放进 Gitee 仓库，需要存档时放到独立的文件存储，或干脆放本地大容量目录并做好定期备份。值得一提，WorkBuddy 对图片的索引能力不如纯文本，所以图片类资料我通常会花 30 秒在笔记里写一句文字说明，这比任何 OCR 硬扫都可靠。

如果仓库已经塞满，处理办法有两个方向：一是用 Git 清理历史，比如git filter-branch或git gc，重写历史去掉大文件，但这个操作需要所有设备重新 clone，成本偏高；二是更朴素的方案：按年拆库，把当前库归档，建一个新库继续记录。文本笔记的增量很小，拆库对个人用户来说足够支撑很多年。

4.3 WorkBuddy 索引不到新笔记

WorkBuddy 接入后最常被问到的问题是：“我明明在 Obsidian 里新写了一篇笔记，为什么问它的时候没有结果？”第一反应是看同步链路：如果 Obsidian Git 的自动 push 没执行或者执行失败，WorkBuddy 读取的还是旧索引，自然检索不到。先解决 Git 同步问题，再看索引问题。

确认同步正常后，需要触发一次索引重建。在我用的版本里，数据源设置项里有“重建索引”按钮，点击后它会重新扫描全部文件。另外检查一下 WorkBuddy 的权限：在 macOS 上，第一次选择本地文件夹时需要在系统设置里允许“文件和文件夹”访问；在 Windows 上，某些安全软件会拦截它对目录的读取，需要在排除列表里加上库目录。

排除以上原因后还有一个容易被忽视的点：如果笔记内容是一句话或者只有标题没有正文，AI 工具能用来判断的信息太少，检索命中率会极低。我的应对方法是至少写三五行正文，把关键词、上下文、结论写进去。知识库里的每一篇笔记，都是给未来的自己和工作流模型留的一条线索。

4.4 双链失效与图谱混乱

用 Obsidian 一段时间后，你可能会发现关系图谱里出现一堆孤立节点，或者点击链接提示“文件不存在”。最常见的原因是文件被重命名或移动，而引用它的笔记没有跟着更新。解决办法在设置里很不起眼：进入“文件与链接”，把“自动更新内部链接”打开，尽量使用[[文件名]]这种 Wiki 链接形式，避免手写[文本](路径)这种 Markdown 链接。

另一个原因是附件路径。Obsidian 默认附件会进到一个“新附件文件夹”，但如果你把笔记和附件放在不同目录，且设置了“基于最近笔记的文件夹”，移动文件后图片引用很容易断。我的习惯是：在库根目录建一个attachments文件夹，在设置里把“默认附件位置”固定为它，然后所有图片生成时统一落进去，避免散落。

对已经失效的链接，可以装一个“Find orphaned files”或“Broken links”类插件扫描，逐个修复。不过我更要强调：双链的价值在于语义关联，不是为了图谱好看。每次新建笔记时问自己一句“这条笔记跟哪几条已有笔记相关”，然后顺手加上双向链接，比事后整理高效得多，AI 工具参考到的上下文也会更丰富。

最后说点私人的体会。这套东西真正跑起来后，最大的变化不是“我有了一个 AI 问答机器”，而是我开始更认真地对待输入。知识库的底层逻辑没有变：存储是地基，AI 只是加速器。WorkBuddy 能回答得多准，取决于喂进去的内容有多规整；Gitee 能保护得多好，取决于你愿不愿意每改一段就多留一次提交。我自己现在每天 15 分钟往 Inbox 里丢碎念头，每周日花半小时让 WorkBuddy 做一轮知识回顾，把散落的内容归位。坚持几个月后回头翻提交历史，那感觉比任何连续打卡都有成就感。

这个组合如果还要往下扩展，我下一步想试的方向是把 Gitee 仓库作为多端的中转，在手机上用移动端 Git 客户端直接提交，然后把 WorkBuddy 的 Skill 跑成定时任务，让“每周回顾”自动落地成笔记。反正思路已经通了，工具换来换去，核心始终是那几条：纯文本、有版本、能索引。你先按这套搭起来，跑通后再按自己的习惯调结构，会比直接照搬别人的模板稳妥得多。