标准升级指南
📘 概述
本指南详细介绍如何在 生产环境 中对 CSGHUB 进行 安全升级。
升级过程将确保数据安全、服务连续性与最小停机时间。
💡 适用范围：适用于通过 Helm Chart 部署的 CSGHUB 集群。
⚙️ 前置条件
✅ 环境要求
| 项目 | 要求 |
|---|---|
| Kubernetes 集群 | v1.33+，集群处于健康状态（kubectl get nodes 全部 Ready） |
| Helm | v3.12.0+，已配置管理权限 |
| CSGHUB 已部署 | 已通过 Helm 成功部署的运行实例 |
⚠️ 注意：升级前必须完成 数据备份 与 配置保存，避免意外数据丢失。
💾 升级前准备
1️⃣ 备份现有配置
导出当前的 Helm values 文件：
helm get values csghub -n csghub -o yaml > csghub-values-backup.yaml
2️⃣ 备份关键数据
请至少备份以下内容：
| 组件 | 备份方式 |
|---|---|
| 数据库（PostgreSQL） | 请参考数据备份恢复章节备份数据 |
| Helm Values | 已在上一步导出 csghub-values-backup.yaml |
💡 建议使用快照型备份方案（如 Ceph Snapshot / RDS Snapshot）以确保一致性。
🧩 升级步骤
1️⃣ 更新 Helm 仓库
helm repo update
确认可用版本：
helm search repo csghub/csghub --versions
示例输出：
NAME CHART VERSION APP VERSION DESCRIPTION
csghub/csghub 1.17.0 v1.17.0 CSGHub is an open-source platform designed for ...
2️⃣ 版本说明
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 接管并纳入统一管理
注意： 如果升级目标版本为 v1.17.0 或更高版本，以上脚本需要依次顺序执行。
3️⃣ 执行升级命令
执行升级命令：
helm upgrade --install csghub csghub/csghub \
--namespace csghub \
-f csghub-values-backup.yaml
如需升级到指定版本：
helm upgrade csghub csghub/csghub \
--namespace csghub \
-f csghub-values-backup.yaml \
--version 1.17.0
⚠️ 如果你修改过域名或启用了 HTTPS，请确保以下参数仍然一致：
--set global.gateway.external.domain="<your-domain>" \
--set global.gateway.tls.enabled=true \
--set global.gateway.tls.secretName="csghub-tls-certs"
4️⃣ 验证升级状态
helm status csghub -n csghub
查看 Pod 是否全部正常：
kubectl get pods -n csghub
正常情况下，所有组件应处于 Running 或 Completed 状态。
🔄 回滚操作（如所需）
若升级出现问题，可执行回滚操作：
查看历史版本：
helm history csghub -n csghub
执行回滚操作：
helm rollback csghub <revision> -n csghub
⚠️ 回滚不会自动恢复外部数据库或存储数据，如功能异常需结合数据备份一并恢复。
🔍 升级验证
升级完成后请验证以下服务状态：
| 服务 | 验证命令 / 操作 |
|---|---|
| CSGHUB 主界面 | 访问 http://csghub.example.com |
| Casdoor 控制台 | 访问 http://casdoor.example.com |
| Temporal 控制台 | 访问 http://csghub.example.com/-/temporal |
| MinIO 控制台 | 访问 http://minio.example.com:30080/console |
| Registry | 执行 docker login csghub.example.com 验证可用性 |
如需重新获取凭据，可执行：
kubectl get secret -n csghub csghub-casdoor-init \
-o jsonpath='{.data.INIT_ADMIN_USER}' | base64 -d && echo -n " / " && \
kubectl get secret -n csghub csghub-casdoor-init \
-o jsonpath='{.data.INIT_ADMIN_PASSWORD}' | base64 -d
⚡ 常见问题
- 见故障诊断
🔒 安全升级建议
- ✅ 升级前在测试环境先行验证版本兼容性
- ✅ 保留至少 2 个历史版本以便快速回滚
📚 参考资料
- 官方文档：https://github.com/OpenCSGs/csghub-charts
- Helm 官方指南：https://helm.sh/docs/
- Kubernetes 运维文档：https://kubernetes.io/docs/tasks/administer-cluster/