docs: 6月25-26日知识库架构重构完整文档
This commit is contained in:
fxy
167
docs/2026-06-26-知识库架构重构.md
Normal file
167
docs/2026-06-26-知识库架构重构.md
Normal file
@ -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 图标
|
||||
Reference in New Issue
Block a user