ONES 升级操作说明

本文将引导您完成单机版 ONES 升级过程；

如果按照ONES 集群安装说明部署，也可以参考本文升级ONES 集群。

操作步骤

升级前准备
升级操作
升级后操作

1.升级准备

1.1 升级前准备

在开始升级之前，参考ONES 升级前检查第1章进行检查；再获取当前ONES版本号。

1.2 查看可升级版本

通过以下命令选择一个可用的版本号，或联系ONES工程师确认目标版本号。

# 列出所有可用版本
curl https://packages.ones.cn/release/ones-versions.yaml

1.3 准备在线服务器下载升级包

如果运行 ONES 的服务器是离线的，需要找一台在线的服务器来制作差量包。然后将差量包拷贝到离线服务器上进行升级。
如果运行 ONES 的服务器是在线的，可以直接在运行 ONES 的服务器上进行升级。也可以提前准备一台在线服务器来制作差量包。然后将差量包拷贝到运行 ONES 的服务器上进行升级。

根据1.1获取的当前版本号和1.2获取的目标版本号来制作差量包，假定你当前的版本号是 v3.14.32、目标版本号是 v3.15.25，相关命令如下：

#root账号登录服务器
sudo su -

#创建临时目录
mkdir   -p /data/upgrade/

#下载升级包
curl https://packages.ones.cn/release/v3.15.25/build_offline_pkg_linux_amd64.sh | sudo SRC_ONES_VERSION=v3.14.32  IMAGE_REGISTRY_PORT=5001  bash - 

#如果上述命令报错 FATAL：pip3 not found, please install pip3 or build soft link to pip3 from pip-3.x
#则是缺失pip组件，需要先安装，ubuntu上手工执行命令：   apt install -y python3-pip

等待10-20分钟（取决于网络带宽），直到看到以下输出，表示下载成功。

alt text

1.4 获取当前ONES数据目录

执行如下命令查找当前环境ONES数据目录的实际路径，在2.3节使用

kubectl -n ones-installer describe deploy installer-api | grep Path:

示例输出

Path:          /data/ones/ones-installer-pkg/pkg
Path:          /data/ones/ones-installer-pkg/config
Path:          /data/ones/ones-installer-pkg/backups

如果输出结果有 /data/ones/ones-installer-pkg，则 ONES_DATA_DIR=/data/ones

如果输出结果有 /home/ones/ones-installer-pkg，则 ONES_DATA_DIR=/home/ones

2 升级操作

2.1 备份配置文件

升级前，请先执行备份文件的配置。

#进入容器后，根据版本选择如下1种备份方式即可
 ones-ai-k8s.sh

#新版本采用命令备份
make backup-config

#退出容器
exit

#FAQ：老版本如果上述命令执行报错，请手工备份如下操作代替make backup-config命令
filename=`date +"%Y%m%d-%H%M%S-$(date +%s.%6N)"`
mkdir -p config/backups/time-$filename
cp config/*.yaml config/backups/time-$filename/

2.2 备份业务数据

升级前，执行数据备份任务；如果是外置数据库，请联系客户自行备份。

ones-ai-k8s.sh

# 手动全量备份
make mysql-base-backup NAMESPACE=ones
# 如果没有开启备份任务，该命令执行会报错；测试环境请联系客户确认后可继续，正式环境请先开启备份功能

# 如果该命令执行没有报错，则查看备份日志
make logs-mysql-xbackup NAMESPACE=ones

# 看到"备份成功"日志，表示MySQL备份完成。
exit

上述备份操作不影响业务，可提前完成；下述操作将影响配置和服务，请在变更窗口内执行！

2.3 导入新镜像

执行如下命令导入新版本的镜像。注意：该操作会更新public.yaml中的版本号，执行该命令后请勿执行与升级无关的make操作。

cd  /data/upgrade/
# 请根据1.4节查询到的环境实际路径替换ONES_DATA_DIR ！！！
OFFLINE_PKG=offline_pkg_v3.14.29_from_v3.14.28.tar ONES_DATA_DIR=/data/ones bash install_linux_amd64.sh

# 升级到6.105.0以下版本需更新部署工具；升级到6.105.0及以上版本无需执行该步骤
ones-ai-k8s.sh
make setup-installer-api 

# 上述命令执行之后，installer-api 这个pod可能会销毁重建，故须退出当前会话，等待 60s 后重新进入ones-ai-k8s.sh
exit
sleep 60

2.4 初始化新配置

ones-ai-k8s.sh

make setup-ones-cluster-operator

make setup-tidb-operator

make init-config

make init-db

#  如果是集群环境，请核对如下参数
grep -i onesSystemScale config/private.yaml
onesSystemScale: 'self-hosting-single'
# 如果该参数为 self-hosting-single，请修改为 common-ha

2.5 执行数据迁移

从低于6.88.0的版本，升级到6.88.0以上版本，必须先停服、再执行数据迁移

kubectl -n ones scale --replicas=0 deploy project-api-deployment wiki-api-deployment ones-project-api-deployment 

请根据命令输出的日志继续完成升级动作,区分有迁移和无迁移两种流程

make start-migration MIGRATION_DIR=config/migration

2.5.1 有迁移时，屏幕上应该打印如下输出：

1. Get the migration pod:

    $ kubectl -n ones-system get pod -l job-name=upgrade-ones-{升级前版本后}-{升级后版本号}-mysql

2. View pod log, observe the migration progress and status:

    $ make tail-migration MIGRATION_DIR=config/migration

    If the migration is nearing completion, you will see logs similar to the following:

    [xxxx/xxx/xxx xx:xx:xx] [info] cutover preflight round x took xx.xxs, migration is nearing completion and manual confirmation can be done anytime now.

    Than you can confirm the migration, the database and services will be upgraded to the new version within a few minutes.
            
3. Confirm the migration:

    $ make confirm-migration MIGRATION_DIR=config/migration

查看迁移进度

make tail-migration MIGRATION_DIR=config/migration

当屏幕上打印类似如下输出时，表示迁移执行完成，可执行下一步的confirm操作

[xxxx/xxx/xxx xx:xx:xx] [info] cutover preflight round x took xx.xxs, migration is nearing completion and manual confirmation can be done anytime now.

上一步确认迁移完成后，执行最终确认操作

此命令会将新版本资源应用到集群中，不可逆

make confirm-migration MIGRATION_DIR=config/migration

（1）看到类似的输出，代表升级成功，继续执行2.6

2023-09-07 04:08:37,917 [INFOJ The system has been surccessfully upgraded to version v3.15.9 from v3.14.32

（2）看到类似的输出，代表本次升级有3个迁移，请参考提示命令继续执行

2026-06-25 11:44:29,240 [INFO migration segment 1/3 has been applied.
2026-06-25 11:44:29,240 [INFO You can run 'make tail-migration MIGRATION_DIR=config/migration' to watch it.

等待一会，没有输出，再次执行

make confirm-migration MIGRATION_DIR=config/migration

此时如果有上述提示，参考提示命令继续执行等待一会，没有输出，再次执行

make confirm-migration MIGRATION_DIR=config/migration

看到类似的输出代表升级成功，继续执行2.6

2023-09-07 04:08:37,917 [INFOJ The system has been surccessfully upgraded to version v3.15.9 from v3.14.32

2.5.2 没有迁移时，屏幕上应该打印如下输出：

2024-08-28 02:40:12,231 [INFO] ugrade ones version from v6.1.39 to v6.1.43
2024-08-28 02:40:12,264 [INFO] There is no need for migration.
2024-08-28 02:40:12,264 [INFO] Skip migration. Now you can continue to upgrade via 'make setup-ones'

没有迁移直接执行如下命令应用新版本镜像即可

make setup-ones

2.6 升级中间件

手工执行如下命令升级中间件，然后重启pod：

# 如果 redis/kafka/tikv 版本需升级，下述命令会弹出确认信息、输入yes即可

make setup-ones-built-in-redis

make setup-ones-built-in-kafka

make setup-ones-built-in-tikv

#FAQ：如果执行上述built命令出现如下类似报错
#The Statefulset "kafka-ha" is invalid: spec: Forbidden: updates to statefulset spec for fiels other than ......；
#请先执行 kubectl -n ones delete sts kafka-ha或者advanced-tidb-tikv/advanced-tidb-pd， 然后重新执行built命令

# 如果升级了redis/kafka/tikv任一中间件的版本，请执行如下命令重启相关应用
kubectl get pod -n ones |grep -iE 'api|wiz|platform|plugin|attach|sync|proxy' | awk '{print $1}' |xargs kubectl delete pod -n ones 

# 如果升级了Kafka，请执行如下命令重建cdc数据，再观察 cdc-connect 、kilob-sync 和etl 这几个组件是否正常 Running
make rebuild-cdc

# 检查是否有异常运行的pod
kubectl get pod -A| grep -vE  'Running|Completed'

# 如果输出结果不为空，且持续10分钟多次查询后，依然存在没有正常 Running 的pod，请联系ONES工程师处理。

# 如果输出结果为空，表示都是正常 Running、继续执行后续更新内置插件、重建索引和效能的操作。

2.7 更新内置插件

仅在 v6.18.1 及以上版本支持，安装/更新6个标品插件，根据授权决定是否启用。

make setup-ones-inner-plugins

2.8 重建效能

如果本次升级，执行了数据migration迁移操作，必须重建 Performance 数据。

2.9 重建索引

如果本次升级，执行了数据migration迁移操作，必须重建索引。

3 升级后操作

参考ONES 升级后调整。

上述操作执行完成之后系统会升级到新版本，可以访问 ONES 查看业务是否正常！

操作步骤​

1.升级准备​

1.1 升级前准备​

1.2 查看可升级版本​

1.3 准备在线服务器下载升级包​

1.4 获取当前ONES数据目录​

2 升级操作​

2.1 备份配置文件​

2.2 备份业务数据​

2.3 导入新镜像​

2.4 初始化新配置​

2.5 执行数据迁移​

2.5.1 有迁移时，屏幕上应该打印如下输出：​

查看迁移进度​

上一步确认迁移完成后，执行最终确认操作​

2.5.2 没有迁移时，屏幕上应该打印如下输出：​

2.6 升级中间件​

2.7 更新内置插件​

2.8 重建效能​

2.9 重建索引​

3 升级后操作​