ONES 升级前检查

1 检查说明

本文用于在执行 ONES 生产环境升级前，判断当前环境是否具备升级条件。升级前检查应形成明确结论：通过、需整改后再升级、暂停升级。

正式环境升级前，必须完成本文所有阻断项检查。任一阻断项不通过时，不建议继续升级，应先完成整改、备份或兼容性确认。

2 基础信息确认

升级前先确认如下信息，避免在维护窗口内临时补充材料：

信息	说明
当前版本	记录当前 ONES 版本和底座类型
目标版本	记录目标 ONES 版本、升级包名称和来源
升级窗口	明确开始时间、预计耗时、业务影响范围
回退方案	明确回退判断条件、回退负责人和客户确认人
备份责任人	内置数据库由 ONES 执行备份；外置数据库、外置存储由客户确认备份
外置组件清单	记录 MySQL、Redis、Kafka、对象存储、NFS、镜像仓、前置网关等外置依赖

可执行如下命令记录当前版本和数据目录：

# 进入运维容器
ones-ai-k8s.sh

# 查看当前配置版本信息
head config/public.yaml

# 退出运维容器
exit

# 查看当前 ONES 数据目录
kubectl -n ones-installer describe deploy installer-api | grep Path:

3 服务状态检查

升级前应先确认当前服务本身健康。如果服务已经异常，应先排查恢复，再判断是否可以升级。

# 节点状态
kubectl get node

# ONES 业务 Pod
kubectl -n ones get po

# 快速筛选异常 Pod
kubectl -n ones get po | grep -viE "Running|Completed"
kubectl get po -A | grep -viE "Running|Completed"

# 快速筛选异常event
kubectl get event -A 

通过标准：

• 计划承载 ONES 的节点均为 Ready。
• ones 命名空间无持续异常 Pod。
• 不存在持续增长的 RESTARTS。
• 业务入口、核心页面或版本接口可访问。

异常处理：

• 出现 Pending：优先检查资源不足、PVC、节点污点或调度限制。
• 出现 ImagePullBackOff：优先检查镜像仓、镜像名和仓库凭证。
• 出现 CrashLoopBackOff：优先检查配置、依赖服务、健康探针和应用日志。
• 出现 OOMKilled 或 Evicted：优先检查内存限制、节点资源和磁盘压力。

更多排查方法可参考ONES系统后端服务Checklist。

4 磁盘空间检查

检查系统盘、数据盘、索引盘和备份目录所在分区的空间使用率。

# 查看磁盘空间和文件系统类型
df -hT

# 常见目录单独确认
df -hT /
df -hT /data
df -hT /data/ones
df -hT /data/ones/ones-local-storage/tidb

通过标准：

• 系统盘、数据盘、索引盘使用率均低于 80%。
• 升级包、配置备份、日志、镜像导入和临时文件有足够空间。

阻断条件：

• 任一关键分区使用率超过 80%，应延期升级，先清理临时文件或扩容。
• 系统盘空间不足时，可能出现 The node was low on resource: ephemeral-storage 等临时空间不足报错。
• 系统盘或数据盘使用率达到 85% 及以上时，应优先扩容，不建议继续执行升级。

5 磁盘 I/O 检查

磁盘性能会直接影响镜像导入、数据库备份、数据迁移、索引重建和升级耗时。升级前应重新确认正式环境的磁盘 I/O。

参考环境要求中的磁盘 I/O 标准：

磁盘	最低要求
系统盘	读 IO 不低于 30MB/s，写 IO 不低于 10MB/s
数据盘	读 IO 不低于 30MB/s，写 IO 不低于 12MB/s
索引盘	读 IO 不低于 40MB/s，写 IO 不低于 15MB/s
NFS	读 IO 不低于 15MB/s，读延时小于 15ms；写 IO 不低于 6MB/s，写延时小于 12ms

# Ubuntu 示例，其他系统请自行安装 fio
apt install fio

# 在对应挂载目录下执行测试：
# cd /                         # 系统盘
# cd /data                     # 数据盘
# cd /data/ones/ones-local-storage/tidb  # 索引盘
# cd /nfstest                  # NFS 临时挂载目录
fio --randrepeat=1 --ioengine=libaio --direct=1 --group_reporting --name=test --filename=random_read_write.fio --bs=16k --iodepth=64 --size=8GB --time_based --runtime=120 --ramp_time=10 --readwrite=randrw --rwmixread=75

# 测试后删除临时文件
rm random_read_write.fio

阻断条件：

• 系统盘、数据盘、索引盘任一项不满足最低 I/O 要求。
• NFS 延时或吞吐不满足要求，且当前环境依赖 NFS 承载业务数据。
• 磁盘性能明显衰退，导致备份、镜像导入或数据库操作耗时异常。

处理建议：

• 更换更高性能磁盘。
• 为索引数据提供独立索引盘。
• 为备份任务提供独立备份机或外置存储。
• 将测试结果提供给 ONES 工程师进一步确认。

6 CPU/内存检查

根据ONES 私有部署环境要求核对授权人数、部署模式和服务器规格，确认 CPU/内存满足目标版本运行要求。

# 查看主机 CPU 和内存
lscpu
free -h

# 查看节点资源，集群支持 metrics-server 时可执行
kubectl top node
kubectl -n ones top po

通过标准：

• CPU、内存不低于当前组织规模对应的环境要求。
• 升级前无持续 CPU、内存高水位。
• 关键业务 Pod 无持续 OOM、频繁重启或资源限制过低问题。

阻断条件：

• 服务器规格低于授权人数对应的环境要求。
• 关键服务存在持续 OOMKilled、频繁重启或资源耗尽。
• 升级前已经存在明显资源瓶颈。

处理建议：

• 先请客户扩容服务器资源。
• 对大规格环境，联系 ONES 工程师评估 Pod 资源配置优化。

7 数据盘/备份盘检查

生产环境应避免业务数据和备份任务争用同一块磁盘或同一套 I/O 资源。

# 查看挂载关系
findmnt

# 查看关键目录所在分区
df -hT /data
df -hT /data/ones
df -hT /data/ones/minio

通过标准：

• 生产环境备份数据存放在独立备份机、独立磁盘或外置对象存储中。
• K3s 集群环境采用符合环境要求的应用和存储分离方案。

阻断条件：

• 生产环境备份盘和数据盘未分离。
• 备份任务与业务数据共用同一块高压力磁盘。
• K3s 集群环境未采用标准的本地存储 + NAS，或本地存储 + NAS + OSS 的应用和存储分离方案。

处理建议：

• 暂缓升级，向客户说明性能冲突、稳定性和单点风险。
• 请客户提供独立备份机、独立备份盘或外置对象存储。
• 存储架构不符合要求时，先完成存储整改或由 ONES 工程师评估风险。

8 数据备份检查

升级前必须确认数据备份可用。仅有备份配置不等于备份成功，应检查最近一次备份结果或手动触发一次备份。

8.1 内置 MySQL

参考备份数据，确保最后一次备份成功。

ones-ai-k8s.sh

# 查看备份日志
make logs-mysql-xbackup NAMESPACE=ones

exit

通过标准：

• 备份日志中可看到最近1次的备份成功信息。
• 备份对象存储或 MinIO 可访问，Bucket、Endpoint、凭证和 DNS 正常。

如果命令报错：

• 测试环境：联系客户确认风险后再决定是否继续。
• 正式环境：先开启或修复备份功能，备份成功后再升级。

8.2 外置数据库

如果使用外置 MySQL 或其他外置数据库，ONES 不负责该数据库的备份恢复。升级前必须由客户完成数据库备份、快照或同等级保护措施。

升级记录中至少保留如下信息：

• 外置数据库类型、版本和地址。
• 备份方式：数据库备份、云盘快照、存储快照或客户自有备份系统。
• 备份完成时间。
• 客户确认人。
• 恢复责任人和恢复入口。

未取得客户备份确认前，不建议执行正式环境升级。

8.3 附件、Wiki、插件和审计数据

根据当前存储模式确认备份责任：

• 附件、Wiki、插件等存储在本地时，需确认附件和插件备份已开启且最近一次备份成功。
• 存储外置到 OSS 或 NFS 时，客户需自行确认外置存储的数据安全、备份和恢复能力。
• ClickHouse 或 Kafka 审计日志备份需按当前版本对应机制确认是否正常。

9 K3s 版本、证书和 Pod 容量检查

执行如下 3 项检查，满足任一条件时，需在版本升级前执行Linux单机单独重装k3s或联系 ONES 工程师确认处理方案。

# 1. 检查 K3s 版本
kubectl get node -o wide

# 2. 检查 K3s 内置证书有效期
find /var/lib/rancher/k3s/server/tls/ -maxdepth 1 -name "*.crt" -exec openssl x509 -enddate -noout -in {} \;

# 3. 检查节点可承载 Pod 数量
kubectl describe node | grep -i pods

需处理的情况：

• K3s 版本为 v1.25。
• K3s 内置证书为 1 年有效期，存在临近过期风险。
• 节点可承载 Pod 数量为 110，可能无法满足升级后 Pod 数量增长。

10 配置文件重复项检测

如果 config/private.yaml 存在重复配置项，升级命令可能报错或配置生效结果不符合预期。

ones-ai-k8s.sh

# 检查 private.yaml 是否存在重复 key
grep -o '^[^:]\+' config/private.yaml | sort | uniq -d

exit

通过标准：

• 命令无输出，表示未发现重复 key。

如果有输出：

• 暂停升级。
• 人工确认重复配置项的正确值。
• 清理重复项后再次执行检查。

11 影子表清理评估

升级产生的影子表会增加数据库磁盘占用，并可能拉长备份时间。升级前应根据数据量、磁盘空间和备份耗时判断是否需要清理。

建议清理的情况：

• 数据盘空间接近 80%。
• MySQL 备份耗时明显增加。
• 历史多次升级后未清理影子表。
• 客户数据量较大，升级窗口对备份耗时敏感。

清理方法参考清理升级产生的影子表。

12 外置组件兼容性确认

对于外置 MySQL、Kafka、Redis等场景，升级前需确认目标版本兼容性和连通性。

建议记录如下信息：

外置组件	需确认内容
MySQL	数据库版本、参数、字符集、GTID、binlog、备份恢复责任、建库建表的权限
Kafka	版本、Topic、权限、网络连通性、消息保留策略
Redis	版本、部署模式、认证方式、连通性

阻断条件：

• 目标 ONES 版本与外置组件版本未完成兼容性确认。
• 外置数据库或外置存储责任边界未与客户确认。
• 关键外部依赖网络不通或权限不足。

13 升级放行标准

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

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

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