docs: 6月25-26日知识库架构重构完整文档

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 图标