Hap Upgrade Guide

HAP 私有部署升级 Skill

本 skill 覆盖两类场景：

• 场景 A：升级咨询解答 — 用户有升级相关的具体问题需要解答
• 场景 B：生成升级指南 — 用户需要一份完整的可执行升级文档

收到用户请求后，先判断属于哪类场景，再按对应流程处理。两类场景可能在同一对话中切换，保持灵活。

场景 A：升级咨询解答

触发特征

用户提出具体问题，例如：

• "v7.0.0 升级到 v7.2.0 需要注意什么？"
• "能直接跨版本升级吗？"
• "附加操作是什么意思，必须执行吗？"
• "v7.1.0 的镜像命名变更怎么处理？"
• "升级失败了怎么回滚？"
• "这次升级有哪些新功能？"

解答流程

第一步：判断是否需要抓取文档

• 若问题涉及具体版本的变更内容、升级步骤、附加操作，必须先 web_fetch 对应版本页再回答，不得凭记忆猜测
• 若问题是通用升级概念（如跨版本升级策略、附加操作含义、回滚方法等），可直接基于本 skill 的知识回答

第二步：抓取所需文档

先读取 references/site-structure.md 确认 URL，再按需抓取：

版本发布历史：https://docs-pd.mingdao.com/version
特定版本详情：https://docs-pd.mingdao.com/upgrade/{版本号}/

第三步：组织回答

• 聚焦用户问题，不要生成完整升级文档
• 涉及代码命令时原文引用，不得改写
• 可选步骤明确说明适用条件
• 回答末尾附上相关官方文档链接
• 重要回答末尾必须附上 AI 声明（见文末"输出规范"）

常见咨询场景回答要点

关于跨版本升级

• HAP 支持跨版本直接升级，无需逐版本操作
• 需关注跨越路径中含附加操作的版本，这些版本的操作需合并执行
• 不含附加操作的版本只需在备份后升级微服务镜像版本即可

关于附加操作

• 分为两类：微服务升级前（Pre）和升级后（Post）
• Pre 操作示例：镜像命名替换、创建 MongoDB 库、存储组件升级（仅单机）、MongoDB 预置数据更新
• Post 操作示例：进入容器/Pod 执行 MySQL DDL、MongoDB DDL 脚本
• 跨越多版本时，同类操作可合并执行（详见场景 B 合并规则）

关于版本维护

• 官方默认维护最新 3 个主版本（第三位为 0 的版本）
• 同一主版本下，建议选择第三位数字最大的修复版本升级

场景 B：生成升级指南

Step 1 — 收集前置信息（必须完成，不可跳过）

必须先向用户确认以下全部信息，若未主动提供，逐一询问：

⚠️ 以上 5 项全部确认后，方可进入 Step 2。

询问话术示例：

在生成升级指南之前，我需要确认以下信息：
1. 您当前运行的版本是？（例如：v7.0.4）
2. 希望升级到哪个目标版本？（例如：v7.2.0）
3. 部署模式是单机模式（Docker Compose）还是集群模式（Kubernetes）？
4. 服务器架构是 AMD64 还是 ARM64？
5. 服务器是否可以访问互联网？

Step 2 — 抓取并分析版本信息

2.1 读取站点结构

先读取 references/site-structure.md，获取版本列表页 URL 及各版本升级说明页的 URL 规律。

2.2 获取版本列表

web_fetch 抓取：https://docs-pd.mingdao.com/version

从中识别：

• 当前版本到目标版本之间所有被跨过的版本（不含当前版本，含目标版本），按从旧到新排列
• 每个版本是否含附加操作（"含附加操作"列有 √）
• 目标版本是否支持用户所选架构，若不支持则立即告知用户并停止

2.3 抓取含附加操作的版本详情

只需抓取"含附加操作"的版本，逐一 web_fetch：

URL 格式: https://docs-pd.mingdao.com/upgrade/{版本号}/

对每个含附加操作的版本，提取并区分 Pre / Post 操作：

Pre 操作（微服务升级前）常见类型：

• 镜像命名变更（替换配置文件中的镜像名、服务名）
• 手动创建 MongoDB 数据库（如 mdwfai、mdpayment 等）
• 存储组件升级（仅单机模式，集群模式无此步骤）
• 重新初始化预置文件（使用外部文件对象存储时）
• MongoDB 预置数据更新（标注"可在原版本服务运行状态下执行"）
• 微服务 yaml 配置新增服务（集群模式）

Post 操作（微服务升级后）常见类型：

• 进入微服务容器执行 MySQL DDL 脚本（单机）
• 进入 config Pod 执行 MongoDB DDL 脚本（集群）
• 进入 config Pod 执行 MySQL DDL 脚本（集群）
• 进入 config Pod 执行文件初始化命令（集群）

Step 3 — 合并附加操作（跨版本升级核心）

跨多个含附加操作的版本时，将所有版本的附加操作合并为一次执行：

Pre 操作合并规则

Post 操作合并规则

合并示例

从 v6.4.0 跨越到 v7.2.0（跨过 v6.5.0、v7.0.0、v7.1.0、v7.2.0，均含附加操作）

Pre 合并：镜像命名替换执行一次（v7.1.0）、MongoDB 库一次性全部创建、MongoDB 预置数据只更新到 7.2.0、yaml 新增服务合并写入

Post 合并（集群）：一次进入 config Pod，依次执行 v6.5.0 → v7.0.0 → v7.2.0 的所有脚本

Step 4 — 生成升级指南

根据部署模式，读取对应模板文件的完整内容：

- 单机模式 → assets/upgrade-guide-template-standalone.md

- **集群模式 → assets/upgrade-guide-template-cluster.md

> 必须先读取模板文件内容，再开始填充生成。不得凭记忆构造文档结构。注意以下关键规则：

关键生成规则

镜像拉取 / 导入（根据网络情况）

联网 — 单机 AMD64：

docker pull registry.cn-hangzhou.aliyuncs.com/mdpublic/mingdaoyun-hap:{目标版本号}

联网 — 单机 ARM64：

docker pull registry.cn-hangzhou.aliyuncs.com/mdpublic/mingdaoyun-hap-arm64:{目标版本号}

联网 — 集群（每台微服务节点）：

crictl pull registry.cn-hangzhou.aliyuncs.com/mdpublic/mingdaoyun-hap:{目标版本号}

离线镜像 URL 规律（替换版本号即可获取历史版本）：

AMD64: https://pdpublic.mingdao.com/private-deployment/offline/mingdaoyun-hap-linux-amd64-{版本号}.tar.gz
ARM64: https://pdpublic.mingdao.com/private-deployment/offline/mingdaoyun-hap-linux-arm64-{版本号}.tar.gz

离线导入 — 单机：docker load -i mingdaoyun-hap-linux-amd64-{版本号}.tar.gz 离线导入 — 集群（每台节点）：gunzip -d xxx.tar.gz && ctr -n k8s.io image import xxx.tar

MongoDB 预置数据更新（只执行目标版本，4 种情况）

单机联网：

bash -c "$(curl -fsSL https://pdpublic.mingdao.com/private-deployment/data/preset_mongodb_docker.sh)" -s {目标版本号}

单机离线：

wget https://pdpublic.mingdao.com/private-deployment/data/preset_mongodb_docker.sh
wget https://pdpublic.mingdao.com/private-deployment/data/preset_mongodb_{目标版本号}.tar.gz
bash ./preset_mongodb_docker.sh {目标版本号} ./preset_mongodb_{目标版本号}.tar.gz

集群联网：

# default 替换为实际命名空间
bash -c "$(curl -fsSL https://pdpublic.mingdao.com/private-deployment/data/preset_mongodb_k8s.sh)" -s {目标版本号} default

集群离线：

wget https://pdpublic.mingdao.com/private-deployment/data/preset_mongodb_k8s.sh
wget https://pdpublic.mingdao.com/private-deployment/data/preset_mongodb_{目标版本号}.tar.gz
# default 替换为实际命名空间
bash ./preset_mongodb_k8s.sh {目标版本号} default ./preset_mongodb_{目标版本号}.tar.gz

单机微服务升级：修改 docker-compose.yaml 镜像版本号，然后 bash ./service.sh restartall

集群微服务升级：在控制节点 /data/mingdao/script/kubernetes 目录下执行

• 滚动更新（推荐）：bash update.sh update hap {目标版本号}
• 非滚动更新（内存不足时）：先 bash stop.sh，确认 Pod 消失后再执行 bash update.sh update hap {目标版本号}

单机存储组件升级（仅单机，集群无此步骤）： 联网 AMD64：docker pull registry.cn-hangzhou.aliyuncs.com/mdpublic/mingdaoyun-sc:{版本号} 联网 ARM64：docker pull registry.cn-hangzhou.aliyuncs.com/mdpublic/mingdaoyun-sc-arm64:{版本号} 之后修改 docker-compose.yaml 中存储组件镜像版本号，然后 bash ./service.sh restartall （注意：若与微服务同时升级，可在最后只执行一次 restartall）

创建 MongoDB 数据库（仅开启认证时需要）

创建 MongoDB 数据库时，命令规范：在整理出的创建数据库的命令中，仅 use {库名} 和 db: "{库名}" 按升级实际要求补全。

单机 — 进入存储组件容器操作：

# 进入存储组件容器
docker exec -it $(docker ps | grep mingdaoyun-sc | awk '{print $1}') bash

# 容器内：使用含 admin 角色的用户登录（替换用户名和密码）
mongo -u 用户名 -p 密码 --authenticationDatabase admin

# 依次创建所有需要的库和对应用户（每个库重复以下两条命令）
use {库名}
db.createUser({ user: "修改成与其他库一致的用户名", pwd: "修改成与其他库一致的密码", roles: [{ role: "readWrite", db: "{库名}" }] })

在单机部署模式下，系统内置的 MongoDB 存储组件默认不启用身份认证。只有在用户参照 MongoDB 添加认证 文档完成相关配置后，认证功能才会开启。

集群 — 登录到 MongoDB 服务器后操作：

# 使用含 admin 角色的用户登录 MongoDB（替换连接信息）
mongo -u 用户名 -p 密码 --authenticationDatabase admin

# 依次创建所有需要的库和对应用户（每个库重复以下两条命令）
use {库名}
db.createUser({ user: "修改成与其他库一致的用户名", pwd: "修改成与其他库一致的密码", roles: [{ role: "readWrite", db: "{库名}" }] })

其他写作规范

• 所有代码命令原文保留，不得改写或简化，禁止使用“此处省略”、“结构同上”等描述，必须提供完整可运行的代码块
• 代码块使用 ``` bash 或 ``` yaml 包裹
• 有路径占位符或需要用户修改的参数，在代码块上方用 > 💡 提示
• 含附加操作的步骤前加 > ⚠️ **特别注意** 提示框
• 可选操作（如"如果已开启 MongoDB 认证"）明确标注适用条件，不要删除
• 备份步骤永远放在第一位
• 统一输出为 Markdown (.md) 文件，保存后提供用户下载

输出规范

AI 声明（所有输出必须附加）

无论是生成的升级指南文档，还是场景 A 中的重要回答，末尾必须附上以下声明：

---
💡 声明：本文档内容由 AI 生成。尽管已努力确保信息的合理性，但 AI 模型仍可能产生不准确、过时或存在偏差的内容。请在执行关键操作前，务必对照[官方文档](https://docs-pd.mingdao.com)进行核实校验。

注意事项

• 所有命令来自官方文档，禁止自行创作或修改命令逻辑
• 集群模式没有存储组件升级步骤，不要在集群模板中生成此步骤
• 网站默认使用中文文档（英文版路径加 /en/ 前缀）
• 抓取页面时若内容不完整，可重试或尝试抓取英文版对照
• 咨询解答时，若涉及具体版本，务必先抓文档再回答，不得凭记忆猜测