0. 先看结论

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

1. v1.0.0 与 v1.1.0 对照

1.1 目录与入口

1.2 URL / 页面

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

KB_SERVE_LEGACY_WEB=1

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

1.3 HTTP API

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

1.4 行为差异（容易踩坑）

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 建议核对的字段

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

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

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 路径加前缀

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. 反向代理 / 服务注册注意

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版）