12 KiB
v3.2 / develop 升级到 v3.2-refact / develop-mineru-2.7.6
本文保留 2026-11-10 旧单文件离线包的详细升级记录。新版分镜像包的构建与交付请使用
README_发布维护.md,客户操作请使用customer/README_客户部署.md;本文的images.tar命令不适用于分镜像包。
本文用于准备离线镜像包,并在维护窗口内将旧四容器部署升级到 MaxKB 重构版和 MinerU 2.7.6。升级脚本在独立数据副本上执行数据库迁移,保留旧容器、旧镜像和原数据;升级后新旧数据不再同步,回退不会带回新版产生的数据。脚本和本说明尚未完成本组合的真实镜像构建与升级演练,正式使用前必须在隔离环境完成演练和验收。
1. 版本与拓扑
| 内容 | 升级前 | 升级后 |
|---|---|---|
| 应用源码 | MaxKB v3.2 |
v3.2-refact |
| 解析源码 | markitdown develop |
develop-mineru-2.7.6,MinerU 2.7.6 |
| 导图页面 | 独立 mindmap-web |
MaxKB 工作台,旧 /mindmap/ 和 9898 重定向至工作台 |
| 容器 | airag、mineru-api、mindmap-web、unis-gateway |
airag、mineru-api、unis-hub-worker、unis-gateway |
| 数据 | /opt/maxkb bind mount,内部 PostgreSQL 17 / Redis |
独立副本,仍使用容器内部 PostgreSQL / Redis;worker 与应用共享网络及副本 |
此升级包不包含独立导图 Web 镜像、大模型服务或模型权重。独立导图页面由 MaxKB 工作台替代;原独立页面浏览器中未保存的内容不自动迁移,应事先导出。MinerU 2.7.6 支持 V2 协议、/file_parse 和 /api/file_parse;需实际测试所选文档及模型权重。
CUDA 打包针对目标分支中的依赖冲突应用镜像内修正:gradio==5.49.1 要求 Pydantic <2.12,而该分支要求 >=2.12,因此构建时将 Gradio 调整为 5.50.0(支持 Pydantic 至 2.12.3)。CUDA 基础镜像的 PyGObject 缺少 pycairo,构建时补装并执行 pip check。这些调整不修改源码仓库,具体构建文件随包及校验值一起保留;仍需完成解析与页面业务验收。
知识库镜像将 Pydantic 固定为 2.12.3,并检查 MCP 依赖所用的接口;较新的 Pydantic 版本移除了该接口,会阻止应用初始化。
本次只读核对 2026-11-09 测试机 10.100.52.118:四个旧容器运行中;airag 的 /opt/maxkb 挂载至 /home/tlw/unis/maxkb-fresh-init-20261109,PGDATA 位于其中;MinerU 模型挂载 /home/tlw/unis/mineru-models;GPU 为单张 NVIDIA RTX 3070 Ti,旧容器的 CUDA_VISIBLE_DEVICES=0。这些是检查时的状态,升级前以 inspect 和实际宿主机信息为准。源码测试服务与 Docker 应用是不同部署,不要覆盖其目录或共享数据库。
2. 构建前准备
在 Linux 构建机准备相邻的 maxkb/ 和 markitdown/ 仓库,分别检出目标分支,确认需要发布的改动均已提交、工作区干净。当前材料本身若尚未提交,也需先纳入要构建的 MaxKB 提交;脚本会拒绝脏工作区。构建不自动拉取分支,先按项目流程更新并核对提交号。不要将凭据、模型、虚拟环境、构建缓存或生产数据提交到 Git。
git -C maxkb status --short --branch
git -C maxkb rev-parse HEAD
git -C markitdown status --short --branch
git -C markitdown rev-parse HEAD
docker version
docker compose version
df -h
需要可联网访问基础镜像和依赖源、可执行 Docker build/save,以及足够的构建缓存、镜像和离线包空间。CUDA 构建引用 vllm/vllm-openai:v0.11.2;实际驱动、CUDA 和 GPU 兼容性需在目标机验证。此处的构建脚本不使用旧 installer/Dockerfile 中可能复用已有前端 dist 的逻辑,而是重新编译 /admin/ 和 /chat/,写入镜像的 ui/dist 和 apps/static。
3. 构建 NVIDIA 离线包
cd /path/to/maxkb
VERSION=refact-276-20261109-1 GPU_FLAVOR=cuda bash deploy_artifacts/build-release.sh
VERSION 必须为每次发布设置新值,输出目录不能已存在。默认输出 maxkb/deploy_artifacts/releases/refact-276-20261109-1-cuda/:
images.tar # KB、gateway、MinerU CUDA 三个带版本的镜像
upgrade.py # 检查、备份、副本升级与回退
seed_local_v2_parsers.py # 可选:登记本地三种 V2 解析服务及角色授权
README_UPGRADE_276.md
SOURCES.txt # 两个仓库的提交号、版本、GPU 类型
SHA256SUMS.txt
镜像分别为 unis-kb:版本、unis-gateway:版本、unis-mineru:版本-cuda。解析镜像使用目标分支源码和本发布目录中调整过依赖安装的 CUDA Dockerfile,并附加发布标签;升级脚本校验 GPU 类型、组件标签及 MinerU 2.7.6。CoreX 可用 GPU_FLAVOR=corex 单独构建,不能用 CUDA 验收代替天数卡验收;当前 52.118 应使用 CUDA 包。构建、导出和依赖下载可能耗时较长,失败后不要将不完整目录作为安装包。
NVIDIA 升级配置显式使用 nvidia runtime 和 GPU 设备请求;目标机须已配置对应 runtime。52.118 已实测只有显式指定该 runtime 时 GPU 预检成功。
打包后将整个目录复制到目标机的新目录,不要覆盖旧 deploy_artifacts、旧镜像文件或旧配置。目标机只需导入三张镜像,docker load 不会启动容器:
cd /path/to/offline-package
sha256sum -c SHA256SUMS.txt
cat SOURCES.txt
sudo docker load -i images.tar
4. 升级前检查与备份准备
要求 Linux、Python 3.10+、GNU tar、Docker Compose v2(支持 up --wait)及 root/Docker 权限。确认维护窗口、暂停写入并等待任务结束;保留旧发布包、原容器、旧镜像和原数据,不运行 down -v、全局 prune 或递归 chmod。需要足够空间保存原数据归档及独立运行副本。模型目录保留不覆盖,先核实其中 Pipeline / VLM 权重与 MinerU 2.7.6 兼容;目录存在不等于模型可加载。若需更新权重,应在独立目录准备并实测,不要覆盖旧权重后再声称可回退。
当前自动脚本只复用旧 mineru-api 的模型挂载,不提供另选模型目录的参数。如果旧权重不兼容,先停止自动切换并调整、验证部署方案,不能直接执行以下 apply。
sudo python3 upgrade.py inspect
sudo docker ps -a
df -h
inspect 只读校验旧容器、挂载、PostgreSQL 17 和模型目录;如果存在外部 DB/Redis、嵌套数据挂载、额外 PostgreSQL 挂载或其他不支持的拓扑,停止自动流程,先制定独立备份与隔离迁移方案。它会检查其他运行容器和原生 PostgreSQL 是否使用原数据,但不能替代对所有外部写入方、挂载和任务的人工核验。测试机 /var/lib/postgresql/data 匿名卷不覆盖实际位于 /opt/maxkb 的 PGDATA;以检查输出及实际配置为准。
在维护窗口,确认旧容器不再写入后:
sudo docker stop --time 330 unis-gateway mindmap-web mineru-api airag
sudo mkdir -p /home/tlw/unis/releases
sudo python3 upgrade.py prepare \
--release-dir /home/tlw/unis/releases/refact-276-20261109-1-cuda \
--data-dir /home/tlw/unis/maxkb-refact-276-20261109-1 \
--kb-image unis-kb:refact-276-20261109-1 \
--parser-image unis-mineru:refact-276-20261109-1-cuda \
--gateway-image unis-gateway:refact-276-20261109-1 \
--gpu cuda
发布目录和副本目录必须不存在、互不包含,且不能与原数据或模型目录重叠;父目录须预先存在。prepare 不启动新容器:它生成私有状态、原容器配置、校验和、数据归档、独立数据副本和固定镜像 ID 的 Compose 配置。发布目录包含敏感环境配置,权限为 0700/0600,不要上传 Git、公开或作为普通安装包分发。
如果 inspect 显示原 PGDATA 正被其他容器使用,不能对运行中的 PGDATA 直接冷拷贝。仅在确认唯一共享写入方是使用同一 PGDATA 的 PostgreSQL 17 容器时,可经维护窗口评估 prepare 的 --online-db-container 容器名,由 pg_basebackup 生成一致性物理备份;仍需暂停所有业务写入以获得最终切换点。其他共享访问方式须先单独处理,不能强行跳过检查。
5. 切换与验证
sudo python3 upgrade.py apply \
--release-dir /home/tlw/unis/releases/refact-276-20261109-1-cuda
apply 核验快照、原容器身份和端口,先在候选 MinerU 镜像中检查版本、Torch/vLLM 和 GPU,再重命名保留旧容器并启动新容器。新 airag 的启动流程会对副本执行 Django 前向迁移;apply 检查迁移后执行 unify_platform_roles,在首次创建统一管理员角色时导入旧版 ADMIN 用户,并检查内置 PostgreSQL/Redis。已有统一管理员角色时不会重新导入,以免撤销后又被提权。不得将该操作指向共享原库。失败时新容器会被停止,原容器和副本保留;依据状态执行下节回退。不要将健康检查通过当成业务验收通过。
管理员登录后在“解析服务”配置 http://mineru-api:8000,选择 2.7.6(内部协议为 legacy)并测试,再按权限设置工作台默认解析服务和平台模型。旧独立服务的模型环境变量不会自动转换为平台模型,密钥仅在目标机安全配置。确认用户、知识库、文档、向量检索、应用和会话记录与升级前一致。
也可选择执行以下增量初始化脚本,先预览,再按需应用;升级和容器启动不会自动执行它:
sudo docker exec -i airag python - < seed_local_v2_parsers.py
sudo docker exec -i airag python - --apply < seed_local_v2_parsers.py
脚本检查本地解析服务的 /health 和 2.7.6 版本,登记“传统管道”“混合引擎”“VLM引擎”三种后端,并将各解析资源的查看和使用权限授权给内置管理员及普通用户角色。默认工作区为 default,默认地址为 http://mineru-api:8000;自定义地址可在 --endpoint 后传入。脚本不选择平台默认解析器,也不改变用户其他权限。重复执行不会重复创建;此前由脚本创建的旧名称会按固定资源 ID 原位更新,保留授权。发现同名资源、角色配置或已有授权与预期冲突时,会停止并回滚本次改动。Hybrid 和 VLM 的模型加载、显存和实际解析能力需在目标设备单独验收;资源登记成功不代表 GPU 推理通过。
上线前至少检查:
sudo docker ps -a;查看容器运行与健康状态;从服务器检查 8989 登录页、注册页、/chat/,及 9898、/mindmap/是否进入新版工作台;浏览器确认静态资源没有 404。- 已有账号、权限、知识库问答和实际向量检索正常;业务模型和 Hub worker 可完成真实任务。
- 使用标识清晰的测试文档,分别验证 PDF、图片 OCR、Word、标题和表格、总结、保存重开、导出。实际效果、显存及 VLM 能力以目标机结果为准。
- 容器内检查 GPU 可见性与实际解析;重建候选容器后验证导图图片和数据持久化。检查源码测试服务未受到影响。
必要的故障日志在目标机本地查看,日志可能包含业务数据或凭据,不要直接公开。
6. 回退
先停止新版本业务写入并记录新版产生的数据。以下命令停止本发布的新容器、保留其数据和容器,并恢复旧容器名称;默认不启动旧容器:
sudo python3 upgrade.py rollback \
--release-dir /home/tlw/unis/releases/refact-276-20261109-1-cuda
如确认原 PGDATA 没有其他服务使用,且接受回到升级前数据时点,可在同一次调用中增加 --start-old。旧容器启动前仍须确认端口、原模型和其他服务的实际使用情况。回退不会自动合并新版数据;保留新副本,按业务需要另行导出或补录。若仅需恢复失败发布后的旧名称,使用不带 --start-old 的形式。
7. 已知验证边界
本目录的历史 VALIDATION_20261106.md 和 README_UPGRADE.md 针对旧的 2.7.1 组合,不代表此次 2.7.6 镜像已构建或演练。升级脚本单元测试与 Shell 语法检查不连接 Docker;真实镜像构建、旧版数据库首次前向迁移、模型权重兼容、GPU PDF/OCR 及登录后端到端验收均需单独记录。