Nexent Kubernetes 升级指南：从 PVC 备份、Helm 在线/离线升级到数据库自动迁移的完整实践

• 人工智能
• AI Agent
• Agent 编排
• 低代码
• AI 技能
• RAG

本文是使用 Helm 部署的 Nexent 平台的升级操作手册，覆盖升级前备份、在线/离线升级、数据库自动迁移原理与升级后检查四个阶段。读者将掌握如何借助仓库内置的 deploy/k8s/backup.sh 在不停 Pod 的前提下完成全量 PVC 备份，如何通过deploy.sh完成在线快进升级或离线包升级，并理解nexent-config主导的 SQL 迁移机制——这是一套可直接照做的低风险升级方案。

1. 升级前的总体原则与适用前提

本文仅适用于使用 Helm 部署的 Nexent 集群。执行升级前请确认以下几点：

• 业务低峰窗口：建议在无人使用或业务低峰时段执行，尽量缩短升级对用户的影响面。
• 备份前必须停止业务写入：包括用户操作、接口请求和定时任务等一切写路径，但不需要停止 Pod，也不要求缩容。备份脚本不会检测业务写入状态，也不会要求输入确认，因此停止写入是执行者自己的责任。
• 一致性前提：如果复制期间仍有业务写入，PostgreSQL、Elasticsearch、Redis 和 MinIO 等组件的数据可能不属于同一时间点，备份可能无法恢复。这正是脚本要求"先停写、再备份"的根本原因。
• 环境前提：执行kubectl的本地机器是备份目标，必须能够访问目标集群；默认 namespace 为nexent，应按实际环境调整。

需要说明的是，本文档配套的 Docker Compose 版本升级流程见 Docker 升级指南，本文只讨论 Kubernetes/Helm 场景。

2. 升级前检查和备份

2.1 备份命令与参数

先进入当前正在使用的 Nexent 仓库根目录；离线部署则进入上一版已解压部署包的根目录。执行：

bash deploy/k8s/backup.sh \ --backup-dir /mnt/backup/nexent \ --namespace nexent

脚本支持的全部参数如下（来自 backup.sh 的 usage 说明）：

脚本还支持环境变量NEXENT_BACKUP_TIMESTAMP（格式YYYYMMDD-HHMMSS）覆盖默认的 UTC 时间戳，用于生成备份目录名k8s-<timestamp>。

2.2 备份脚本的执行流程

从源码看，backup.sh 的main()依次执行五个阶段，每一步失败都会以[ERROR]终止：

1. 本地环境校验（validate_local_environment）：要求本地已安装kubectl、tar、base64、du、df，kubectl客户端可用且能访问目标 namespace；备份目录必须可创建、可写，且目标k8s-<timestamp>目录不存在。
2. 发现 PVC（discover_pvcs）：列出指定 namespace 中全部 PVC，所有 PVC 必须为Bound，否则在复制前输出[ERROR]并退出，避免静默漏备份。
3. 为每个 PVC 定位数据源（discover_sources/find_pvc_source）：为每个 PVC 选择一个完整挂载该卷的运行中容器。源码明确要求挂载点不能使用subPath或subPathExpr（backup.sh），否则无法保证卷内容完整性。使用自定义existingClaim时，脚本按集群中的实际 PVC 名处理，不依赖默认组件名称。
4. 测量数据量与空间（measure_sources/check_space）：通过容器内du回显每个 PVC 的未压缩数据量和总量，通过本地df -Pk检查备份目录可用空间。数据不会压缩，因此空间检查按文件原始大小计算。出现[PASS] Pre-upgrade space check passed.表示本地空间充足，脚本随后直接开始复制；空间不足时会在复制前退出。
5. 复制全部 PVC（copy_all_pvcs）：所有 PVC 复制完成后，目录k8s-<timestamp>.partial才会被重命名为k8s-<timestamp>，并输出[PASS] Backup complete: <path>。

2.3 三种数据复制路径与日志标记

复制单个 PVC 时，脚本按优先级尝试三种方式（见 copy_pvc）：

1. kubectl cp：默认优先路径，将$pod:$source_path/.复制到本地。
2. kubectl exec ... tar流式传输：kubectl cp失败且目标容器包含tar时，通过tar -C <source> -cf - . | tar -C <target> -xf -流式传输并立即在本地解包，不保留 tar 文件。
3. 逐文件流式导出：MinIO 等精简镜像不包含tar时，脚本使用容器内的 Bash 和基础 coreutils（stat、readlink、cat、base64）先枚举目录清单（区分目录/普通文件/符号链接并记录权限位），再通过kubectl exec ... cat逐文件流式导出，最后恢复目录与文件权限；该路径在文件很多时会更慢。

脚本不使用sudo，不创建临时 Pod，也不生成压缩包或 SHA-256 文件，备份内容即文件的原始拷贝。

备份目录的最外层使用 PVC 原名，例如nexent-postgresql/、nexent-workspace/、nexent-skills/以及已启用监控组件对应的 PVC 名。通过[INFO]查看来源与复制进度；只有出现[PASS] Backup complete: <path>才表示指定 namespace 中的全部 PVC 已复制完成，<path>是实际备份目录。出现[ERROR]时不要使用脚本回显的.partial未完成目录——脚本在异常退出时也会通过trap on_exit EXIT明确提示该目录"Inspect but do not use"（backup.sh）。

3. 执行升级

3.1 在线升级

在能够访问 GitHub 和所需镜像仓库的环境中，使用当前 Nexent 仓库执行在线升级。先确认当前分支和目标版本，再以快进方式更新，不要用未记录的latest代替明确版本：

git branch --show-current git pull --ff-only bash deploy.sh k8s --defaults --version X.Y.Z

• --defaults会复用已保存的 Kubernetes 部署配置并跳过交互界面。
• 升级前应确认 deploy/k8s/deploy.options 中的组件、端口策略、镜像源、持久化模式和 namespace 与原环境一致；脚本升级时以保存的配置或内置默认值重新生成 Helm values。
• 版本号X.Y.Z应替换为目标版本；未显式传入--version时，deploy/k8s/deploy.sh 会从backend/consts/const.py的APP_VERSION自动检测。

更多在线部署说明参见 Kubernetes 安装部署。

3.2 离线升级

目标集群无法访问公网镜像仓库时，按 Kubernetes 离线部署 下载与集群节点架构匹配的目标版本包，复制到能够访问目标集群的管理节点并解压到新目录：

unzip nexent-<version>-amd64.zip -d nexent-<version> cd nexent-<version>

单节点且使用 Docker 容器运行时的集群，可直接加载新包镜像并升级：

bash deploy.sh \ --reuse-from /path/to/previous/nexent \ --load-images \ --defaults \ k8s

其他单节点或多节点集群，应将新包镜像推送到集群可访问的内部仓库：

bash deploy.sh \ --reuse-from /path/to/previous/nexent \ --push-images \ --image-registry-prefix registry.example.com/nexent \ --defaults \ k8s

离线升级的两个关键参数（来自根入口 deploy.sh）：

ARM64 集群节点应使用对应的arm64包名（如nexent-<version>-arm64.zip）。

3.3 升级过程中的自动迁移

升级时由nexent-config执行数据库自动迁移，其他后端服务会等待迁移达到目标状态。这一机制在仓库中有完整的源码实现支撑：

• nexent-config 的 deployment.yaml 设置了NEXENT_SQL_STARTUP_MODE=migrate，其启动入口 start-backend.sh 会先执行run-sql-migrations.sh --migrate再启动服务。
• 而 nexent-runtime、nexent-mcp、nexent-northbound、nexent-data-process 等其他后端组件的 deployment 同样注入该变量但使用等待模式，由 run-sql-migrations.sh 的--wait轮询nexent.schema_migrations表，直到所有迁移文件都达到目标校验和才放行服务启动。

迁移执行器 run-sql-migrations.sh 的运作方式（详见 deploy/sql/migrations/README.md）：

• 以 SQL 文件名作为 migration ID，将当前文件 SHA-256 校验和记录在nexent.schema_migrations表中（包含migration_id、checksum、status、executed_at、app_version、source_file字段）。
• 文件按版本感知的文件名顺序（sort -V）执行：无记录的文件执行并记录为applied；校验和一致的文件跳过；校验和变化的文件重新执行并更新记录。
• 级联重放机制：一旦某个文件因校验和变化被重放，本次会话中其后的所有文件都会被强制重新执行（migration_force_rerun标志，见 run-sql-migrations.sh），因为前面的破坏性语句（如DROP COLUMN）可能把 schema 回退到后续文件所补偿的状态；跳过会导致数据库不一致。
• 迁移全程通过pg_advisory_lock加锁（run-sql-migrations.sh），避免多实例并发迁移冲突。
• deploy/sql/init.sql每次启动无条件执行且不参与级联，其语句必须保持幂等。

因此文档强调的"已合并的 SQL 文件不可修改、改名或删除"是一条硬约束：当前迁移文件位于 deploy/sql/migrations（v1_merged_migrations.sql、v2.0~v2.7.0各版本合并文件），即使只改动注释，也会触发级联并重放其后所有文件，在大规模合并文件上可能耗时很长。任何变更都应新增独立版本文件（如vX.Y.Z_xxx.sql）。

4. 升级后检查

检查指定 namespace 中的 Pod 状态（以下示例使用默认 namespacenexent）：

kubectl get pods -n nexent -o wide

判断标准：

• 通过：所有 Nexent Pod 均为Running，且 READY 数量符合预期（如1/1）。
• 继续等待：Pod 显示ContainerCreating——此时可能正处于镜像拉取或迁移等待阶段，升级脚本本身也会对每个工作负载执行kubectl rollout status ... --timeout=<K8S_WAIT_TIMEOUT_SECONDS>s（默认 600 秒，见 deploy/k8s/deploy.sh）。
• 不通过：Pod 显示CrashLoopBackOff、Error或长时间Pending。此时应结合 Kubernetes 安装部署 中的方法查看kubectl describe pod与kubectl logs定位问题；若迁移失败，通常需要排查nexent-config的日志与schema_migrations表状态。

5. 升级失败时的处理思路

如果升级后业务异常，需要注意：卸载与回滚操作不会自动删除备份数据。仓库的 deploy/k8s/uninstall.sh 支持--release-scope all|infrastructure|nexent精确控制卸载范围，并支持--delete-local-data true|false/--keep-local-data控制是否删除本地 PV 数据（仅 local 模式生效），默认不删除本地数据。升级前由 backup.sh 产生的k8s-<timestamp>备份目录是恢复数据的唯一可信来源，请妥善保管；k8s-<timestamp>.partial目录在任何情况下都不应作为恢复数据使用。

6. 升级清单速览

• 人工智能
• AI Agent
• Agent 编排
• 低代码
• AI 技能
• RAG