UnisKB/deploy_artifacts/README_UPGRADE.md

154 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 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;构建脚本拒绝脏工作区,避免提交分支与镜像内容不一致。不要将临时输出、凭据、虚拟环境或模型提交到仓库。
```bash
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`。模型权重单独复用,不进镜像包。包不携带目标服务器的凭据。
```bash
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;公开端口继承旧网关和独立导图端口。
```bash
sudo python3 upgrade.py inspect
```
`inspect` 不启动容器、不连数据库、不输出环境凭据。核对目录、镜像 ID、四个容器状态。若原容器在运行,先在维护窗口停止这四个容器,等异步任务完成;不要停止源码测试服务或共享数据库/Redis。
```bash
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. 备份并准备副本
新数据目录必须不存在,且与原数据、模型、发布备份目录互不包含。准备父目录,不递归修改任何业务目录权限。预留至少原数据大小两倍加余量的空间,用于冷备归档和运行副本。
```bash
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. 执行切换
```bash
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 写入新模型表、不覆盖已有平台模型或授权**。升级后管理员需要完成:
1. 在“解析服务”登记 `http://mineru-api:8000`,版本 2.7.1,协议 legacy,先用 pipeline;在工作台默认设置中选择该资源。已有外部 2.7.4 服务选项仍保留。
2. 如平台已有对应大模型,直接选择;否则将旧导图模型通过平台模型管理导入,再设置工作台默认模型。旧环境中的 Key 仅在服务器本地核对输入。
3. 将解析服务和模型授权给原使用人群;不扩大原知识库/应用权限。旧知识库、应用、模型原有记录由迁移保留。
旧浏览器本地的未保存编辑内容和导出文件不会自动转为新版“我的导图”;升级前下载需要保留的内容,升级后可重新导入 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. 回退
```bash
# 保持与本次升级前相同的停机状态,只恢复旧容器名称:
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. 脚本验证
```bash
python3 -m unittest discover -s deploy_artifacts/tests -v
bash -n deploy_artifacts/build-release.sh
```
测试覆盖 Compose 凭据原样传递、GPU 隔离配置、内部数据库/worker 网络、原数据保护和失败回退身份检查。它们不启动 Docker 或访问共享服务。实际镜像构建、数据库演练和两类 GPU 业务验收仍需分别记录。