首页 > 开源 > WIKI 本地知识库从 v1.0.0 升级 v1.1.0 的迁移指南

WIKI 本地知识库从 v1.0.0 升级 v1.1.0 的迁移指南

OSChina资讯 2026-08-26 22:54 1 阅读 查看原文
知识库 版本升级 技术文档

项

说明

文档日期

2026-08-25

升级路径

v1.0.0 → v1.1.0

适用对象

已部署 v1.0.0、需升到 v1.1.0 的运维 / 二次开发同学

v1.1.0 相对 v1.0.0 的工程变化

Vue 控制台 frontend/、配置优先 conf/、业务 API 统一 /api

0. 先看结论

维度

结论

知识库数据（kb_store/ 等）

一般可直接沿用；路径以配置 knowledge_base.storage 为准

会话 / 历史库

一般可沿用；若仍用旧库表，可继续用现有迁移脚本

配置文件

建议从根目录 config.json 迁到 conf/config.json；根目录文件仍兼容

Web 控制台

必须用 v1.1.0 重新构建 frontend/dist；v1.0.0 的 web/ 已归档，默认不再服务

自研 / 外部调用方

必须改 API 路径：统一加 /api 前缀

一句话：备份 v1.0.0 的配置与 kb_store → 迁配置 → 改调用路径 → 安装/构建 v1.1.0 控制台 → 冒烟验证。

1. v1.0.0 与 v1.1.0 对照

1.1 目录与入口

v1.0.0

v1.1.0

迁移动作

web/.html + app.js

frontend/（Vue3），产物 frontend/dist

构建新前端；勿再改 web/

web/ 随发布包提供

archive/web/ 归档

仅对照；默认不挂载

根目录 config.json

优先 conf/config.json

复制并核对路径后启动

src/api.py 等集中实现

src/api/http_server.py + handlers/

二次开发改 handlers

build.ps1 拷贝 web/

构建并拷贝 frontend/dist + conf/

使用 v1.1.0 脚本（见 §4）

入口常为 /ui/ 等

/ 起即 Vue SPA

更新书签与反向代理

1.2 URL / 页面

v1.0.0（约）

v1.1.0

说明

http://host:5000/ui/ 或静态首页

http://host:5000/

默认托管 frontend/dist

web 聊天页

/retrieval-qa

检索问答

kb.html

/kb/management

知识库管理

model.html

/model/management

模型管理

docs/API.html 或 /docs/

/api-docs（Vue 页）

勿再依赖后端直接吐 API.html

  • 临时对照 v1.0.0 静态台（一般不需要）：

KB_SERVE_LEGACY_WEB=1

启用后经 /legacy-ui/ 提供归档静态页。新功能只在 Vue 控制台上使用。

1.3 HTTP API

v1.0.0

v1.1.0

/query、/kb/...、/stats…

/api/query、/api/kb/...、/api/stats…

无统一前缀约定

业务接口一律 /api；可用 KB_API_PREFIX 覆盖（默认 /api）

v1.1.0 前端 VITE_API_BASE_URL 默认已是 /api。外部脚本、网关、旧 SDK 必须改路径。

1.4 行为差异（容易踩坑）

项

v1.0.0 常见行为

v1.1.0

deep_think

部分路径默认偏「开」或前端常开

默认 false；关闭时不注入/不下发思考标记

文档解析

以文字层为主

仍以文字层抽取为主

文档分片

固定长度（或环境内混用策略）

默认固定长度分片；已有 chunk 不会因升级自动重切

2. 升级前准备（必做）

  1. 停掉 v1.0.0 服务（含 Windows 服务 / systemd 若已注册）。

  2. 备份（至少）：

    • 配置：config.json 或整份 conf/

    • 知识库目录：配置中的 kb_store（或等价路径）

    • 会话/历史库：SQLite / MySQL / PostgreSQL / Redis 相关数据

    • 模型缓存目录（可选，体积大可只记路径）

  3. 记录当前访问方式：端口、反向代理、调用方清单（谁还在打裸 /query）。

  4. 确认运行环境：

    • Python 3.10+

    • 构建控制台需要 Node.js 18+ 与 npm

3. 配置迁移（v1.0.0 → v1.1.0）

3.1 推荐步骤

1. 将 v1.0.0 根目录 config.json 复制为 v1.1.0 的 conf/config.json
2. 按需增加 conf/config.dev.json / conf/config.prod.json（可选）
3. 设置 KB_ENV=dev|prod 时可自动合并对应覆盖文件
4. 校验 knowledge_base.storage 仍指向原 kb_store
5. 灰度可用 KB_CONFIG_PATH 显式指定配置文件

  • v1.1.0 加载优先级：

  1. 环境变量 KB_CONFIG_PATH

  2. conf/config.json

  3. 仓库根目录 config.json（兼容 v1.0.0 布局）

3.2 建议核对的字段

配置块

核对点

server

host / port 是否与防火墙、反代一致

knowledge_base.storage

数据目录、模型缓存、向量后端（faiss / zvec / numpy）

knowledge_base.embedding / rerank / chat

模型名与本地路径

db / session

后端类型与连接串

chat_context

轮数与开关

多提供商可参考包内 conf/config.multi-provider.example.json（若存在）。

3.3 环境变量（v1.1.0 常用）

变量

用途

KB_CONFIG_PATH

自定义配置文件

KB_PROJECT_ROOT

安装根目录（发行包 run.ps1 会设）

KB_API_PREFIX

API 前缀，默认 /api

KB_SERVE_LEGACY_WEB

1 时挂载归档静态台（仅过渡）

4. 升级到 v1.1.0 的步骤

4.1 源码部署

# 1. 切换到 v1.1.0（保留本地 kb_store 与 conf）
git fetch
git checkout v1.1.0
# 或：解压 / 覆盖安装 v1.1.0 发行包，勿覆盖已备份的数据目录

# 2. Python 依赖
pip install -r requirements.txt
# GPU 等按原习惯选 requirements.cuda.txt / cpu / rocm

# 3. 配置迁到 conf/（若尚未）
# 4. 构建 v1.1.0 控制台
cd frontend
npm install
npm run build
cd ..

# 5. 启动
python -m src.main

4.2 Windows 发行包（build.ps1）

v1.0.0 脚本会拷贝 web/；v1.1.0 脚本会：

  • 构建并打包 frontend/dist

  • 复制 conf/

  • run.ps1 / run.bat 写入 KB_PROJECT_ROOT 等运行环境

.\build.ps1 -Clean -Version 1.1.0

# 已有 frontend/dist 时
.\build.ps1 -Clean -SkipFrontendBuild -Version 1.1.0

  • 注意：build.ps1 需 UTF-8 BOM（Windows PowerShell 5.1）；若出现中文解析错误，勿用「无 BOM UTF-8」覆盖保存。

  • 安装包内：

cd dist
.\setup.ps1
.\run.ps1

把 v1.0.0 机器上的 kb_store（或配置指向的数据目录） 与 配置文件 拷到 v1.1.0 包对应位置（建议 conf/config.json），再启动。

5. 调用方改造清单（Breaking）

5.1 路径加前缀

v1.0.0

v1.1.0

GET/POST /query

GET/POST /api/query

/kb/documents、/kb/file…

/api/kb/...

/stats、/session、/history…

/api/stats、/api/session、/api/history…

/model/...、/mcp/...

/api/model/...、/api/mcp/...

SSE 流式查询同样走 /api/query?...（或 POST），注意反代对 SSE 的缓冲关闭。

5.2 响应包装

v1.1.0 成功/失败多为统一包装（含 code / data / pageIndex 等）。若 v1.0.0 客户端按「裸 JSON 业务字段」解析，需改为读 data（或按现网实际响应调整）。以浏览器 Network 或 /api-docs 为准。

5.3 健康检查

  • 探活仍支持裸路径：GET /health

  • 亦支持：GET /api/health

6. 数据兼容

6.1 向量库 / 分片

  • 同一向量后端、同一 embedding 模型下，v1.0.0 的 kb_store 一般可被 v1.1.0 直接使用。

  • 若升级时更换了向量后端（例如 numpy → zvec），需 重建索引（控制台「分片重建」或对应 rebuild 接口）。

  • 已有 chunk 不会因升级自动重切；新导入默认按固定长度分片。

6.2 文档解析

  • 以文字层抽取为主。

  • 升级后请对关键文档做一次导入 / 问答抽样，确认解析结果符合预期。

7. 反向代理 / 服务注册注意

项

建议

静态资源

反代到后端即可；SPA 由后端 fallback index.html

API

转发 /api/；勿再只转发 v1.0.0 裸路径

SSE

关闭代理缓冲；拉长超时

Windows 服务

更新工作目录与启动命令为 python -m src.main，保证能读到 conf/ 与 frontend/dist

环境变量

发行包建议设置 KB_PROJECT_ROOT

8. 升级后验收清单

  • v1.1.0 服务启动无报错；日志中能看到托管 frontend/dist

  • 打开 http://127.0.0.1:5000/ 为 Vue 控制台（非 v1.0.0 的 web 台）

  • /retrieval-qa 可提问；SSE 正常

  • /kb/management 能看到升级前文档列表（证明 kb_store 路径正确）

  • /api/stats 或控制台统计有数据

  • /api-docs 可打开

  • 旧客户端已改为 /api/...，或已下线

  • deep_think 默认关闭；显式打开才有思考过程

9. 回滚到 v1.0.0

  1. 停掉 v1.1.0 服务。

  2. 恢复备份的配置与 kb_store。

  3. 切回 v1.0.0 安装目录 / v1.0.0 tag / 旧发行包。

  4. 若曾改库表结构，按当时迁移脚本的反向说明处理（多数升级不强制改向量文件格式）。

过渡期可在 v1.1.0 上临时设 KB_SERVE_LEGACY_WEB=1 对照旧 UI，但 API 前缀仍以 v1.1.0 为准——旧前端若仍打裸路径会失败，需同步改调用或继续跑 v1.0.0 进程（双进程并行时注意端口与数据目录锁）。

10. 常见问题

Q: 打开网站白屏 / 404？
A: 未构建或未带上 v1.1.0 的 frontend/dist。执行 cd frontend && npm run build，确认存在 frontend/dist/index.html。

Q: 接口全部 404？
A: 调用方仍在使用 v1.0.0 裸路径，未加 /api。用浏览器访问 /api/stats 验证。

Q: 知识库是空的？
A: conf/config.json 里 storage 路径未指向 v1.0.0 数据目录；或工作目录变化导致相对路径漂移。改用绝对路径或设 KB_PROJECT_ROOT。

Q: build.ps1 一运行就解析错误？
A: 文件须为 UTF-8 带 BOM；并确认使用的是 v1.1.0 脚本（不再拷贝 web/）。

关于维基框架

维基本地知识库 是一个本地优先的开源知识库系统，融合向量检索、重排与对话式问答，支持多种主流大模型 API，具备高性能本地存储与灵活扩展能力，适合智能问答、知识管理、企业知识中台等场景。MulanPSL2 许可证，欢迎共建！

  • 官网：framewiki.com

Gitee：https://gitee.com/cdkjframework/knowledge-base

  • 📄 许可证：MulanPSL-2.0（木兰宽松许可证，第2版）

相关推荐