升级指引

升级建议：

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

保留至少 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 任务日志

v2.2.0

从 v2.2.0 开始，升级前需关注以下变更：

Dataflow Breaking Changes：

StatefulSet → Deployment 迁移 — Dataflow 工作负载从 StatefulSet 切换为 Deployment。升级前请备份 csghub_dataflow 数据库并删除旧 PVC：
```
kubectl delete pvc data-<release-name>-dataflow-0 -n csghub
```
Pre-upgrade migration Job — 新的 pre-upgrade Helm hook 会自动执行 /scripts/*_dataflow_*.sql 脚本（通过 _migrations 表幂等追踪）。初始迁移快照并清空 6 张业务表（collection_tasks, data_format_tasks, datasources, deletion_status, job, workers）。升级前必须 dump csghub_dataflow 数据库。
Redis 和 MongoDB 已移除 — Dataflow 服务不再需要 Redis 或 MongoDB，仅需 PostgreSQL。引用了 dataflow.redis.* 或 dataflow.mongo.* 的配置应移除。

Agentichub 0.6.x 配置 Schema 变更： Agentichub chart 随 csghub v2.2.0 升级至 v0.6.1。csgbot.toml 配置已重构：

[opencsg] 块重命名为 [csghub] — keys hub-base-url/base-url/mcp-gateway-url → endpoint/portal-endpoint/mcp-gateway-endpoint
[aigateway] key base-url → endpoint；新增 temperature 字段
新增块：[environment], [speech-to-text], [sandbox]（含子块）, [observability], [user-facing-errors]
删除块：[database], [external-docs], [web-search], [csghub-sandbox], [openclaw-sandbox]
agenticflow-importer 镜像从 latest 固定为 v1.0.4

注意：如果有自定义的 csgbot.config.webSearch, externalDocs 或 logging.disableGeniusChat 值，请在升级前迁移至新 schema。

新增服务（ee/saas edition）：

llmlog（ee/saas）：写入 AI Gateway LLM 调用日志到 MinIO 的工作器
fedap（saas only）：联邦适配器（端口 8099）
trustregistry（saas only）：联邦注册中心（端口 8098）

fedap、trustregistry 在 global.edition=saas 时自动启用；llmlog 在 ee/saas 时默认启用（可通过 aigateway.aigateway.llm.log.enabled=false 关闭），ce 不部署。

其他新增配置：

aigateway.moderation.llm.* — 可选的 LLM 内容安全守卫（默认模型：Qwen/Qwen3Guard-Gen-0.6B）
server.allowCpuOnGpuNodes — 控制 CPU 任务是否调度到 GPU 节点（默认：false）

v2.4.2

从 v2.4.2 开始，Agent Sandbox 引入了新的 CRD 变更。由于 Helm 升级时不会自动更新依赖组件所需的 CRDs（CustomResourceDefinitions），因此升级到 v2.4.2 前需要先手动更新 agent-sandbox 相关 CRDs。

执行以下脚本：

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

该脚本用于：

更新 agent-sandbox 相关 CRDs
确保升级到 v2.4.2 后相关组件能够正常运行

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​

v2.2.0​

v2.4.2​

4. 开始升级​

5. 回滚升级​

6. 功能验证​

1. 概述

2. 升级前准备

2.1 备份Helm配置

2.2 备份数据库

3. 前置操作

v1.16.0

v1.17.0

v2.0.0

v2.2.0

v2.4.2

4. 开始升级

5. 回滚升级

6. 功能验证