From 025825596ab1388a95ea1bf260dabcb3b97d5ae4 Mon Sep 17 00:00:00 2001 From: fxy Date: Fri, 26 Jun 2026 14:58:33 +0800 Subject: [PATCH] =?UTF-8?q?docs:=206=E6=9C=8825-26=E6=97=A5=E7=9F=A5?= =?UTF-8?q?=E8=AF=86=E5=BA=93=E6=9E=B6=E6=9E=84=E9=87=8D=E6=9E=84=E5=AE=8C?= =?UTF-8?q?=E6=95=B4=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/2026-06-26-知识库架构重构.md | 167 ++++++++++++++++++++++++++++++ 1 file changed, 167 insertions(+) create mode 100644 docs/2026-06-26-知识库架构重构.md diff --git a/docs/2026-06-26-知识库架构重构.md b/docs/2026-06-26-知识库架构重构.md new file mode 100644 index 0000000..be6db87 --- /dev/null +++ b/docs/2026-06-26-知识库架构重构.md @@ -0,0 +1,167 @@ +# 知识库架构重构 · 2026年6月25-26日 + +## 背景 + +6月25日完成导航页崩坏修复、Authelia SSO部署、Homepage/Wiki.js初装。6月26日完成知识库全链路重构，从自建前端转向成熟开源方案，确立了「两层分离」的最终架构。 + +--- + +## 一、核心决策 + +### 1.1 放弃自建前端，拥抱成熟方案 + +| 之前 | 之后 | 原因 | +|------|------|------| +| 自建 search.html/reader.html | Wiki.js + ask.xybkwd.top | 自建前端频繁崩溃，JS 语法错误、CDN 问题不断 | +| Meilisearch 做展示 | Meilisearch 做搜索后端 | 搜索引擎的长板是检索，短板是展示 | +| 单体前端 | 两层分离 | Gitea→Wiki.js展示层 + Meilisearch→AI检索层 | + +### 1.2 两层分离架构 + +``` +层1: 知识库展示 + Gitea(fxy) + Memos(SQLite) → cron聚合 → wiki-knowledge-base → Wiki.js + ↓ ↓ + inspiration-collector wiki.xybkwd.top + weread-notes 454篇页面 + work-docs + +层2: 知识库检索 + wiki-knowledge-base → Meilisearch → RAG(DeepSeek) → AI问答页 + 457篇索引 25篇/35000字 ask.xybkwd.top +``` + +**设计原则**： +- Git 是唯一真相源，Wiki.js 是只读展示 +- Meilisearch 不与 Wiki.js 集成（版本 2.5 不支持），作为独立后端 +- AI 问答页独立部署，不注入 Wiki.js DOM（Vue SPA 注入不稳定） + +--- + +## 二、Wiki.js 部署细节 + +### 2.1 多仓库聚合 +- 聚合仓库：`beast/wiki-knowledge-base` +- 同步脚本：`/home/ubuntu/wiki-knowledge-base/sync.sh`，cron 每小时 15 分 +- 四个来源：inspiration(214) + reading(119) + work(3) + memos(117) + +### 2.2 批量导入踩坑 +- Wiki.js Git 存储不会把仓库已有 .md 自动展示为页面 +- API Key 只有读权限，需 JWT 认证（密码临时改为 tmp123456，导入后恢复） +- 通过 GraphQL API 批量创建 454 个页面 + +### 2.3 网络配置 +- Gitea：`HTTP_ADDR = 0.0.0.0`（原 127.0.0.1），iptables DROP 保护外网 +- Wiki.js：Git 存储指向 `http://172.17.0.1:3000/beast/wiki-knowledge-base.git` +- docker-compose volume 持久化修复（原容器重启丢配置） + +--- + +## 三、Meilisearch 迁移 + +### 3.1 从北京迁到东京 +- 北京 Meilisearch：空索引，已停用 +- 东京 docker-compose 新增 Meilisearch v1.13，端口 localhost:7700 +- 索引脚本：`/home/ubuntu/wiki/meili_index.py` + +### 3.2 中文搜索局限性 +- Meilisearch v1.13 中文按单字分词，「工程物资」→ 「工/程/物/资」 +- 应对策略：扩大检索量（25篇/35000字），交给 DeepSeek 智能筛选 + +--- + +## 四、AI 问答平台 + +### 4.1 RAG 服务 +- FastAPI 容器（wiki-rag:8200），docker-compose 管理 +- 检索：Meilisearch top 25 → 拼上下文 → DeepSeek 生成 +- 对话存储：服务器 JSON 文件 `/home/ubuntu/wiki/conversations/` + +### 4.2 前端 +- 独立域名 `ask.xybkwd.top`，纯静态 HTML +- marked.js 渲染 Markdown，Catppuccin 暗色主题 +- 对话列表、新建/切换/删除、自动保存 + +### 4.3 UI 注入失败教训 +- 尝试 4 次在 Wiki.js 注入搜索框/AI按钮，均失败 +- 原因：Wiki.js 是 Vue SPA，injectBody 脚本执行时机与 Vue 渲染竞争 +- 结论：独立页面是最可靠的方案 + +--- + +## 五、Homepage 看板重构 + +### 5.1 仪表盘聚合 +- 旧：DeepSeek 余额 + 北京状态，两个独立 API（9099/9098） +- 新：统一 API（9097: dashboard_api.py），三个卡片 + - DeepSeek 余额 ¥73.xx + - 东京：内存 62.8% / 磁盘 55% + - 北京：状态 online / 内存 25% / 磁盘 14% + +### 5.2 网络模式修复 +- 原 Homepage 桥接网络，`host.docker.internal` 无法解析 +- 改为 `network_mode: host`，直接访问 localhost API + +### 5.3 视觉优化 +- 主题：zinc 暗色 + 毛玻璃卡片 +- 精简：移除 WebDAV 日记、待办等纯链接项 +- 图标：服务卡片全部使用 Homepage 内置图标 + +--- + +## 六、Caddy 路由变更 + +| 域名 | 路由 | 变更 | +|------|------|------| +| nav.xybkwd.top | `/search-api*` → localhost:7700 | 北京 Meili 改为东京本地 | +| ask.xybkwd.top | `/api/*` → localhost:8200 | 新增 AI 问答域名 | +| wiki.xybkwd.top | `handle_path /api/ask*` | 预留（未启用，留给 Auth 通过后使用） | + +--- + +## 七、服务全景 + +### 东京服务器 (43.163.225.30) + +| 服务 | 端口 | 域名 | +|------|------|------| +| Caddy | 80/443 | 所有域名 | +| Gitea | 3000 | gitea.xybkwd.top | +| Wiki.js | 3100 | wiki.xybkwd.top | +| Meilisearch | 7700 | nav/search-api 反代 | +| RAG API | 8200 | ask.xybkwd.top/api/* | +| Memos | 5230 | memo.xybkwd.top | +| Audiobookshelf | 13378 | podcast.xybkwd.top | +| Vaultwarden | 8088 | vault.xybkwd.top | +| WebDAV | 8766 | dav.xybkwd.top | +| Calibre-Web | 8083 | books.xybkwd.top | +| Halo | 8090 | halo.xybkwd.top | +| Freqtrade | 8080 | dashboard.xybkwd.top | +| Homepage | 3001 | nav.xybkwd.top | +| Authelia | 9091 | auth.xybkwd.top | +| Dashboard API | 9097 | nav(内部) | + +### 数据管道 + +``` +Memos SQLite → memos_export.py +Gitea repos → sync.sh (cron 15分) + ↓ +wiki-knowledge-base (聚合仓库) + ↓ +├── Wiki.js Git Sync (每5分) → wiki.xybkwd.top +└── meili_index.py → Meilisearch → RAG → ask.xybkwd.top +``` + +--- + +## 八、踩坑清单 + +1. **heredoc 转义**：反斜杠和引号在 bash heredoc 中频繁被吃掉，推荐 SCP 上传 Python 脚本 +2. **Wiki.js 注入**：Vue SPA 的 injectBody 与 DOM 渲染存在竞态条件，不适合做 UI 注入 +3. **Caddy forward_auth**：包裹整个站点，无法在 auth 域内做路径级绕过，需用独立域名 +4. **Meilisearch doc ID**：只支持 `[a-zA-Z0-9_-]`，中文路径需 hash 编码 +5. **PostgreSQL json vs jsonb**：Wiki.js settings 的 value 是 json 类型，不支持 jsonb_set +6. **Docker 容器访问宿主机**：`host.docker.internal` 需要 extra_hosts 或 network_mode:host +7. **YAML % 引号**：`suffix: %` 不加引号导致 YAML 解析失败，首页崩溃 +8. **Simple Icons 不彩色**：Homepage 的 si- 图标默认单色，需自定义 PNG/SVG 图标