升级指引

升级建议：

升级前在测试环境先行验证版本兼容性

保留至少 2 个历史版本以便快速回滚

1. 概述

本文档详细介绍如何在 生产环境 中对 CSGHub 进行 安全升级，升级过程将严格保障数据安全、服务连续性，并最大限度缩短停机时间。

💡 适用范围：适用于通过 Helm Chart 部署的 CSGHUB 集群。

2. 升级前准备

升级前需完成配置与数据备份，避免升级过程中出现数据丢失或配置异常，具体操作如下：

2.1 备份Helm配置

导出当前 CSGHub 的 Helm 配置，用于升级时复用配置，命令如下：

helm get values csghub -n csghub -o yaml > csghub-values-backup.yaml

2.2 备份数据库

对 CSGHub 关联的数据库进行全量备份，确保数据可追溯，操作步骤如下：

# 备份数据库
kubectl exec -it csghub-postgresql-0 -n csghub -- su - postgres -lc 'pg_dumpall -U csghub -f /tmp/all_dbs.sql'
# 拷贝备份文件
kubectl cp csghub/csghub-postgresql-0:/tmp/all_dbs.sql all_dbs.sql

3. 前置操作

注意：如果升级目标版本为 v1.17.0 或更高版本，以上脚本需要依次顺序执行。

v1.16.0

从 v1.16.0 开始，系统默认弃用 ingress-nginx，改为使用 envoyGateway。

由于 Helm 升级时不会自动创建依赖组件所需的 CRDs（CustomResourceDefinitions），因此如果当前集群版本低于 v1.16.0，在升级前需要先手动安装相关 CRDs。

执行以下脚本：

curl -sSL https://charts.opencsg.com/repository/scripts/crds_install.sh | bash

该脚本用于：

安装 envoyGateway 相关 CRDs
确保升级到 v1.16.0 后相关组件能够正常运行

v1.17.0

从 v1.17.0 开始，以下组件的资源将由 CSGHub Helm Chart 统一管理：

Knative Serving
Argo Workflow
LeaderWorkSet

为了让 Helm 能够接管这些组件，升级时需要对已有资源进行 Patch，为其添加 Helm 管理相关的 metadata。

执行以下脚本：

curl -sSL https://charts.opencsg.com/repository/scripts/crds_takeover.sh | bash

该脚本用于：

为现有 Knative Serving / Argo Workflow / LeaderWorkSet 资源添加 Helm 管理信息
使这些资源能够被 CSGHub Helm Chart 接管并纳入统一管理

v2.0.0

自版本 v2.0.0 开始，内嵌的 Dataflow 将切换到 v2.0.0 版本，届时 Dataflow 依赖的任务日志存储数据库将从 MongoDB 切换到 PostgreSQL，在升级之前请执行如下迁移操作进行数据库切换（如有必要）。

迁移 Dataflow 任务日志

4. 开始升级

按照以下步骤逐步执行升级操作，确保升级过程平稳有序：

更新 Helm 仓库
```
helm repo update csghub
```

确认升级版本

helm search repo csghub/csghub --versions

执行升级

默认升级至最新版本，复用备份的配置文件。

helm upgrade csghub csghub/csghub \
  --namespace csghub \
  -f csghub-values-backup.yaml

如果升级到指定版本：

helm upgrade csghub csghub/csghub \
  --namespace csghub \
  -f csghub-values-backup.yaml \
  --version 2.0.0

等待应用就绪

# 等待 CSGHub 主要服务就绪
kubectl wait --for=condition=Ready pod -n csghub -l '!job-name'

# 等待 KnativeServing 服务就绪
kubectl wait --for=condition=Ready pod -n knative-serving -l '!job-name'

# 查看所有 pod 状态
kubectl get pods -n csghub

提示：可以通过helm status csghub -n csghub查看部署状态

5. 回滚升级

提示：如果是外置数据库请自行手动恢复。

若升级过程中出现服务异常、功能不可用等问题，可立即执行回滚操作，恢复至升级前的稳定版本，步骤如下：

查看历史版本

获取 CSGHub 的 Helm 部署历史，确认需要回滚的版本号（revision）。
```
helm history csghub -n csghub
```
执行回滚操作

将服务回滚至指定历史版本（将 revision 替换为实际版本号）。
```
helm rollback csghub revision -n csghub
```

恢复数据库

创建网络策略

临时禁止外部访问 PostgreSQL，避免恢复过程中数据冲突：

cat <<EOF | kubectl apply -f -
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: block-postgresql-access
  namespace: csghub
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/instance: csghub
      app.kubernetes.io/name: csghub
      app.kubernetes.io/service: postgresql
  policyTypes:
  - Ingress
  ingress: []
EOF

清理连接

kubectl exec -it csghub-postgresql-0 -n csghub -- su - postgres -c "psql -U csghub -c 'SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname NOT IN ('template0','template1') AND pid <> pg_backend_pid();'"

恢复数据库

# 拷贝备份到容器中
kubectl cp all_dbs.sql csghub/csghub-postgresql-0:/tmp/all_dbs.sql
# 执行导入
kubectl exec -it csghub-postgresql-0 -n csghub -- su - postgres -c 'psql -U csghub -f /tmp/all_dbs.sql'

删除网络策略

kubectl delete netpol block-postgresql-access -n csghub

6. 功能验证

升级（或回滚）完成后，需访问 CSGHub 页面，验证以下核心功能是否正常，确保升级无异常：

页面正常加载，无报错信息；
用户登录、权限管理功能正常；
模型推理、数据管理等核心业务功能正常；
关联的外置组件（数据库、对象存储等）连接正常。

1. 概述​

2. 升级前准备​

2.1 备份Helm配置​

2.2 备份数据库​

3. 前置操作​

v1.16.0​

v1.17.0​

v2.0.0​

4. 开始升级​

5. 回滚升级​

6. 功能验证​