WeKnora 升级指南更新到最新版前必须搞清的 5 个问题【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora如果你正在做 WeKnora 升级大概率卡在同一个地方不确定要不要手动改数据库、怎么拉新镜像、升完之后哪里坏了。这篇文章用 5 个最常被问到的问题把 WeKnora 版本迁移拆成备份 → 拉镜像 → 验证 → 排坑四步从老版本平滑升到最新版全程不需要你手写 SQL。一、升级前需要手动改数据库结构吗不需要这是新手最容易多此一举的地方。WeKnora 的数据库结构变更全部走迁移文件migrations/versioned/ 下已有 180 多个版本化迁移而服务在启动时会自动执行所有未跑的迁移——你只管把新版本的镜像跑起来表结构会自己跟上。只有两种情况需要手动碰迁移你是源码编译部署不是 docker compose启动前想确认结构就绪可以显式跑一次迁移脚本./scripts/migrate.sh up它的作用是把数据库结构升到最新版跑完会看到Migration command completed successfully。数据库连接信息通过DB_HOST、DB_PORT、DB_USER、DB_PASSWORD、DB_NAME等环境变量传入默认值在脚本里都有。迁移卡在中间状态需要回滚一步脚本支持down回退一个版本和force强制修正版本记录具体用法自己执行./scripts/migrate.sh -h即可看到。二、WeKnora 升级前应该备份什么原则很简单数据库、文件、配置三样都要。缺一样升级出问题就回不去。备份对象位置备份方式业务数据库PostgreSQLcompose 部署默认 ParadeDB 实例pg_dump导出 SQL上传的原始文件挂载卷/data/files整目录拷贝运行时配置config/config.yaml及环境变量拷贝文件数据库导出的命令是这样的执行完会在当前目录生成一个.sql文件pg_dump -U ${DB_USER} -h ${DB_HOST} -p ${DB_PORT} ${DB_NAME} backup_$(date %F).sql文件目录直接tar一份即可。配置文件虽小但里面有你调过的切分参数、提示词模板 ID 等别漏。备份时顺便看一眼当前生效的配置项升级后可以对照确认没被默认值覆盖参考 config/config.yaml。三、为什么执行了升级命令版本却没变这是 docker 部署最经典的坑docker compose up -d只负责用本地已有镜像起容器不会去仓库拉新镜像。你升级前如果只有up没有pull容器里跑的还是旧代码界面上版本号纹丝不动。正确的升级命令是两条连跑先拉再启docker compose pull docker compose up -d第一条把 docker-compose.yml 里声明的各服务镜像UI、App、docreader 等统一走WEKNORA_VERSION变量拉到最新第二条用新镜像重建容器启动时自动跑完前面说的数据库迁移。pull和up两条命令执行完docker compose ps里的各容器应显示 Up 且镜像 ID 已更新。顺带提醒如果你启用了full、neo4j、minio等 profile记得在两条命令里都带上--profile xxx不然对应组件会停留在旧版本。官方说明见 README_CN.md 的部署章节。四、升级后必做的 5 项检查镜像起来不等于没问题花 5 分钟过一遍下面的清单确认这次 WeKnora 版本更新没有留下暗伤容器状态docker compose ps全部 Up没有反复 Restarting登录与鉴权用原有账号登录 Web 界面能进首页且不报 401/500知识库列表打开任意知识库文档列表、标签、文件夹树都能正常渲染文档处理随便上传一篇 PDF走完解析 → 切块 → 向量化流程状态变成已完成检索问答发一个文档里肯定能答出的问题答案带引用且检索结果非空。第 4、5 步覆盖了处理管线和检索链路是升级中最容易出问题的两段。文档列表页应类似这样能看到处理进度与状态五、升级踩坑了怎么办按发生频率排一下版本没变、界面还是旧的→ 99% 是漏了pull回到第三节两条命令连跑然后docker compose up -d --force-recreate强制重建。启动报迁移错误、服务起不来→ 先看日志里的迁移版本号docker compose logs app确认是不是卡在某个中间状态能恢复就用./scripts/migrate.sh down回退一步再升级实在不行从第二节的备份还原数据库。文档在、但检索不到内容→ 向量数据没跟上新结构对受影响的文档执行重新处理即可不需要清空重建整个知识库。界面样式错乱、按钮失效→ 浏览器强刷一次CtrlShiftR旧版前端静态资源被缓存住了这是假故障。不确定哪里不对→ 翻 docs/QA.md里面有按模块整理的常见问题仍解决不了再走项目的 Issue 渠道。六、升到最新版后你会拿到什么最新版不只是修 bug几个变化直接影响日常使用知识库文件夹树上传的文件夹结构会保留成侧边目录树文档可以拖拽重新归档切块直接可编辑检索用的 chunk 能在界面里改每次改动都存版本快照支持对比和一键回滚Wiki 修订历史Wiki 页面每次覆盖前都留底历史版本可逐行 diff、手动回退可直接加载的文件 URL聊天回答和引用支持返回可直连的 http(s) 地址第三方集成少一次鉴权调用。左侧知识库列表的入口和整体界面如下升级后可以在这里逐库确认新结构生效更多功能细节和截图可以看仓库里新增的 website-docs/ 官方文档站点。下一步建议备份 →pull up -d→ 跑完第四节清单三个动作做完即可收尾。如果你们的生产环境启用了 neo4j 或 minio profile别忘了把对应 profile 一起升级再观察一两天检索指标即可。【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 WeKnora 升级指南：更新到最新版前必须搞清的 5 个问题
WeKnora 升级指南更新到最新版前必须搞清的 5 个问题【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora如果你正在做 WeKnora 升级大概率卡在同一个地方不确定要不要手动改数据库、怎么拉新镜像、升完之后哪里坏了。这篇文章用 5 个最常被问到的问题把 WeKnora 版本迁移拆成备份 → 拉镜像 → 验证 → 排坑四步从老版本平滑升到最新版全程不需要你手写 SQL。一、升级前需要手动改数据库结构吗不需要这是新手最容易多此一举的地方。WeKnora 的数据库结构变更全部走迁移文件migrations/versioned/ 下已有 180 多个版本化迁移而服务在启动时会自动执行所有未跑的迁移——你只管把新版本的镜像跑起来表结构会自己跟上。只有两种情况需要手动碰迁移你是源码编译部署不是 docker compose启动前想确认结构就绪可以显式跑一次迁移脚本./scripts/migrate.sh up它的作用是把数据库结构升到最新版跑完会看到Migration command completed successfully。数据库连接信息通过DB_HOST、DB_PORT、DB_USER、DB_PASSWORD、DB_NAME等环境变量传入默认值在脚本里都有。迁移卡在中间状态需要回滚一步脚本支持down回退一个版本和force强制修正版本记录具体用法自己执行./scripts/migrate.sh -h即可看到。二、WeKnora 升级前应该备份什么原则很简单数据库、文件、配置三样都要。缺一样升级出问题就回不去。备份对象位置备份方式业务数据库PostgreSQLcompose 部署默认 ParadeDB 实例pg_dump导出 SQL上传的原始文件挂载卷/data/files整目录拷贝运行时配置config/config.yaml及环境变量拷贝文件数据库导出的命令是这样的执行完会在当前目录生成一个.sql文件pg_dump -U ${DB_USER} -h ${DB_HOST} -p ${DB_PORT} ${DB_NAME} backup_$(date %F).sql文件目录直接tar一份即可。配置文件虽小但里面有你调过的切分参数、提示词模板 ID 等别漏。备份时顺便看一眼当前生效的配置项升级后可以对照确认没被默认值覆盖参考 config/config.yaml。三、为什么执行了升级命令版本却没变这是 docker 部署最经典的坑docker compose up -d只负责用本地已有镜像起容器不会去仓库拉新镜像。你升级前如果只有up没有pull容器里跑的还是旧代码界面上版本号纹丝不动。正确的升级命令是两条连跑先拉再启docker compose pull docker compose up -d第一条把 docker-compose.yml 里声明的各服务镜像UI、App、docreader 等统一走WEKNORA_VERSION变量拉到最新第二条用新镜像重建容器启动时自动跑完前面说的数据库迁移。pull和up两条命令执行完docker compose ps里的各容器应显示 Up 且镜像 ID 已更新。顺带提醒如果你启用了full、neo4j、minio等 profile记得在两条命令里都带上--profile xxx不然对应组件会停留在旧版本。官方说明见 README_CN.md 的部署章节。四、升级后必做的 5 项检查镜像起来不等于没问题花 5 分钟过一遍下面的清单确认这次 WeKnora 版本更新没有留下暗伤容器状态docker compose ps全部 Up没有反复 Restarting登录与鉴权用原有账号登录 Web 界面能进首页且不报 401/500知识库列表打开任意知识库文档列表、标签、文件夹树都能正常渲染文档处理随便上传一篇 PDF走完解析 → 切块 → 向量化流程状态变成已完成检索问答发一个文档里肯定能答出的问题答案带引用且检索结果非空。第 4、5 步覆盖了处理管线和检索链路是升级中最容易出问题的两段。文档列表页应类似这样能看到处理进度与状态五、升级踩坑了怎么办按发生频率排一下版本没变、界面还是旧的→ 99% 是漏了pull回到第三节两条命令连跑然后docker compose up -d --force-recreate强制重建。启动报迁移错误、服务起不来→ 先看日志里的迁移版本号docker compose logs app确认是不是卡在某个中间状态能恢复就用./scripts/migrate.sh down回退一步再升级实在不行从第二节的备份还原数据库。文档在、但检索不到内容→ 向量数据没跟上新结构对受影响的文档执行重新处理即可不需要清空重建整个知识库。界面样式错乱、按钮失效→ 浏览器强刷一次CtrlShiftR旧版前端静态资源被缓存住了这是假故障。不确定哪里不对→ 翻 docs/QA.md里面有按模块整理的常见问题仍解决不了再走项目的 Issue 渠道。六、升到最新版后你会拿到什么最新版不只是修 bug几个变化直接影响日常使用知识库文件夹树上传的文件夹结构会保留成侧边目录树文档可以拖拽重新归档切块直接可编辑检索用的 chunk 能在界面里改每次改动都存版本快照支持对比和一键回滚Wiki 修订历史Wiki 页面每次覆盖前都留底历史版本可逐行 diff、手动回退可直接加载的文件 URL聊天回答和引用支持返回可直连的 http(s) 地址第三方集成少一次鉴权调用。左侧知识库列表的入口和整体界面如下升级后可以在这里逐库确认新结构生效更多功能细节和截图可以看仓库里新增的 website-docs/ 官方文档站点。下一步建议备份 →pull up -d→ 跑完第四节清单三个动作做完即可收尾。如果你们的生产环境启用了 neo4j 或 minio profile别忘了把对应 profile 一起升级再观察一两天检索指标即可。【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考