6.0 KiB
6.0 KiB
知识库架构重构 · 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
八、踩坑清单
- heredoc 转义：反斜杠和引号在 bash heredoc 中频繁被吃掉，推荐 SCP 上传 Python 脚本
- Wiki.js 注入：Vue SPA 的 injectBody 与 DOM 渲染存在竞态条件，不适合做 UI 注入
- Caddy forward_auth：包裹整个站点，无法在 auth 域内做路径级绕过，需用独立域名
- Meilisearch doc ID：只支持
[a-zA-Z0-9_-]，中文路径需 hash 编码 - PostgreSQL json vs jsonb：Wiki.js settings 的 value 是 json 类型，不支持 jsonb_set
- Docker 容器访问宿主机：
host.docker.internal需要 extra_hosts 或 network_mode:host - YAML % 引号：
suffix: %不加引号导致 YAML 解析失败，首页崩溃 - Simple Icons 不彩色：Homepage 的 si- 图标默认单色，需自定义 PNG/SVG 图标