ONES Helm 升级说明（内置组件）

本文介绍如何升级通过 Helm 安装、使用 ONES 内置 MySQL、Kafka、Redis、TiKV 和 ClickHouse 的 ONES 集群。

本文适用于 Helm 配置文件 values.yaml 使用以下资源管理配置的场景：

enableNamespaceAutoCreate: false
enableCRDAutoCreate: true
enableRBACAutoCreate: true
enablePVCAutoReconcile: true
enableLocalStorageAutoCreate: false

本升级方式适用于 v7.25.0 或更高版本。升级前，必须确认当前版本到目标版本的升级路径受 ONES 支持。非 Helm 部署的环境不要使用本文操作。

内置组件部署方式由 Helm 自动管理 CRD、Namespace Scope RBAC 和 PVC。升级时无需手动更新 CRD、RBAC，也无需生成数据库升级包；升级前只需生成新增 PVC 清单进行容量评审。

准备升级参数

先确认当前环境的 ONES 版本和本次升级的目标版本，再在终端设置以下参数。本文后续命令会 直接使用这些参数，请在同一终端会话中执行。

执行前必须修改版本号： CURRENT_ONES_VERSION 填写当前环境实际运行的版本， TARGET_ONES_VERSION 填写本次计划升级到的版本。以下 v7.25.0 和 v7.26.0 仅为示例， 不要直接复制示例版本执行升级。

# 必须改为当前环境实际运行的 ONES 版本
CURRENT_ONES_VERSION="v7.25.0"

# 必须改为本次计划升级到的 ONES 版本
TARGET_ONES_VERSION="v7.26.0"
OS_ARCH="amd64"

NAMESPACE="ones"
RELEASE_NAME="ones"

REGISTRY="registry.example.com"
REGISTRY_USER="<私有镜像仓用户名>"
REGISTRY_PASSWORD="<私有镜像仓密码或 Token>"
REGISTRY_BASE_PATH="/ones/"

mkdir -p ~/ones
cd ~/ones

设置完成后，核对集群记录的当前版本与升级参数：

kubectl -n "${NAMESPACE}" get configmap ones-current-version \
  -o jsonpath='{.data.onesVersion}{"\n"}'
printf 'CURRENT_ONES_VERSION=%s\nTARGET_ONES_VERSION=%s\n' \
  "${CURRENT_ONES_VERSION}" "${TARGET_ONES_VERSION}"

集群记录的当前版本必须与 CURRENT_ONES_VERSION 完全一致；确认无误后再继续。

• OS_ARCH 支持 amd64 和 arm64。
• REGISTRY_BASE_PATH 必须与当前环境 ones-secret-config 中的 dockerRegistryBasepathForOnesImage 保持一致。
• 私有镜像仓不需要认证时，将 REGISTRY_USER 和 REGISTRY_PASSWORD 设置为空字符串。
• 私有镜像仓未启用 TLS 时，再执行 export REGISTRY_INSECURE=true。
• 当前环境使用的 values.yaml 应保存在 ~/ones/values.yaml。部分操作会进入生成的制品目录， 完成后应返回 ~/ones 再继续。

升级流程

1. 检查目标版本是否新增 PVC。
2. 将目标版本的 ONES 差量镜像导入私有镜像仓。
3. 检查是否满足升级放行标准。
4. 准备目标 ONES 版本。
5. 执行 Helm 升级。
6. 观察 Bootstrap 和数据库迁移。
7. 验证升级结果。

第一步：检查目标版本是否新增 PVC

生成当前版本到目标版本的新增 PVC 清单：

cd ~/ones
curl -sfL \
  "https://packages.ones.cn/release/${TARGET_ONES_VERSION}/kubernetes/generate-new-pvcs.sh" | \
  SRC_ONES_VERSION="${CURRENT_ONES_VERSION}" \
  bash -

查看生成的清单：

cat "${CURRENT_ONES_VERSION}-to-${TARGET_ONES_VERSION}-new-pvcs.yaml"

重点查看 NEW_PVC_COUNT。值为 0 表示目标版本没有新增 PVC；如果存在新增 PVC，请确认对应 StorageClass 的 CSI 存储供应方有充足的后端存储余量，并提前完成 PVC 容量预算和配额调整， 避免升级后部分 PVC 因存储不足而无法成功制备和绑定。

注意： 本步骤只生成和评审清单，不要执行 kubectl apply。保持 enablePVCAutoReconcile: true，Helm 升级时会自动创建和管理新增 PVC。

第二步：导入目标版本 ONES 差量镜像

默认使用 ONES 提供的工具包导入镜像。如需改用 Docker 等方式，请参见附录中的 其他 ONES 镜像导入方式。本流程不导入目标版本的内置 MySQL 镜像。

2.1 制作 ONES 差量离线包

在联网主机执行以下命令，制作当前版本到目标版本的差量离线包：

curl -fL \
  "https://packages.ones.cn/release/${TARGET_ONES_VERSION}/kubernetes/images/upgrade-ones-images-${OS_ARCH}.sh" | \
  SRC_ONES_VERSION="${CURRENT_ONES_VERSION}" \
  MODE="offline-package" \
  bash -

脚本会在当前目录生成：

${CURRENT_ONES_VERSION}-to-${TARGET_ONES_VERSION}-new-images-linux-${OS_ARCH}.tar

2.2 导入 ONES 差量离线包

将离线包复制到目标环境，解压并进入目录：

tar -xf "${CURRENT_ONES_VERSION}-to-${TARGET_ONES_VERSION}-new-images-linux-${OS_ARCH}.tar"
cd "${CURRENT_ONES_VERSION}-to-${TARGET_ONES_VERSION}-new-images-linux-${OS_ARCH}"

运行包内的导入脚本：

REGISTRY="${REGISTRY}" \
REGISTRY_BASE_PATH="${REGISTRY_BASE_PATH}" \
REGISTRY_USER="${REGISTRY_USER}" \
REGISTRY_PASSWORD="${REGISTRY_PASSWORD}" \
bash import-images.sh

镜像导入完成后，返回 ONES 操作目录：

cd ~/ones

镜像导入完成

执行到这里，升级所需的 ONES 差量镜像已经导入私有镜像仓。现在可以继续第三步。

第三步：检查是否满足升级放行标准

满足以下条件后，方可进入 Helm 升级操作：

1. 当前环境服务状态正常，不存在持续异常的 Pod。
2. 磁盘空间、磁盘 I/O、CPU 和内存满足升级要求。
3. 生产环境的备份资源与业务数据盘相互隔离。
4. 内置 MySQL 已完成一次全量备份，附件、Wiki、插件和审计日志等数据的备份已经完成。
5. 内置 MySQL、Kafka、Redis、TiKV 和 ClickHouse 状态正常。
6. Kubernetes 集群状态正常，证书以及 Pod、Node、Namespace 容量不存在升级阻断风险。
7. values.yaml 不存在重复配置项。
8. 新增 PVC 所需的存储容量和 ResourceQuota 配额已经完成评审。
9. 升级窗口、回退方案、客户确认人和 ONES 支持接口人已经明确。

如果任一条件不满足，应先完成整改，或通过升级评审确认风险后再继续。

记录当前 Helm Release、ONES 版本和 Helm 配置：

helm -n "${NAMESPACE}" status "${RELEASE_NAME}"
helm -n "${NAMESPACE}" get values "${RELEASE_NAME}" -o yaml > ~/ones/ones-helm-values-backup.yaml
kubectl -n "${NAMESPACE}" get configmap ones-current-version -o yaml

不要将包含密码或 Token 的文件提交到 Git 仓库或发送到不受控的日志系统。

ResourceQuota 场景

启用了 Namespace ResourceQuota 时，升级过程中的滚动更新和数据库迁移会临时增加 Pod 和 资源上限。升级前检查剩余配额：

kubectl -n "${NAMESPACE}" describe resourcequota

当 ResourceQuota 要求每个容器必须配置 CPU、内存的 request 和 limit 时，确认 values.yaml 包含数据库迁移主容器和 initContainer 的资源配置：

migrationContainerCPURequest: "0"
migrationContainerCPULimit: "4000m"
migrationContainerMemoryRequest: "0"
migrationContainerMemoryLimit: "10Gi"
migrationInitContainerCPURequest: "0"
migrationInitContainerCPULimit: "500m"
migrationInitContainerMemoryRequest: "0"
migrationInitContainerMemoryLimit: "128Mi"

注意： 数据量超过 250 GB 时，将 migrationContainerMemoryLimit 调整为 "20Gi"。执行升级前，请确保 Namespace ResourceQuota 的内存 limit 剩余配额足以满足 迁移容器的 20Gi 限制；配额不足时，应先提高 ResourceQuota。

如果缺少这些配置，Migration Job 会因不满足 ResourceQuota 要求而无法创建 Pod。此时 Job 事件会显示 FailedCreate，并提示迁移主容器或 initContainer 缺少 requests、limits。

如果 CPU、内存、Pod、PVC 数量或存储容量配额接近上限，应先提高 ResourceQuota。

第四步：准备目标 ONES 版本

确认 CURRENT_ONES_VERSION 和 TARGET_ONES_VERSION 已设置为本次升级的当前版本和目标版本。

更新 Helm 仓库并确认目标版本存在：

helm repo update
helm search repo ones/ones-cluster --versions

确认列表中存在目标 ONES 版本，并确认 ~/ones/values.yaml 是当前环境使用的配置。升级时继续 使用该文件，不要导出和复用旧 Chart 的完整默认 values。

内置组件部署环境应保持以下配置，并确保文档开头列出的资源管理配置没有被修改：

internalComponentMysqlEnable: true
mysqlManualInitDBEnable: false

第五步：执行 Helm 升级

进入 ONES 操作目录，并确认 values.yaml 存在：

cd ~/ones
ls -l ~/ones/values.yaml

确认文件存在后再执行 Helm 升级，避免在镜像包的解压目录中误操作。

helm upgrade "${RELEASE_NAME}" ones/ones-cluster \
  --version "${TARGET_ONES_VERSION}" \
  --namespace "${NAMESPACE}" \
  -f ~/ones/values.yaml \
  --atomic \
  --timeout 30m

不要添加 --reuse-values。Chart 的新版本可能增加或调整默认值；升级命令只需继续传入客户 维护的稀疏 values.yaml，新 Chart 默认值会自动生效。

Helm 命令完成只表示 Chart 资源已更新，不表示 ONES 业务升级已经完成。后续 Bootstrap、 数据库迁移和应用更新由 installer-operator 继续执行。

第六步：观察 Bootstrap 和数据库迁移

持续观察升级进度：

kubectl -n "${NAMESPACE}" logs -f deployment/installer-operator

installer-operator 会识别当前版本和目标版本，自动执行目标版本需要的数据库迁移，并更新 ONES 工作负载。

如果升级失败，会生成 installer-operator-error Pod。查看已完成步骤和有效错误：

kubectl -n "${NAMESPACE}" logs installer-operator-error

修复存储、配额、配置或其他依赖问题后，installer-operator 会自动重试。不要在错误原因未 确认时反复执行 helm upgrade。

可以通过以下命令查看版本和迁移记录：

kubectl -n "${NAMESPACE}" get configmap ones-current-version -o yaml
kubectl -n "${NAMESPACE}" get configmap ones-latest-successful-migration -o yaml
kubectl -n "${NAMESPACE}" get migrations.ones.ai

第七步：验证升级结果

helm -n "${NAMESPACE}" status "${RELEASE_NAME}"
kubectl -n "${NAMESPACE}" get pods
kubectl -n "${NAMESPACE}" get pvc
kubectl -n "${NAMESPACE}" get configmap ones-current-version \
  -o jsonpath='{.data.onesVersion}{"\n"}'

确认以下结果：

• ones-current-version 已更新为目标 ONES 版本。
• installer-operator 日志显示 Bootstrap 全部步骤完成。
• ONES 和内置组件 Pod 均已就绪，不存在持续的 Pending、CrashLoopBackOff 或 ImagePullBackOff。
• 评审发现的新增 PVC 已创建并处于 Bound 状态。
• 登录 ONES 后，核心业务以及内置 MySQL、Kafka、Redis、TiKV 和 ClickHouse 访问正常。

升级完成后，再按照ONES 升级后调整完成目标版本要求的检查。

升级失败和版本回退

helm rollback 只能回退 Helm 管理的资源，不能撤销已经执行的数据库迁移。不要使用 helm rollback 作为 ONES 业务版本回退方案。

版本回退时，installer-operator 会检查目标区间是否包含已执行的数据迁移：

• 存在数据迁移时，自动回退会被拒绝。
• 不存在数据迁移时，仍需确认目标版本的镜像、配置、PVC 和内置组件均可用。

升级失败或需要回退时，请保留 installer-operator-error、迁移 ConfigMap、内置组件和相关 Pod 日志，联系 ONES 技术支持确认处理方案。

附录

附录用于说明特殊场景，不是正文完成后的追加步骤。以下方式可以替代正文中的离线镜像包 导入，无需重复执行。命令复用准备升级参数中设置的参数，请在同一终端 会话中执行。

其他 ONES 镜像导入方式

查看 ONES 差量镜像清单

如需在导入前查看当前版本到目标版本新增的 ONES 镜像，执行：

curl -fL \
  "https://packages.ones.cn/release/${TARGET_ONES_VERSION}/kubernetes/images/upgrade-ones-images-${OS_ARCH}.sh" | \
  SRC_ONES_VERSION="${CURRENT_ONES_VERSION}" \
  bash -

脚本会在当前目录生成：

${CURRENT_ONES_VERSION}-to-${TARGET_ONES_VERSION}-new-images-${OS_ARCH}.yaml

使用 Docker 在线导入

执行主机需要能够访问 ONES 镜像仓和私有镜像仓，并已通过 docker login 登录私有镜像仓。

导入 ONES 差量镜像：

curl -fL \
  "https://packages.ones.cn/release/${TARGET_ONES_VERSION}/kubernetes/images/upgrade-ones-images-${OS_ARCH}.sh" | \
  SRC_ONES_VERSION="${CURRENT_ONES_VERSION}" \
  MODE="docker" \
  REGISTRY="${REGISTRY}" \
  REGISTRY_BASE_PATH="${REGISTRY_BASE_PATH}" \
  bash -

使用 image-syncer 在线同步 ONES 差量镜像

脚本会自动下载 image-syncer 所需工具，并将 ONES 差量镜像同步到私有镜像仓：

curl -fL \
  "https://packages.ones.cn/release/${TARGET_ONES_VERSION}/kubernetes/images/upgrade-ones-images-${OS_ARCH}.sh" | \
  SRC_ONES_VERSION="${CURRENT_ONES_VERSION}" \
  MODE="image-syncer" \
  REGISTRY="${REGISTRY}" \
  REGISTRY_BASE_PATH="${REGISTRY_BASE_PATH}" \
  REGISTRY_USER="${REGISTRY_USER}" \
  REGISTRY_PASSWORD="${REGISTRY_PASSWORD}" \
  bash -