跳到主要内容

ONES Helm 升级说明（外置数据库）

适用场景：适用于使用外置数据库，且对升级权限隔离和变更审计有严格合规要求的环境。 升级过程遵循最小权限原则，CRD、RBAC、PVC 等 Kubernetes 资源变更及数据库升级 SQL 均可 纳入现有审批流程，由相应管理员审核并执行。

本文介绍如何升级通过 Helm 安装的 ONES 集群。仅适用于集群多副本、外置 MySQL 和 Namespace Scope 部署方式。

升级前，必须确认当前版本到目标版本的升级路径受 ONES 支持。非 Helm 部署的环境不要 使用本文操作。

准备升级参数​

先在终端执行以下命令，根据实际环境准备升级参数。本文后续命令均复用这些参数，请在同一 终端会话中执行：

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

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

# Kubernetes 节点架构，支持 amd64 和 arm64
OS_ARCH="amd64"

# ONES 所在的 Namespace
NAMESPACE="ones"

mkdir -p ~/ones/${NAMESPACE}
cd ~/ones/${NAMESPACE}
  • OS_ARCH 支持 amd64 和 arm64。
  • 当前环境使用的 values.yaml 应保存在 ~/ones/${NAMESPACE}/values.yaml。部分操作会进入生成的 制品目录，完成后应返回 ~/ones/${NAMESPACE} 再继续。

升级流程​

  1. 制作差量离线包并将新镜像导入私有镜像仓。
  2. 检查是否满足升级放行标准。
  3. 准备目标 ONES 版本。
  4. 更新 CRD、RBAC，创建新增 PVC，并准备数据库升级 SQL。
  5. 执行 Helm 升级。
  6. 观察 Bootstrap 和数据库迁移。
  7. 验证升级结果。

第一步：导入目标版本差量镜像​

默认使用 ONES 提供的工具包导入镜像。如需改用 Docker 等方式，请参见附录中的 其他差量镜像导入方式。

1.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

1.2 导入差量离线包​

在目标环境的终端设置私有镜像仓参数：

# 私有镜像仓地址，不包含 http:// 或 https://
REGISTRY="registry.example.com"

# 私有镜像仓用户名
REGISTRY_USER="<私有镜像仓用户名>"

# 私有镜像仓密码或 Token
REGISTRY_PASSWORD="<私有镜像仓密码或 Token>"

# ONES 镜像路径前缀，必须与当前环境配置保持一致
REGISTRY_BASE_PATH="/ones/"
  • REGISTRY_BASE_PATH 必须与当前环境 ones-secret-config 中的 dockerRegistryBasepathForOnesImage 保持一致。
  • 私有镜像仓不需要认证时，将 REGISTRY_USER 和 REGISTRY_PASSWORD 设置为空字符串。
  • 私有镜像仓未启用 TLS 时，再执行 export REGISTRY_INSECURE=true。

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

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

离线包内已经包含目标架构的 image-syncer 及其依赖工具。

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

cd ~/ones/${NAMESPACE}

差量镜像导入完成​

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

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

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

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

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

记录当前 Helm Release 和 ONES 版本。

helm -n "${NAMESPACE}" status ones
helm -n "${NAMESPACE}" get values ones -o yaml \
  > ~/ones/${NAMESPACE}/ones-helm-values-backup-${CURRENT_ONES_VERSION}.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 配额接近上限，应先提高 ResourceQuota。ResourceQuota 部署方式的 目标 ONES 版本必须高于 v7.26.0。

第三步：准备目标 ONES 版本​

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

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

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

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

第四步：更新 CRD、RBAC、PVC 和数据库​

4.1 更新 CRD​

kubectl apply --server-side \
  -f "https://packages.ones.cn/release/kubernetes-mainfest/${TARGET_ONES_VERSION}/ones/common/ones-cluster-crd.yaml"

4.2 更新 Namespace Scope RBAC​

kubectl -n "${NAMESPACE}" apply \
  -f "https://packages.ones.cn/release/kubernetes-mainfest/${TARGET_ONES_VERSION}/ones/common/ones-cluster-rbac-mini.yaml"

4.3 生成新增 PVC 清单​

执行目标版本提供的脚本。脚本会比较当前版本和目标版本的 PVC 清单，只输出目标版本新增的 PVC：

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

脚本会在当前目录生成 ${CURRENT_ONES_VERSION}-to-${TARGET_ONES_VERSION}-new-pvcs.yaml。文件头会列出源版本、目标 版本和新增 PVC 名称：

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

当 NEW_PVC_COUNT 大于 0 时，将生成文件中的 StorageClass 占位符替换为 values.yaml 中对应配置项的值：

PVC 清单占位符values.yaml 配置项
__storageClassNameForReadWriteMany__storageClassNameForReadWriteMany
__storageClassNameForReadWriteManyWithRetain__storageClassNameForReadWriteManyWithRetain
__storageClassNameForReadWriteOnce__storageClassNameForReadWriteOnce
__storageClassNameForReadWriteOnceWithRetain__storageClassNameForReadWriteOnceWithRetain

确认占位符已全部替换，再创建新增 PVC。

grep -n '__storageClassName' \
  "${CURRENT_ONES_VERSION}-to-${TARGET_ONES_VERSION}-new-pvcs.yaml"
kubectl apply -f \
  "${CURRENT_ONES_VERSION}-to-${TARGET_ONES_VERSION}-new-pvcs.yaml"
kubectl -n "${NAMESPACE}" get pvc

grep 无输出表示占位符已全部替换。NEW_PVC_COUNT 为 0 时，不需要执行 kubectl apply。该脚本不会修改或删除已有 PVC。

4.4 生成数据库升级包​

执行目标版本提供的脚本。

curl -sfL \
  "https://packages.ones.cn/release/${TARGET_ONES_VERSION}/database/generate-database-upgrade.sh" | \
  SRC_ONES_VERSION="${CURRENT_ONES_VERSION}" \
  bash -

脚本会在当前目录生成 ${CURRENT_ONES_VERSION}-to-${TARGET_ONES_VERSION}-database-upgrade.tar.gz。

脚本比较当前版本和目标版本的数据库制品，生成的压缩包包含：

  • sql/account/create-users.sql：新增或发生变化的数据库账号语句。
  • sql/databases/<database>/：新增数据库的建库和完整初始化 SQL。
  • sql/grant/grant-users.sql：新增或发生变化的授权语句。
  • metadata.yaml：SQL 文件清单和执行顺序。
  • database-upgrade.md：英文数据库升级操作说明。

差异 SQL 的范围为：

  • 新增或发生变化的数据库账号语句。
  • 新增或发生变化的授权语句。
  • 新增数据库及其完整初始化 SQL。

已有数据库不会重复输出，即使其初始化 SQL 在目标版本中发生变化。已有数据库的表结构变化由 ONES 数据库迁移处理。

解压后按照说明完成 SQL 审核、密码占位符替换和数据库操作。

tar -xzf \
  "${CURRENT_ONES_VERSION}-to-${TARGET_ONES_VERSION}-database-upgrade.tar.gz"
cd "${CURRENT_ONES_VERSION}-to-${TARGET_ONES_VERSION}-database-upgrade"
cat database-upgrade.md

database-upgrade.md 会在 Review the SQL files 中列出需要数据库管理员审核的全部 SQL， 并提供密码替换说明和 SQL 执行顺序。账号、授权和新增数据库三类差异数量均为 0 时，不需要 执行数据库升级 SQL。

数据库升级准备完成后，返回 ONES 操作目录：

cd ~/ones/${NAMESPACE}

第五步：执行 Helm 升级​

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

cd ~/ones/${NAMESPACE}
ls -l ~/ones/${NAMESPACE}/values.yaml

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

helm upgrade ones ones/ones-cluster \
  --version "${TARGET_ONES_VERSION}" \
  --namespace "${NAMESPACE}" \
  -f ~/ones/${NAMESPACE}/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 ones
kubectl -n "${NAMESPACE}" get pods
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。
  • 登录 ONES 后，核心业务和外置 MySQL 访问正常。

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

升级失败和版本回退​

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

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

  • 存在数据迁移时，自动回退会被拒绝。
  • 不存在数据迁移时，可以使用原版本 Chart 再次执行 helm upgrade，触发 ONES 业务版本回退。

无数据迁移时回退版本​

仅当确认当前版本与回退目标版本之间未执行数据迁移时，才可执行以下操作。回退前还需确认：

  1. 原版本镜像仍保留在私有镜像仓中。
  2. 升级前备份的 ~/ones/${NAMESPACE}/ones-helm-values-backup-${CURRENT_ONES_VERSION}.yaml 可用。
  3. 外置数据库及其他外部依赖与原版本兼容。

使用升级前的 values.yaml 和原版本 Chart 执行回退：

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

该操作在 Helm 历史中会记录为一次新的 Upgrade Revision，这是正常现象。继续观察回退过程：

kubectl -n "${NAMESPACE}" logs -f deployment/installer-operator
kubectl -n "${NAMESPACE}" get configmap ones-current-version \
  -o jsonpath='{.data.onesVersion}{"\n"}'
kubectl -n "${NAMESPACE}" get pods

确认 ones-current-version 已恢复为 ${CURRENT_ONES_VERSION}，所有 ONES Pod 均已就绪， 并验证核心业务和外置数据库访问正常。

升级失败或需要回退时，请保留 installer-operator-error、迁移 ConfigMap 和相关 Pod 日志， 联系 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

脚本输出会分别显示 ONES 主体镜像和迁移镜像的数量。数量为 0 表示对应类型没有新增镜像。

使用 Docker 在线导入​

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

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 在线同步​

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

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 -