跳到主要内容

标准升级指南

📘 概述​

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

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

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

⚙️ 前置条件​

✅ 环境要求​

项目要求
Kubernetes 集群v1.28+，集群处于健康状态（kubectl get nodes 全部 Ready）
Helmv3.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.16.0        v1.16.0     CSGHub charts with CE and EE.
......

2️⃣ 执行升级命令​

创建自定义资源：

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

执行升级命令：

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

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

--set global.gateway.external.domain="<your-domain>" \
--set global.gateway.tls.enabled=true \
--set global.gateway.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 用户。

  • 升级时提示 StatefulSet patch 错误

    错误提示：

    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 个历史版本以便快速回滚

📚 参考资料​