# 升级准备与验证记录 · 2026-11-06 ## 已完成 - 原工作区 `deploy_artifacts/` 归档到 MaxKB `v3.2`,本地提交 `e34d9011e`;未加入镜像、模型或私有配置。 - 补齐重构版已引用但未跟踪的功能源码、knowledge 0006 迁移及回归脚本;整理前端 pnpm 11.23.0 锁文件。临时构建、缓存不纳入发布。 - 新离线构建入口重新编译 admin/chat,将静态文件写入实际运行路径;CUDA/CoreX 解析镜像分开标记,入口使用 Bash,保留厂商二进制依赖约束。 - 升级使用数据副本和独立网络,保留旧容器/镜像,提供冷备及共享 PostgreSQL 在线一致性备份两种模式。 ## 真实环境发现 52.118 的源码目录仍显示 `v3.2` / `develop`,但有增量功能修改,不能按分支名认定实际内容。源码服务未切换分支或覆盖文件。 原 `airag`、`mineru-api`、`mindmap-web`、`unis-gateway` 均已停止;**运行中的 `ares-pg` 使用 `/home/tlw/unis/maxkb/data/postgresql/pgdata`**。因此不能启动原 airag 的内置 PostgreSQL,默认冷备升级会拒绝继续。在线模式从 `ares-pg` 取得 `pg_basebackup`,恢复到独立目录,原数据库保持运行。 该机为 NVIDIA RTX 3070 Ti 8 GB;没有 MR100 实机验收条件。 ## 验证结果 | 检查 | 结果及边界 | |---|---| | 升级脚本测试 | 追加内置服务验证后,本机 Windows 19 项、52.118 Linux 19 项均通过;模拟 Docker 调用不等于完整发布测试 | | Compose 配置 | CUDA / CoreX 均由 52.118 的 Docker Compose v5.5.1 校验通过,未启动对应解析业务镜像 | | 网关 | 使用已有 Nginx 镜像对新模板执行 `nginx -t` 通过,未替换在线网关 | | 前端 | 本机 admin/chat 的 Vite 生产构建通过;存在既有 eval 和大 chunk 警告;未做完整 TypeScript 检查或新 Docker 页面验收 | | 知识版本 | 本机 SQLite 回归 35 项,2 项跳过;未访问共享数据库/Redis | | 组件/总结/工作台/上下文 | Linux 候选源码中 SQLite 与模拟接口回归 120 项通过,未调用真实模型或外部 MCP | | Python | 应用源码和升级脚本编译检查通过 | | Shell | 两仓打包脚本 Bash 语法检查通过 | ## 在线备份与副本迁移检查 有效演练目录:`/home/tlw/unis/upgrade-rehearsal-20261106-144635`。该目录中的 `database.tar` 来自在线 `pg_basebackup`(含 WAL),非数据库文件另存。早期直接 tar 的副本不作为一致性备份或验收依据。 在候选源码、现有测试机 Python 依赖和独立临时 PostgreSQL 中执行了完整 `migrate --plan`、`migrate --noinput`、`migrate --check`。未启动 Web、Redis 或任务消费者。检查前后: | 表 | 检查前 | 检查后 | |---|---:|---:| | user | 13 | 13 | | knowledge | 8 | 8 | | document | 8 | 8 | | paragraph | 738 | 738 | | embedding | 1021 | 1021 | | application | 9 | 9 | | model | 7 | 7 | **该共享库已经应用当前全部迁移,本轮新增执行的迁移数为 0。** 这证明此备份可独立启动、当前候选可连接并检查已有结构,记录数保留;不能据此声称纯旧版 `v3.2` 库首次前向迁移已经验证。临时数据库已停止,四个原业务容器保持停止,`ares-pg` 和源码测试服务继续运行。 ## 内置 PG/Redis 追加验证 用户确认 `ares-pg` 是开发阶段单独挂载旧 PGDATA 的安排;正式 Docker 拓扑仍使用 MaxKB 内置 PostgreSQL 和 Redis。 验证目录:`/home/tlw/unis/internal-services-check-20261106-151833`。从上节的一致性备份恢复到另一个新目录,以原 MaxKB 应用镜像启动自带 `start-postgres.sh`、`start-redis.sh`,容器 `network=none`、无端口映射,不启动 Web/Celery/Hub worker。使用 Django 实际连接配置执行只读查询及缓存 PING: | 服务 | 实际地址 | 实际版本 | 服务端数据目录 | |---|---|---|---| | 内置 PostgreSQL | 127.0.0.1:5432 | 17.6 | /opt/maxkb/data/postgresql/pgdata | | 内置 Redis | 127.0.0.1:6379 | 8.0.2 | /opt/maxkb/data/redis | 两者均通过。因容器禁用外部网络,此结果不依赖开发用 `ares-pg` / `ares-redis`。检查后临时容器停止,`ares-pg` 的容器 ID、启动时间及运行状态未变,原 airag 仍停止。 此测试覆盖原应用镜像自带的 PG/Redis 启动链和新检查程序;尚未构建候选完整业务镜像。候选 Compose 已明确使用内置地址、标准端口和 `start-all.sh`,且发布流程新增实际连接检查,不能把本次底层检查写成新版整包已验收。 ## 发布前仍需完成 ### MinerU 基线更新(同日追加) 用户明确要求将内核恢复为官方 2.7.1。现已恢复全部 187 个官方文件,撤去三处六级标题补丁;标题输出保持官方四级上限。旧项目 Word 转换、进度、智能整理、静态工作台、VLM 参数过滤及续表定制均不带入内核。 CoreX/CUDA 构建恢复 `develop` 原基础镜像和依赖安装顺序,仅将原 `mineru[core]>=2.7.4` 改为 `==2.7.1`、增加基线完整性校验;构建脚本去掉已退役的 Web 构建并保留旧 API 标签及新版升级标记。必要的环境变量转发位于启动包装器,内核不加补丁。构建上下文排除开发虚拟环境、模型、日志和私有配置。 检查结果:本机 6 项基线/启动测试、5 项 MaxKB 原生解析及版本目录测试、19 项升级测试通过;远端隔离候选及新解释器环境通过 6 项基线、3 项官方标题、2 项模拟推理接口测试。前端 `/admin/` 生产构建通过,本地和 8080 登录/注册页实际检查通过。 源码测试服务已发布到 52.118:运行时 `version=2.7.1`、`installed_version=2.7.1`、官方文件 187、内核定制 0,`/file_parse` 路由存在。发布目录及回退材料:`/home/tlw/unis/UnisMindMap/logs/releases/mineru-271-20261106-161614-publish3`。新解释器复用原环境的依赖路径,仅安装已核对 SHA256 的官方 2.7.1 wheel;原解释器与原源码备份保留。此前一次准备失败、一次健康检查失败均未改共享数据库,后者已自动恢复旧服务;修复依赖路径后本次发布成功。 这次同步包括 MaxKB 的 2.7.1 新资源选项、版本目录和 `apps/static/admin` 构建,已有显式 2.7.4 外部资源选项保留。没有执行数据库迁移、修改模型或启动新消费者。没有构建候选 Docker 镜像,没有执行真实 GPU 文档推理,尤其不代表 MR100 实卡兼容验收通过。 最终启动包装器还隔离了 API 参数与引擎参数:官方 2.7.1 CLI 会将额外参数全部写入引擎配置,包装器改为直接配置官方 ASGI app,避免 `mineru_api_max_concurrent_requests` 误传给 vLLM。该处理仅位于 `scripts/run_parser.py`,`mineru/` 内核仍为原版 187 个文件,未加运行时引擎猴子补丁。此包装器已通过上述 11 项远端测试并完成解析服务健康检查;仍未执行 GPU 推理。 以下待办仍然适用;解析内核目标现为 2.7.1。 1. 在构建机实际构建两个 GPU 镜像包,检查依赖解析与模型路径;本轮未构建或导入候选业务镜像。 2. 使用尚未应用重构迁移的独立旧版数据库备份执行首次升级,并进行登录、权限、问答、文件、向量和聊天记录验收。 3. 完成导图解析资源与平台模型的映射及授权,处理旧浏览器未保存内容。此部分不是旧 `MINDMAP_LLM_*` 环境变量自动迁移。 4. 在候选 Docker 8989/9898 入口检查 admin/chat、登录/注册及导图完整流程;NVIDIA、MR100 分别做真实模型/PDF 验收。 5. 在开放写入前明确最终数据时间点与回退边界;共享源码环境与新 Docker 数据副本后续不会自动同步。 升级命令及限制见 [README_UPGRADE.md](README_UPGRADE.md)。本记录不等于上线完成报告。