168 lines
6.0 KiB
Markdown
168 lines
6.0 KiB
Markdown
# 知识库架构重构 · 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 图标
|