标准升级指南

📘 概述

本指南详细介绍如何在 生产环境 中对 CSGHUB 进行 安全升级。

升级过程将确保数据安全、服务连续性与最小停机时间。

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

⚙️ 前置条件

✅ 环境要求

项目	要求
Kubernetes 集群	v1.28+，集群处于健康状态（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.12.0        v1.12.0     CSGHub charts with CE and EE.
......

2️⃣ 执行升级命令

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.12.0

⚠️ 如果你修改过域名或启用了 HTTPS，请确保以下参数仍然一致：

--set global.ingress.domain="<your-domain>" \
--set global.ingress.tls.enabled=true \
--set global.ingress.tls.secretName="csghub-tls-certs"

3️⃣ 验证升级状态

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

⚡ 常见问题

Pod 一直处于 CrashLoopBackOff

请按照以下步骤排查：
- 执行kubectl describe pod <pod> -n csghub或者kubectl logs -f pod <pod> -n csghub确认失败原因
- 常见问题有镜像拉取失败，需要排查网络问题
- 依赖资源未启动，需要排查依赖资源问题
- 数据库无法连接，参考后面数据库不存在连接失败问题
Pod 连接数据库提示数据库不存在，连接失败

此问题常见于如果初始安装时未启用某个功能，但是升级时启用了此功能导致。因为数据库的创建在数据库做初始化时就已经完成，后续如果出现新的数据库目前则需要手动创建，可通过如下命令进行创建
```
kubectl exec -it csghub-postgresql-0 -n csghub -- su - postgres -lc 'psql -U csghub'
> CREATE DATABASE <DB_NAME> ENCODING UTF8 OWNER csghub;

kubectl rollout restart deploy/sts <resource> -n csghub 
```
升级后访问异常（404）

请检查所有资源是否已经就绪，尤其是 csghub-server / csghub-portal。
页面刷新提示获取 tags 失败

退出当前登录状态，重新登录 CSGHub 用户。
Error: UPGRADE FAILED: cannot patch "my-app" with kind StatefulSet: StatefulSet.apps "my-app" is invalid: spec: Forbidden: updates to statefulset spec for fields other than 'replicas', 'template', 'updateStrategy', 'persistentVolumeClaimRetentionPolicy' and 'minReadySeconds' are forbidden

此问题通常是由于版本优化重构后资源文件做了调整会导致 StatefulSets 无法正常更新，按照以下操作进行修复：
- 删除所有StatefulSets 资源
```
kubectl delete sts --all -n csghub
```
- 重新执行升级操作
```
helm upgrade --install csghub csghub/csghub \
  --namespace csghub \
  -f csghub-values-backup.yaml
```

🔒 安全升级建议

✅ 升级前在测试环境先行验证版本兼容性
✅ 保留至少 2 个历史版本以便快速回滚

📚 参考资料

官方文档：https://github.com/OpenCSGs/csghub-charts
Helm 官方指南：https://helm.sh/docs/
Kubernetes 运维文档：https://kubernetes.io/docs/tasks/administer-cluster/

📘 概述​

⚙️ 前置条件​

✅ 环境要求​

💾 升级前准备​

1️⃣ 备份现有配置​

2️⃣ 备份关键数据​

🧩 升级步骤​

1️⃣ 更新 Helm 仓库​

2️⃣ 执行升级命令​

🔄 回滚操作（如所需）​

🔍 升级验证​

⚡ 常见问题​

🔒 安全升级建议​

📚 参考资料​