企业官网建设流程全解析

1. 为什么我要折腾这套三联组合

先说结论：我用了大半年时间，把 Obsidian、WorkBuddy 和 Gitee 这三样东西串成了一条流水线，现在我的个人知识库已经能做到"记进去就不用管，需要的时候 AI 帮我翻出来"。这套方案解决的核心问题就一个——笔记越攒越多，但真正要用的时候找不到、用不上。

我相信很多人跟我一样，Obsidian 里躺着几百上千篇笔记，标签打了一堆，文件夹分了好几层，可真到写方案、查资料的时候，还是靠搜索框硬搜关键词，搜出来的东西零零散散，还得自己重新拼。这就是典型的"知识库变成了知识坟场"。而 AI 驱动的知识库，本质上是给你的笔记加了一层"语义理解"，你问它问题，它去你的笔记里找答案，而不是让你自己去翻。

这套组合里，三个角色分工很明确。Obsidian 是仓库，负责本地存储、双链关联、Markdown 纯文本管理，数据完全在你自己手里；WorkBuddy 是大脑，负责把笔记切片、向量化、建立语义索引，让你能用自然语言提问；Gitee 是保险柜加传送带，负责版本管理和多设备同步，顺便还能当备份。三者各司其职，谁也不越界。

适合谁来参考？我觉得三类人最合适。第一类是已经有 Obsidian 使用习惯、笔记量在 200 篇以上的朋友，你已经过了"记什么"的阶段，现在卡在"怎么用"；第二类是对 AI 感兴趣但不想把笔记传到别人服务器上的隐私敏感型用户，这套方案全程本地或私有仓库；第三类是喜欢折腾、愿意花一个周末把基础设施搭好的技术爱好者。如果你笔记还没超过 50 篇，我建议先老老实实记，别急着上 AI，数据量不够的时候语义检索的优势体现不出来。

下面我按"整体设计思路 → 核心组件拆解 → 实操搭建 → 踩坑排查"这个顺序讲，每一步都会说清楚为什么这么做，而不是只给命令。你照着做，一个下午能跑通。

2. 整体架构设计与选型逻辑

2.1 三个组件各自解决什么问题

很多人一上来就问"用什么工具"，但我觉得更重要的是先想清楚"每个环节要解决什么"。我把知识库的完整链路拆成四段：采集 → 存储 → 理解 → 调用。Obsidian 管存储和初步关联，WorkBuddy 管理解和调用，Gitee 管跨设备的存储同步和版本兜底。

为什么不用 Notion 或者飞书这类云端一体方案？因为它们把"存储"和"理解"绑死了，你没法单独替换其中一环。而我这套是解耦的——哪天 WorkBuddy 不好用了，我换一个向量化工具，Obsidian 里的笔记一个字都不用动。这种"可替换性"是我选型时最看重的东西。

再说不选纯云端 RAG 服务的原因。你的笔记里可能有工作草稿、个人思考、读书笔记，这些东西传给第三方做向量化，心理上总归不踏实。本地跑 WorkBuddy，数据不出机器，这是底线。

2.2 为什么是 Gitee 而不是别的同步方式

Obsidian 自带的同步要付费，第三方网盘同步又容易产生冲突文件（我见过最惨的一次，一个笔记被同步出 7 个冲突副本）。用 Git 做同步的好处是：版本可追溯、冲突可合并、历史可回滚。你改错了一篇笔记，git log一看就知道哪天改的，git checkout一键还原。

选 Gitee 而不是其他代码托管平台，主要是两个考虑。一是国内访问速度稳定，git push和git pull不用等半天；二是私有仓库免费，个人知识库这种敏感内容放私有仓库是必须的。至于开源许可证，个人私有仓库根本用不上，别被那些"选什么许可证"的教程带偏了，那是给公开项目准备的。

提示：Gitee 单文件有大小限制，普通 Markdown 笔记完全没问题，但如果你往库里塞大附件（比如几十兆的 PDF、视频），需要单独处理，后面实操部分我会讲。

2.3 数据流向全景

我把整条链路画成文字版，方便你理解数据怎么流动：

1. 你在 Obsidian 里写笔记，存成.md文件，放在本地 vault 目录；
2. WorkBuddy 监听这个目录，把新增或修改的笔记切片、生成向量，存进本地向量库；
3. 你通过 WorkBuddy 的对话界面提问，它检索向量库，把相关笔记片段喂给大模型，生成回答；
4. 你写完一批笔记，用 Git 命令提交到 Gitee 私有仓库；
5. 换一台电脑，git clone或git pull拉下来，Obsidian 打开同一个 vault，WorkBuddy 重新索引一遍，继续用。

这个流程里，Obsidian 的 vault 目录是唯一的数据源，其他所有东西都是围绕它服务的。记住这一点，后面出问题排查就有方向了。

3. 核心组件深度拆解与配置要点

3.1 Obsidian 的目录结构设计

Obsidian 用得好不好，八成看目录结构。我踩过的最大坑就是早期把所有笔记平铺在一个文件夹里，等到 300 篇的时候，侧边栏滚都滚不完。后来我改成了一套"按用途分层"的结构，你可以直接抄：

vault/ ├── 00-Inbox/ # 临时收集，每周清空 ├── 10-Notes/ # 永久笔记，原子化，一篇一个概念 ├── 20-Projects/ # 项目相关，有明确起止时间 ├── 30-Areas/ # 长期关注的领域 ├── 40-Archive/ # 归档，不再活跃 ├── 90-Attachments/ # 图片、附件统一放这里 └── 99-Templates/ # 模板文件

这套结构借鉴了 PARA 方法，但做了简化。核心逻辑是：Inbox 负责快，Notes 负责准，Projects 和 Areas 负责用。你随手记的东西先扔 Inbox，每周花半小时整理，该拆成原子笔记的拆到 Notes，该归项目的归 Projects。

为什么附件要单独放90-Attachments？因为 WorkBuddy 做向量化的时候，主要是处理文本，图片和 PDF 需要额外配置。把附件隔离出来，可以让索引过程更干净，也方便你后面单独处理图片类知识（比如截图、扫描件）。

注意：Obsidian 的附件默认会放在笔记同级目录，一定要在设置里改成"指定附件文件夹"，指向90-Attachments，否则你的目录会越来越乱。

3.2 WorkBuddy 的索引机制与参数选择

WorkBuddy 这类工具的核心是文本切片 + 向量化 + 相似度检索。我重点讲切片策略，因为这是最影响效果、又最容易被忽略的环节。

切片（chunking）就是把一篇长笔记切成一段段小文本，每段单独生成向量。切得太粗，检索出来的片段包含太多无关信息，大模型容易被干扰；切得太细，一段话被拆散，语义不完整。我的经验值是：中文笔记每片 300 到 500 字，重叠 50 字。重叠是为了防止一句话正好被切在边界上，导致语义断裂。

WorkBuddy 的配置里通常有这几个参数需要调：

top_k设 5 是我实测下来比较平衡的值。设 3 有时候漏掉关键信息，设 10 又会把不相关的内容塞进上下文，反而让模型答偏。相似度阈值 0.7 是个经验值，低于这个分数的片段基本是"沾边但不相关"，宁可少给也别给错。

3.3 Gitee 仓库的初始化与密钥配置

Git 同步的第一步是配置 SSH 密钥，这样每次 push 不用输密码。流程是：本地生成密钥对 → 把公钥贴到 Gitee → 测试连接。

# 生成密钥，邮箱换成你的 ssh-keygen -t ed25519 -C "your_email@example.com" # 一路回车，默认存在 ~/.ssh/id_ed25519 # 查看公钥内容，复制它 cat ~/.ssh/id_ed25519.pub

复制出来的那串以ssh-ed25519开头的内容，贴到 Gitee 的"设置 → SSH 公钥"里。然后测试：

ssh -T git@gitee.com

看到欢迎信息就说明通了。这一步很多人卡住，八成是公钥复制的时候带了换行或者少了字符，仔细核对。

仓库建好后，在本地 vault 目录初始化：

cd /path/to/your/vault git init git remote add origin git@gitee.com:yourname/your-repo.git

3.4 大文件与附件的处理策略

Gitee 对单文件和仓库总大小有限制，附件多了会 push 失败。我的处理方式是：用.gitignore排除大附件，附件单独用网盘或对象存储同步。

在 vault 根目录建一个.gitignore：

# 排除大附件 90-Attachments/*.pdf 90-Attachments/*.mp4 90-Attachments/*.zip # 排除 Obsidian 的工作区缓存 .obsidian/workspace.json .obsidian/workspace-mobile.json # 排除系统文件 .DS_Store Thumbs.db

.obsidian/workspace.json记录的是你当前打开了哪些面板、光标在哪，这个文件每台机器都不一样，同步过去只会造成冲突，必须排除。但.obsidian下的插件配置、主题设置是要同步的，所以不能整个文件夹排除，只排除 workspace 相关文件。

4. 完整实操流程与关键环节

4.1 环境准备与工具安装

先把三样东西装齐。Obsidian 去官网下载对应系统的安装包，装完新建一个 vault，路径选一个你记得住的地方，比如~/Documents/MyVault。WorkBuddy 按官方文档安装，注意看清楚是桌面版还是命令行版，两者配置方式不同。Git 用系统包管理器装，Windows 用 Git for Windows，macOS 用brew install git。

装完之后验证一下：

git --version # 应该输出 git version 2.x.x

WorkBuddy 装好后，先别急着索引，用一篇测试笔记跑通流程再说。新建10-Notes/测试笔记.md，随便写点内容，比如"今天学习了向量检索的基本原理，核心是把文本映射到高维空间"。

4.2 WorkBuddy 索引配置实操

打开 WorkBuddy 的配置界面，找到知识库或索引相关的设置项。不同版本菜单名称可能不一样，但核心配置项就那几个：

1. 知识库路径：指向你的 Obsidian vault 目录，注意是 vault 根目录，不是某个子文件夹；
2. 文件类型过滤：只索引.md文件，其他类型先排除，减少噪音；
3. 切片参数：按前面说的 400/50 设置；
4. 向量模型：如果支持本地模型就选本地的，隐私性更好；如果只能用在线模型，注意看它的数据处理政策。

配置完点"开始索引"，第一次会比较慢，几百篇笔记可能要跑十几分钟。跑完之后，在对话界面问一个你笔记里明确写过的问题，看它能不能准确找出来。如果答非所问，八成是切片参数或者相似度阈值需要调。

实操心得：索引完成后，我建议你手动测试 5 到 10 个问题，覆盖不同笔记。比如问"我关于 XX 项目的笔记里提到了哪些风险"，看它能不能把分散在几篇笔记里的风险点都找出来。这一步能帮你提前发现配置问题。

4.3 Git 首次提交与推送

索引跑通后，把 vault 提交到 Gitee。注意顺序：先建.gitignore，再git add，否则会把不该传的文件也加进去。

cd ~/Documents/MyVault # 确认 .gitignore 已创建 cat .gitignore # 添加所有文件 git add . # 查看将要提交的文件列表，确认没有大附件 git status # 提交 git commit -m "初始化知识库：Obsidian vault + WorkBuddy 配置" # 推送到 Gitee git push -u origin master

git status这一步千万别跳过。我有一次偷懒直接 commit，结果把一个 200 兆的录屏文件传上去了，push 卡了半小时最后失败，还得用git reset回退重来。养成看git status的习惯，能省很多事。

4.4 多设备同步的日常工作流

两台电脑之间同步，标准流程是"先拉后推"：

# 早上到公司，先拉最新 git pull # 写了一天笔记，下班前提交 git add . git commit -m "更新：XX 项目笔记 + 读书笔记 3 篇" git push

这里有个关键点：WorkBuddy 的索引数据要不要同步？我的建议是不同步。索引文件通常很大，而且换台机器重新索引一遍也就十几分钟，没必要传。把索引目录加进.gitignore就行。

如果你在两台机器上都改了笔记，git pull时可能冲突。Markdown 文件的冲突其实好解决，打开冲突文件，会看到<<<<<<<和>>>>>>>标记，手动选择保留哪部分就行。为了避免冲突，我的习惯是同一篇笔记尽量只在一台机器上编辑，跨设备时先 pull 再动手。

4.5 让 AI 检索更准的三个技巧

索引跑通只是及格线，想让它真正好用，还得在笔记写法上下功夫。我总结了三个立竿见影的技巧。

第一，每篇笔记开头写一句"摘要句"。比如一篇讲 Git 冲突解决的笔记，开头就写"本文解决 Git 多设备同步时的文件冲突问题"。这句话会被向量化，检索时命中率极高。很多人笔记开头直接是正文，AI 抓不住重点。

第二，用双链建立概念关联。Obsidian 的[[双链]]不只是给人看的，WorkBuddy 在切片时能识别这些链接，把相关笔记串起来。你问"XX 概念"，它可能同时返回定义笔记和应用案例笔记。

第三，标签要克制。我见过有人一篇笔记打十几个标签，结果标签系统彻底失效。我的原则是每篇笔记最多 3 个标签，且标签要成体系，比如#方法论、#工具、#案例这种粗粒度分类，细粒度靠双链和搜索。

5. 常见问题排查与避坑实录

5.1 索引相关的问题

问题：WorkBuddy 索引后，提问总是答非所问。

排查顺序：先看切片参数是不是太大，如果一篇 2000 字的笔记只切成 2 片，每片 1000 字，检索精度肯定差；再看相似度阈值是不是太低，把不相关的内容也放进来了；最后看笔记本身是不是太口语化、缺乏明确的概念表述。我遇到过一篇笔记全是"今天搞了半天终于弄好了"这种流水账，AI 根本提取不出有效信息。

问题：新增笔记后，AI 检索不到。

大概率是索引没有增量更新。WorkBuddy 有的版本需要手动触发重新索引，有的支持文件监听自动更新。去配置里确认一下"自动索引"或"监听文件变化"的选项有没有开。如果开了还不生效，重启一下 WorkBuddy 服务。

5.2 Git 同步相关的问题

问题：push 时报错remote: error: File xxx is 100.00 MB; this exceeds file size limit。

说明有大文件被提交了。解决步骤：

# 从暂存区移除大文件 git rm --cached path/to/bigfile # 把它加进 .gitignore echo "path/to/bigfile" >> .gitignore # 重新提交 git commit --amend -m "移除大文件" git push

如果大文件已经在历史提交里了，处理起来更麻烦，需要用git filter-branch或者 BFG 工具清理历史。所以最好的办法是一开始就把 .gitignore 配好。

问题：git pull时提示冲突，不知道怎么处理。

先别慌，冲突不是错误，是 Git 在问你"这两处改动你想保留哪个"。打开冲突文件，找到<<<<<<< HEAD到=======之间是你本地的改动，=======到>>>>>>>之间是远程的改动。手动编辑成你想要的结果，删掉那些标记符号，然后：

git add 冲突文件 git commit -m "解决冲突" git push

5.3 常见问题速查表

5.4 几个我踩过的坑

坑一：把.obsidian整个同步了。结果两台电脑的插件配置互相覆盖，A 电脑装的插件在 B 电脑上显示已安装但用不了。正确做法是只同步.obsidian/plugins和.obsidian/themes，排除 workspace 文件。

坑二：笔记文件名用了特殊字符。比如如何解决 C++ 的 "内存泄漏" 问题.md，引号在 Git 和某些系统上会出问题。文件名尽量用中文、英文、数字和连字符，别用引号、斜杠、冒号。

坑三：以为索引一次就一劳永逸。知识库是活的，你每天在写新东西，索引也得跟着更新。我现在养成的习惯是每周五下班前，手动触发一次全量重新索引，顺便把 Inbox 里的临时笔记整理归档。

坑四：过度依赖 AI 检索，自己不动脑。有段时间我什么问题都问 AI，结果发现它给的答案虽然来自我的笔记，但组合方式未必是我想要的。后来我改成"AI 检索 + 自己精读原文"，效率反而更高。AI 是帮你缩小范围的，不是替你做判断的。

6. 进阶玩法与扩展方向

6.1 接入更多数据源

Obsidian 只是起点。你可以把 Zotero 的文献笔记导出成 Markdown 放进 vault，把微信公众号文章用剪藏工具存进来，甚至把网页书签转成笔记。数据源越丰富，AI 能回答的问题范围越广。我现在的知识库里，除了自己的笔记，还有 200 多篇文献摘要和 100 多篇剪藏文章。

导入 Zotero 笔记的常见做法是用 Zotero 的 Markdown 导出插件，把文献笔记批量导出到10-Notes下的一个子文件夹。注意导出后检查一下格式，有些插件导出的 Markdown 会带一堆元数据，需要清理。

6.2 用本地小模型降低成本

如果你不想调用在线大模型，可以在本地跑一个小参数模型做向量化和问答。卡帕西那种级别的知识库用大模型效果当然好，但个人知识库用 7B 到 13B 的模型其实够用了。关键是向量化模型要选对，中文场景下选专门针对中文优化的 embedding 模型，检索准确率会高很多。

本地模型的代价是速度慢、占内存，但换来的是完全离线、数据不出机器。我的建议是：向量化用本地小模型，问答环节如果追求质量可以调在线模型，两者分开配置。

6.3 知识库的定期维护

知识库跟花园一样，不修剪就会荒。我给自己定了三条维护规则：每月清理一次 Inbox，把临时笔记要么归档要么删除；每季度检查一次双链，把断链修掉；每半年做一次全量备份，除了 Gitee 仓库，再导出一份到移动硬盘。

最后分享一个我最近在用的技巧：在 WorkBuddy 里设置一个"每周回顾"的提示词，让它自动从我这周新增的笔记里提取关键概念和待办事项，生成一份周报草稿。这个用法把知识库从"被动查询"变成了"主动推送"，体验完全不一样。你可以试试，提示词大概是"请阅读我本周新增的笔记，总结三个核心主题，并列出所有标记为待办的事项"。