|
|
项
说明
文档日期
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 静态台（一般不需要）：
启用后经 /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
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版）
原文链接 |
|
发表于 2026-8-27 10:00:38
