14 KiB
v3.2 / develop → v3.2-refact / develop-refact
本目录是重构版离线升级入口。旧部署材料已归档到 MaxKB v3.2 分支的 deploy_artifacts/。
升级保留原账号、知识库、文档、向量、应用、聊天记录和配置,不重新导入文档、不批量重建向量。数据库迁移在旧数据的独立副本上执行,原目录、原容器和原镜像均保留。需要维护窗口;这不是零停机切换。升级后回退到旧数据时间点,不会自动合并新版产生的数据。
1. 部署结构与兼容范围
| 项目 | 原版 | 重构版 |
|---|---|---|
| 应用 | MaxKB v3.2 |
MaxKB v3.2-refact |
| 解析 | markitdown develop,包含旧工作台 |
develop-refact,纯官方 MinerU 2.7.1 源码,仅解析 API |
| 导图界面 | mindmap-web 独立页面 |
MaxKB /admin/mindmap,需要登录和授权 |
| 旧入口 | 8989 /admin/、/chat/、/mindmap/;9898 |
保留原发布 IP/端口,导图入口跳转到新工作台 |
| 数据库/Redis | airag 容器内置 PostgreSQL 17 / Redis |
同一基础镜像系列,沿用原环境和持久化数据副本 |
| 异步任务 | MaxKB 自带消费者 | 自带消费者 + 同版本独立 Hub worker;Hub worker 与 airag 共用网络命名空间及数据目录 |
| NVIDIA | CUDA 镜像 | unis-mineru:版本-cuda,Docker GPU device request |
| 天数 MR100 | CoreX 镜像 | unis-mineru:版本-corex,CoreX 4.4.0 / 厂商 Torch / vLLM 0.11.2,保留厂商二进制版本 |
脚本自动支持原四容器 airag、mineru-api、mindmap-web、unis-gateway,且 /opt/maxkb、/models 是 bind mount、PostgreSQL 17 与 Redis 内置的部署。外置数据库、命名卷数据库、额外挂载或定制配置模式会停止自动升级,按文末流程处理。
升级后的运行拓扑仍是 MaxKB 内置 PG/Redis:airag 的 /usr/bin/start-all.sh 启动容器内部 127.0.0.1:5432 和 127.0.0.1:6379,持久化目录分别为 /opt/maxkb/data/postgresql/pgdata、/opt/maxkb/data/redis。Compose 不创建独立 PG/Redis 服务,也不把 ares-pg、ares-redis 当作新版运行依赖。--online-db-container ares-pg 只用于开发环境的在线备份来源。Hub worker 共用 airag 的网络命名空间,因此它的 localhost 同样指向这两个内置服务。
启动后脚本还会用 Django 的实际数据库连接和实际缓存客户端检查服务地址、服务端数据目录及 Redis PING,结果写入私有发布目录的 internal-services.json。连接到外部服务或持久化路径错误会使此次发布验收失败。可在容器内单独复核:docker exec airag python /usr/local/bin/unis-check-internal-services.py,该检查不修改业务记录、不输出密码。
大模型服务仍通过平台已有模型接口使用;此包不安装或替换 Ollama/vLLM 大模型服务。GPU 配置针对 MinerU 解析容器,MaxKB 的嵌入模型与原包保持一致。CUDA 驱动须与选定 vLLM 基础镜像兼容;MR100 需要可用的 CoreX 驱动。两类卡均须在目标机器实测,不能把 Dockerfile 存在视为硬件验收通过。
2. 构建离线包
在 Linux 联网构建机准备两个相邻仓库 maxkb/、markitdown/,切到对应重构分支。先将本次功能所需源码及迁移纳入 Git;构建脚本拒绝脏工作区,避免提交分支与镜像内容不一致。不要将临时输出、凭据、虚拟环境或模型提交到仓库。
cd maxkb
VERSION=refact-20261106-1 GPU_FLAVOR=cuda bash deploy_artifacts/build-release.sh
# MR100 单独构建,不混用 CUDA 包:
VERSION=refact-20261106-1 GPU_FLAVOR=corex bash deploy_artifacts/build-release.sh
构建脚本重新构建 /admin/ 和 /chat/,忽略本机 dist,将产物同时写入镜像的 ui/dist 与 apps/static。后端保持 PostgreSQL 17.6 基础镜像,不跨主版本升级数据库。解析服务恢复官方 2.7.1,不加六级标题补丁;CoreX/CUDA 恢复原打包基础镜像及依赖安装顺序,将 MinerU 固定为 ==2.7.1 并校验全部源码和安装版本。CoreX 保留原 --no-deps 安装方式。其余浮动依赖仍可能变化,不构成 MR100 兼容保证。入口脚本使用 Bash,支持 pipefail。
每类包位于 deploy_artifacts/releases/版本-卡型/,包含 images.tar、upgrade.py、本说明、源码提交号及 SHA256。镜像使用版本标签,升级时再固定为本机 image ID;不覆盖旧 latest。模型权重单独复用,不进镜像包。包不携带目标服务器的凭据。
cd /path/to/offline-package
sha256sum -c SHA256SUMS.txt
sudo docker load -i images.tar
3. 检查旧部署
部署主机需要 Python 3.10+、Docker Compose v2(支持 up --wait)、GNU tar、足够磁盘空间及 root/Docker 权限。推荐统一通过 sudo python3 upgrade.py 运行。脚本不改源码测试服务,也不占用 8080/3000/8100;公开端口继承旧网关和独立导图端口。
sudo python3 upgrade.py inspect
inspect 不启动容器、不连数据库、不输出环境凭据。核对目录、镜像 ID、四个容器状态。若原容器在运行,先在维护窗口停止这四个容器,等异步任务完成;不要停止源码测试服务或共享数据库/Redis。
sudo docker stop --time 330 unis-gateway mindmap-web mineru-api airag
2026-11-06 对 52.118 的核查:四个旧业务容器已停止;原数据 /home/tlw/unis/maxkb,模型 /home/tlw/unis/mineru-models;源码测试服务继续占用 8080/3000/8100。ares-pg 仍在运行,并直接挂载原数据下的 data/postgresql/pgdata,不能启动旧 airag 的内置 PostgreSQL,也不能将该目录直接 tar 当作一致性冷备。该机是 NVIDIA RTX 3070 Ti,不是 MR100。执行前以 inspect 为准;共享挂载会使默认冷备模式停止。
4. 备份并准备副本
新数据目录必须不存在,且与原数据、模型、发布备份目录互不包含。准备父目录,不递归修改任何业务目录权限。预留至少原数据大小两倍加余量的空间,用于冷备归档和运行副本。
sudo mkdir -p /home/tlw/unis/releases
sudo python3 upgrade.py prepare \
--release-dir /home/tlw/unis/releases/refact-20261106-1-cuda \
--data-dir /home/tlw/unis/maxkb-refact-20261106-1 \
--kb-image unis-kb:refact-20261106-1 \
--parser-image unis-mineru:refact-20261106-1-cuda \
--gateway-image unis-gateway:refact-20261106-1 \
--gpu cuda \
--online-db-container ares-pg
MR100 将 --gpu 改为 corex,解析镜像及发布目录后缀改为 corex。不要仅修改镜像标签而保留 NVIDIA 的运行配置。
上例为 52.118 的共享数据库情况,显式指定 --online-db-container ares-pg:只允许该 PostgreSQL 17 容器恰好挂载旧 PGDATA,使用 pg_basebackup(含 WAL)生成在线一致性物理备份,非数据库文件另存,随后恢复到独立目录。原容器和源码数据库继续运行,新 Docker 版从备份时点分离;之后两边新增的数据不会同步。备份不修改原数据库角色/认证设置,缺少复制权限会失败退出。
原生产部署的 PGDATA 若没有其它运行容器/进程使用,省略 --online-db-container,走停机冷备。正式切换有其它写入方时,须在维护窗口统一停止写入,再完成最终备份;在线复制不是双向数据同步或无损实时切换。
prepare 要求四个旧业务容器停止,检查其它数据使用方,校验 PG_VERSION=17。生成 data.tar(在线模式另有 database.tar)、SHA256、原容器配置、固定镜像 ID 的 compose.json,并提取到新数据目录;不会启动或迁移数据库。发现未明确指定的共享挂载会退出。
发布目录为 0700,状态/Compose 文件为 0600,包含原容器私有环境用于保留数据库密码等配置。不要上传 Git、在终端打印文件,或将发布目录当作普通安装包分发。新数据目录用于长期运行,升级后不要删除。模型按只读方式复用,MinerU 输出及导图图片均持久化到新数据目录。
5. 执行切换
sudo python3 upgrade.py apply \
--release-dir /home/tlw/unis/releases/refact-20261106-1-cuda
执行顺序:校验备份/Compose → 检查原容器身份及端口 → 用新解析镜像检查 Torch/vLLM 和 GPU 可见性(不加载模型)→ 将旧容器改名保留 → 启动新容器及隔离网络 → 仅在新副本上执行 Django 迁移 → 等待应用/解析 HTTP 就绪 → 检查迁移全部应用。
应用镜像内原 start-all.sh/main.py start 会执行全部前向迁移,不使用 --fake,也不把目标迁移固定在旧的 0007_ai_hub。本次版本需包含 knowledge 0004/0005/0006、users 0002、models_provider 0002、system_manage 0007/0008,Django 自动处理依赖。没有新增数据库迁移文件。
新 Hub worker 使用同一应用 image ID,只消费 Hub 数据库任务;不启动额外 Celery/Beat,不执行任务恢复或清理命令。原 MaxKB 自带消费者继续使用副本中的 Redis。模型目录不重新下载,不运行 down -v、全局 prune 或 chmod -R。
失败时停止新服务、保留副本和原容器;不会自动启动用户原先停掉的旧程序。诊断应在服务器本地查看 docker logs,其中可能包含私有配置,不要直接公开。
2026-11-06 已按用户要求将新解析包恢复到纯官方 2.7.1,启动校验同步为 2.7.1。原天数包 unis-mindmap-api-corex-latest.tar 仍保留,但它包含旧项目 /api/file_parse 接口,不能直接代替带发布标记、官方 /file_parse 接口的新解析包;旧包仅作回退材料。
6. 一次性配置与验收
旧导图的 MINDMAP_LLM_* 是独立服务环境,新版从平台模型管理读取;脚本保存旧容器配置,但不猜测模型供应商、不把旧明文 Key 写入新模型表、不覆盖已有平台模型或授权。升级后管理员需要完成:
- 在“解析服务”登记
http://mineru-api:8000,版本 2.7.1,协议 legacy,先用 pipeline;在工作台默认设置中选择该资源。已有外部 2.7.4 服务选项仍保留。 - 如平台已有对应大模型,直接选择;否则将旧导图模型通过平台模型管理导入,再设置工作台默认模型。旧环境中的 Key 仅在服务器本地核对输入。
- 将解析服务和模型授权给原使用人群;不扩大原知识库/应用权限。旧知识库、应用、模型原有记录由迁移保留。
旧浏览器本地的未保存编辑内容和导出文件不会自动转为新版“我的导图”;升级前下载需要保留的内容,升级后可重新导入 Markdown。不能将此类浏览器数据描述为数据库自动迁移。
完成以下真实检查后再开放使用:
- 8989
/admin/login、/admin/register及/chat/可打开;加载的 JS/CSS 来自新构建,没有 404。直接 8080 的源码测试页面不代表 Docker 版验收。 - 旧账号可登录;管理员及普通用户授权正确;原知识库/文档/应用/聊天记录可见;原问答实际向量检索可用。
/mindmap/和 9898 进入新版工作台;真实 PDF(含图片、标题、表格/公式)解析、总结、保存、重开和导出成功;Hub worker 确实完成任务。当前 MinerU 保持官方四级标题上限,不宣称保留五/六级。- 模型文件、导图图片和 MinerU 输出在重建容器后仍存在;源码测试服务和共享 Redis 未受影响。
- MR100 另在对应机器完成同一组验收;52.118 的 NVIDIA 结果不替代 MR100 验收。
“HTTP healthy / 迁移完成”仅是启动检查,不等于以上业务验收。
7. 回退
# 保持与本次升级前相同的停机状态,只恢复旧容器名称:
sudo python3 upgrade.py rollback \
--release-dir /home/tlw/unis/releases/refact-20261106-1-cuda
# 如确需恢复旧版运行,在 rollback 同一次调用增加 --start-old。
回退仅停止本发布项目的新容器并改名保留,恢复原容器名称;不会删除容器、数据、镜像、网络或模型。原目录没有被本脚本迁移,无需对新库做反向迁移。共享 PGDATA 仍被使用时,--start-old 会拒绝启动,以免两个 PostgreSQL 同时打开同一目录;恢复旧程序运行也必须使用另一个一致性数据副本。新版开放写入后,回退旧库不包含新增数据,需先停止写入并决定是否导出/补录;保留新副本用于恢复。
8. 非标准部署 / 源码测试服务
52.118 的源码测试目录分支名仍显示旧分支,但已含大量增量修改。不要在远程直接 git checkout、reset --hard、覆盖配置或切换数据库;该环境和旧 Docker 数据各自核验,各自发布。
外部 DB/Redis 或其它挂载方式:先确认数据库所有写入方、队列消费者及源码服务是否共用它们。在隔离数据库恢复 pg_dump -Fc 备份并复制持久化文件;为新版分配独立 Redis 实例/逻辑库及 Celery 队列,Web/Hub worker 指向同一新库。明确保留原 SECRET_KEY、加密密钥和模型配置。使用候选镜像运行 python apps/manage.py migrate --plan 审核,再执行完整 migrate --noinput;更新 apps/static/admin 和 chat 构建后启动同版本 Web/worker,完成上节验收。禁止在共享原库直接试迁移,也不调用本机 main.py dev web。
9. 脚本验证
python3 -m unittest discover -s deploy_artifacts/tests -v
bash -n deploy_artifacts/build-release.sh
测试覆盖 Compose 凭据原样传递、GPU 隔离配置、内部数据库/worker 网络、原数据保护和失败回退身份检查。它们不启动 Docker 或访问共享服务。实际镜像构建、数据库演练和两类 GPU 业务验收仍需分别记录。