HAP 私有部署跨版本升级：步骤与注意事项

跨版本升级，通常无需逐个安装中间版本；但只更新镜像和版本号，并不代表升级完成。

本文说明通用流程，补充近期版本的预置数据更新要求。具体命令按对应版本、部署模式和架构查阅官方说明。

主应用准备目标版本镜像，
跨越版本的适用附加操作必须补齐。
重点检查：组件依赖、认证建库、预置数据、服务配置和增量数据库脚本。前置迁移或分阶段操作按官方规定顺序执行。

一、建议的停服升级顺序

1. 确认环境。记录起止版本、部署模式、CPU 架构、联网或离线；核对架构支持、授权期限、磁盘空间和数据库类型。组件最低要求必须满足，例如升级到 6.0.0+ 要求 MongoDB ≥ 4.4。
2. 列全变更。从当前版本之后核对到目标版本，阅读版本表及详情，重点检查“含附加操作”；未标记及已归入“不再维护”的路径版本也需核对。按适用条件列出前置、后置动作。
3. 先备份，再做任何数据或配置变更。备份数据库、文件和配置，检查结果并明确恢复步骤。提前备齐镜像、脚本和数据包，整理配置差异；集群确认相关节点镜像齐全。
4. 保持原版本运行，先完成 MongoDB 预置数据更新。路径要求更新时，先满足脚本的前置条件；涉及认证建库及授权的，按对应说明完成。确认预置更新成功后再停服，跨版本合并规则见下表。
5. 按旧配置停止微服务，确认旧服务已退出。此时保留原服务清单和配置，按对应部署方式执行停服。不要先删除、重命名服务配置再处理旧服务。
6. 修改配置，完成组件调整。按路径合并服务增删、镜像名称及版本、环境变量、挂载、端口和代理配置。组件升级及迁移遵循各自前置要求；组件版本不能统一改成 HAP 版本号。
7. 启动目标版本微服务。按对应部署方式启动，等待服务就绪。单机与集群的脚本、配置和执行位置不能混用。
8. 执行后置变更。在文档指定的容器或 Pod 中，完成各版本的结构、索引及其他数据操作。按数据库类型选用对应 SQL，核对实际连接参数。保留结果，报错先处理，再继续后续步骤。
9. 完成验收。确认服务、数据变更及关键业务正常后，再结束升级。验收项目见文末。

为什么先更新预置数据？官方单机脚本进入运行中的 HAP 容器执行更新，集群脚本进入现有 config Pod 执行。先停服可能失去脚本执行入口。把下载和预置更新提前完成，也能缩短停机时间。停服若依赖配置中的服务清单，先修改清单还可能遗漏旧资源，因此推荐先按旧配置停服，再切换配置。

执行入口：单机微服务升级 · 集群微服务升级 · 单机备份。数据库已变更时，仅切回旧镜像不能作为完整恢复方案。

二、三类数据操作，处理规则不同

预置数据更新入口：单机模式 · 集群模式。联网按官方脚本执行；离线同时准备脚本和目标版本数据包。集群还需指定实际命名空间。

官方页面里的示例版本号不一定是本次目标版本，执行时应核对版本参数、数据包和命名空间。

三、近期示例：v7.3.6 → v7.5.0

以 AMD64 集群为例，合并 7.4.0 与 7.5.0 要求后，重点顺序如下：

1. 完成备份。MongoDB 开启认证时，按 7.4.0 说明创建并授权 MDAgentInfra 库。
2. 保持旧版本运行，MongoDB 预置数据直接更新到 7.5.0 一次，无需先更新到 7.4.0 再更新一遍。
3. 按原服务配置停止微服务，确认旧服务已退出。
4. 修改服务配置：删除 ai，新增 agent、tpintegrate、accountapi；有外层代理时补充 SSE 流式响应和长连接配置。
5. 启动 7.5.0 微服务，不逐个启动 7.4.x。
6. 执行 7.4.0 要求的 MongoDB 索引脚本：mdapps、mdopenauth、mdsms、mdemail，再完成业务验收。

该例仅适用于上述起止版本及部署模式；其他路径仍需逐版本核对。单机不照搬集群的服务 YAML 和 config Pod 操作。

四、验收通过，才算升级完成

• 服务：版本正确、状态正常，无持续重启或明显报错。
• 变更：组件、配置、预置数据及增量脚本均已完成，无未处理错误。
• 预置内容：国家地区选择、翻译及模板显示正常；涉及预置文件时验证文件访问。
• 业务：验证登录、工作表读写、一条代表性工作流，以及附件上传下载。
• 扩展：按启用情况验证代码块、文档预览、对象存储、单点登录、集成及 SSE 流式响应。

页面能打开、版本号能显示，不等于升级完成。

镜像名称也要核对：从 v7.1.0 起主应用使用 mingdaoyun-hap，历史版本仍用 mingdaoyun-community，见命名变更说明。

资料核对：2026-10-16。本文为升级思路说明，具体执行以对应官方文档为准。