跳到主要内容

故障排查

1. http: server gave HTTP response to HTTPS client​

CSGHub 默认安装使用不安全的 registry（即上面提到的：<domain or IPv4>:5000），需要确保 Kubernetes 可以从这个 registry 拉取镜像。因此在 Kubernetes 的每个节点上需做如下配置：

  1. 配置前请确认配置文件 /etc/containerd/config.toml 是否存在，若不存在，可以使用以下命令创建。
mkdir -p /etc/containerd/ && containerd config default >/etc/containerd/config.toml

  1. 配置 config_path

    • Containerd 1.x

      version = 2

      [plugins."io.containerd.grpc.v1.cri".registry]
           config_path = "/etc/containerd/certs.d"

    • Containerd 2.x

       version = 3

       [plugins."io.containerd.cri.v1.images".registry]
            config_path = "/etc/containerd/certs.d"

  2. 配置 hosts.toml

    # 创建 Registry 配置目录
    mkdir /etc/containerd/certs.d/<domain or IPv4>:5000

    # 定义配置
    cat >/etc/containerd/certs.d/<domain or IPv4>:5000/hosts.toml <<EOF
    server = "http://<domain or IPv4>:5000"

    [host."http://<domain or IPv4>:5000"]
       capabilities = ["pull", "resolve", "push"]
       skip_verify = true
       plain-http = true
    EOF

  3. 重启 containerd 服务

    systemctl restart containerd

2. tcp: lookup casdoor.example.com on 10.43.0.10:53: no such host​

此问题是由于集群无法解析域名，如果是公有域名请配置域名解析，如果是自定义域名请配置 CoreDNS 和 Hosts 解析。CoreDNS 解析配置方式如下：

# 添加自定义域名解析
$ kubectl apply -f - <<EOF
apiVersion: v1
kind: ConfigMap
metadata:
  name: coredns-custom
  namespace: kube-system
data:
  example.server: |
    example.com {
      hosts {
        172.25.11.131 csghub.example.com csghub
        172.25.11.131 casdoor.example.com casdoor
        172.25.11.131 registry.example.com registry
        172.25.11.131 minio.example.com minio
        172.25.11.131 temporal.example.com temporal
        172.25.11.131 starship.example.com starship
        172.25.11.131 starship-api.example.com starship-api
      }
    }
EOF

# 更新 coredns pods
$ kubectl -n kube-system rollout restart deploy coredns

3. ssh: connect to host csghub.example.com port 22: Connection refused​

此问题常由于 gitlab-shell job 执行失败导致，出现此问题请按照如下方式进行排查：

  1. 查看

    $ kubectl get cm csghub-ingress-nginx-tcp -n csghub -o yaml
    apiVersion: v1
    data:
      "22": default/csghub-gitlab-shell:22
    ......

    确认 22 端口对应的服务名是否正确。

  2. 如果不正确手动进行修改

    $ kubectl -n csghub edit configmap/csghub-ingress-nginx-tcp
    apiVersion: v1
    data:
      "22": csghub/csghub-gitlab-shell:22

    # 更新 ingress-nginx-controller
    $ kubectl rollout restart deploy csghub-ingress-nginx-controller -n csghub

4. 如何禁用多源同步并清理已经同步的数据​

CSGHub 默认启动会开启多源同步，但是在某些情况下可以能需要禁用多源同步仅做本地模型的托管，因此就需要禁用多源同步并且需要清楚已经同步到本地的多源同步列表数据。具体操作如下：

  • Docker

    • 添加如下配置

      services:
        csghub:
          image: registry.opencsg.com/opencsghq/omnibus-csghub:<version>
          environment:
            CSGHUB_OMNIBUS_CONFIG: |
              csghub:
                external_url: "http://csghub.example.com"
              ......
              server:
                multi_sync:
                  enabled: false   # 禁用多源同步
              ......

    • 应用配置

      docker compose up -d

    • 清理多源同步数据

      docker exec -it omnibus-csghub-1 csghub-psql "SELECT cleanup_multi_sync_data();"

  • Helm Chart

    • v1.10.0 以后版本

      helm upgrade --install csghub csghub/csghub \
        ......
        --set csghub.server.multiSync.enabled=false \
        ......

    • v1.10.0 及以前版本

      helm upgrade --install csghub csghub/csghub \
        ......
        --set csghub.server.environments.STARHUB_SERVER_MULTI_SYNC_ENABLED=false \
        ......

    • 清理多源同步数据

      kubectl exec -it pod/csghub-postgresql-0 -n csghub -- su - postgres -lc "psql -d csghub_server -c 'SELECT cleanup_multi_sync_data();'"

5. failed to create pull mirror in mirror server: rpc error: code = PermissionDenied desc = permission denied​

创建镜像仓库失败，排查 Gitaly 令牌是否正确。

6. failed to set rlimit for open files. Try starting as root or requesting smaller maxconns value​

此问题是问题机器的配置或设置不足以支持过多的 loki 连接，尝试减低连接数设置即可，操作如下：

--set loki.chunksCache.connectionLimit=1000 --set loki.resultsCache.connectionLimit=1000

7. database "csghub_dataflow" does not exists​

此问题是因为在 csghub 应用初始化安装的饰扣，postgresql.databases列表中并没有包含数据库csghub_dataflow，手动创建即可：

kubectl exec -it csghub-postgresql-0 -n csghub -- su - postgres -lc 'psql -U csghub'

CREATE DATABASE csghub_dataflow ENCODING UTF8;

等待 Pod 自动重建或者手动快速重建。

kubectl rollout restart sts csghub-dataflow -n csghub

8. After upgrading, refreshing the page prompts 'Unauthorized'.​

请尝试登出后重新登录。

9. XNet 始终处于 Init 0/2 初始化等待状态​

此问题是由于 XNet 服务需要有自己的数据库，但是 postgresql 数据库的创建仅在数据库初始化时有效，因此需要手动创建数据库。

kubectl exec -it csghub-postgresql-0 -n csghub -- su - postgres -lc 'psql -U csghub -d csghub_server'

CREATE DATABASE csghub_xnet OWNER csghub;

10. Failed to allocate directory watch: Too many open files​

此问题是由于操作系统内核参数设置过低导致。通过以下调整后重启 Pod。

# 查看当前内核参数设置
sysctl fs.inotify.max_user_instances

# 修改内核参数
echo "fs.inotify.max_user_instances = 256" >> /etc/sysctl.conf

# 生效内核参数
sysctl -p

重建 Pod 即可。

11. Error checking push permissions -- make sure you entered the correct tag name, and that you are authenticated correctly.​

此问题是由于 Space 无法正常连接到容器镜像仓库，常见原因是更换过 csghub 的访问方式（例如：修改过主域名，修改过服务的类型，NodePort 和 LoadBalancer 的更换），导致默认创建的 docker registry secret 和实际不符合无法完成验证。

此种情况通常由两种解决方案：

方式一：

因为 docker registry secret 是通过 auto configure job 进行创建的，因此修改如下参数可以修改 secret 的更新逻辑。

如果你的版本是v1.12.0及以上，可以通过修改--set runner.kymlMode=update进行修复。

方式二：

任何版本都可以使用此种方式。

kubectl delete secret csghub-docker-credentical -n spaces

然后重新执行 helm upgrade --install 操作。

除此之外如果是 insecure registry 还需要同步修改 containerd 的配置。

12. Failed to upload object: failed to list object parts: The specified key does not exist.​

{"time":"2026-01-15T04:27:35.707998143Z","level":"ERROR","msg":"failed to download and upload lfs file","error":"failed to upload object: failed to list object parts: The specified key does not exist.","workerID":1,"error":"failed to upload object: failed to list object parts: The specified key does not exist.","sourceURL":"https://sync.opencsg.com/models/AIWizards/DeepSeek-R1-Block-INT8.git","repoPath":"CSG_AIWizards/DeepSeek-R1-Block-INT8","repoType":"model","pointer":{"oid":"4bf319deea1abe908bfb1ed8737e2247d6fe6846647443985cfcff5cf6d67457","size":4302380984,"download_url":"https://opencsg-gitea-lfs.oss-cn-beijing.aliyuncs.com/lfs/4b/f3/19deea1abe908bfb1ed8737e2247d6fe6846647443985cfcff5cf6d67457?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=LTAI5tH6mgHpNxCBvEYyu9ov%2F20260115%2Fcn-beijing%2Fs3%2Faws4_request&X-Amz-Date=20260115T042735Z&X-Amz-Expires=259200&X-Amz-SignedHeaders=host&X-Amz-Signature=d0f81d4f3e3366b1fbc4c69082a9849dc1ed41d5730fa87f58115da21cb4d258"}}

此问题是由于 Redis 缓存污染导致多源同步同步 LFS 文件时异常。手动清理下缓存：

redis-cli --scan --pattern 'upload-id*' | xargs -r redis-cli del

or

redis-cli

EVAL "
local cursor = '0'
repeat
  local res = redis.call('SCAN', cursor, 'MATCH', 'upload-id*', 'COUNT', 100)
  cursor = res[1]
  for _, key in ipairs(res[2]) do
    redis.call('DEL', key)
  end
until cursor == '0'
return 'done'
" 0

然后重新同步项目或者点击重试。

13. Failed to upload xorb: inconsistent data: xorbID exists in DB but missing in S3: The specified key does not exist.​

此问题是由于 xnet 元数据信息和对象存储数据不一致导致。

我们将通过 sdk 在后面提供一致性校验和修复方案

14. Error: UPGRADE FAILED: Unable to continue with update: CustomResourceDefinition "xxxxx" in namespace "" exists and cannot be imported into the current release: invalid ownership metadata​

详细报错日志如下：

Error: UPGRADE FAILED: Unable to continue with update: CustomResourceDefinition "clusterworkflowtemplates.argoproj.io" in namespace "" exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to "csghub"; annotation validation error: missing key "meta.helm.sh/release-namespace": must be set to "csghub

此问题是由于从版本v1.17.0开始，组件Argo Workflow/Knative Serving/LeaderWorkSets纳入 CSGHub Helm Chart 自管理，替换了之前 Job 中通过kubectl创建的方式，因为 CRDs 资源之前的管理方式并不是 Helm，且严格意义上并不属于csghub发布，因此需要通过执行以下脚本修改 CRDs 由 CSGHub Helm Chart 进行管理。

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

15. Warning: unrecognized format "string"​

Argo Workflow 的 CRD 资源创建合规问题，并不影响功能的使用，忽略即可。

16. Knative Serving Pods CrashLoopBackOff​

现象：

  • knative-serving namespace 下组件 Pod 持续 CrashLoopBackOff

  • knative-operator 日志报错：

    failed to apply non rbac manifest:
    failed calling webhook "config.webhook.serving.knative.dev":
    dial tcp <webhook-service-ip>:443: connect: connection refused

原因：

knative-serving 的 webhook 服务未正常启动或处于异常状态，导致 Operator 在应用 Serving 配置时调用 config.webhook.serving.knative.dev 失败。

Webhook 未就绪会造成 资源无法正确 reconcile，相关 Pod 反复重启进入 CrashLoopBackOff。

常见原因：

  • knative-serving namespace 内资源状态不一致（历史残留资源 / webhook 证书异常）
  • Webhook / cert-controller 初始化失败
  • Helm 与旧资源状态冲突

解决方案：

清理 knative-serving 命名空间并重新部署：

# 注意：csghub 创建的实例会出现暂时无法访问
kubectl delete ns knative-serving --force

# 重新执行 helm upgrade
helm upgrade --install csghub csghub/csghub -n csghub --create-namespace

重新部署后 webhook 正常启动，Operator 可以成功 apply manifests，Pod 恢复正常运行。

17. cluster resources unhealthy, last update time​

现象：

前端页面提示集群资源不可用。

原因：

集群状态过期，即 runner 和 csghub 之间心跳异常。通常需要排查 runner 的日志。

常见原因：

  • Runner 配置的STARHUB_SERVER_API_TOKEN和 Server 的不一致。
  • Runner 配置的 externalUrl 不可达。

解决方案：

  • 更新 Runner 并指定正确的值。

18. Pods always CrashLoopBackOff​

请按照以下步骤排查：

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

19. Pod 连接数据库提示数据库不存在，连接失败​

此问题常见于如果初始安装时未启用某个功能，但是升级时启用了此功能导致。因为数据库的创建在数据库做初始化时就已经完成，后续如果出现新的数据库目前则需要手动创建，可通过如下命令进行创建

kubectl exec -it csghub-postgresql-0 -n csghub -- su - postgres -lc 'psql -U csghub -d postgres'
> CREATE DATABASE <DB_NAME> ENCODING UTF8 OWNER csghub;

kubectl rollout restart deploy/sts <resource> -n csghub

20. 升级后访问异常（404）​

请检查所有资源是否已经就绪，尤其是 csghub-server/csghub-portal。

21. 页面刷新提示获取 tags 失败​

退出当前登录状态，重新登录 CSGHub 用户。

22. UPGRADE FAILED: cannot patch "my-app" with kind StatefulSet​

现象：

Error: UPGRADE FAILED: cannot patch "csghub-dataflow" with kind StatefulSet: StatefulSet.apps "csghub-dataflow" 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

23. Failed to get k8s version kubernetes version "1.32.0" is not compatible, need at least "1.33.0-0" (this can be overridden with the env var "KUBERNETES_MIN_VERSION"​

此问题是由于升级后的 Knative Serving 版本过高，需要 Kubernetes 版本不低于 v1.33.0，如果出现此问题可以通过设置如下参数进行兼容运行：

--set runner.knative.knative_operator.kubernetes_min_version="v1.32.0"

如以上参数无效可以通过如下命令临时解决：

kubectl get deploy -n knative-serving | awk 'NR>1{print $1}' | xargs -n 1 kubectl patch deploy -n knative-serving --type json -p '[{"op":"add","path":"/spec/template/spec/containers/0/env/-","value":{"name":"KUBERNETES_MIN_VERSION","value":"v1.32.0"}}]'

24. Failed to initialize NVML: ERROR_LIBRARY_NOT_FOUND​

现象：

安装 volcano-device-plugin 时 DaemonSet 无法就绪。

Loading NVML
Starting pprof server, listen on port 6060
Failed to initialize NVML: LIBRARY_NOT_FOUND.
If this is a GPU node, did you set the docker default runtime to `nvidia`?
......
failed to initialize NVML:ERROR_LIBRARY_NOT_FOUND

原因：

volcano-device-plugin 未找到默认的 runtimeClass。

解决方案：

编辑文件 volcano-device-plugin.yaml +187

      runtimeClassName: nvidia

然后重新应用资源即可。

25. Unable to enable MIG Mode for GPU xxxx: Not Supported​

Supported GPUs

26. Hook post-upgrade csghub/charts/runner/templates/knative-serving.yaml failed: object is being deleted: knativeservings.operator.knative.dev "knative-serving" already exists​

现象：

helm upgrade 升级报错：

level=WARN msg="upgrade failed" name=csghub error="post-upgrade hooks failed: warning: Hook post-upgrade csghub/charts/runner/templates/knative-serving.yaml failed: object is being deleted: knativeservings.operator.knative.dev \"knative-serving\" already exists"
Error: UPGRADE FAILED: post-upgrade hooks failed: warning: Hook post-upgrade csghub/charts/runner/templates/knative-serving.yaml failed: object is being deleted: knativeservings.operator.knative.dev "knative-serving" already exists

原因：

CSGHub Helm Chart bugs，由于 KnativeServing 资源的触发创建条件异常导致，已于 2.0.0 中修复。

解决方案：

手动删除 KnativeServing 资源。

kubectl delete KnativeServing -n knative-serving --force

或者升级到版本 2.0.0。

27. Error: failed to init migration worker: failed to create migration activities: failed to init xorb component: failed to check xorb bucket:csghub-xnet existence: Access Denied.​

现象：

Defaulted container "xnet" out of: xnet, wait-for-postgresql (init), wait-for-redis (init), wait-for-temporal (init)
init logger, level: INFO, format: json
{"time":"2026-04-04T13:21:27.563481199Z","level":"INFO","msg":"database select DB","type":"relational"}
{"time":"2026-04-04T13:21:27.563523995Z","level":"INFO","msg":"init database connection","dialect":"pg"}
{"time":"2026-04-04T13:21:27.592350738Z","level":"INFO","msg":"run migration"}
{"time":"2026-04-04T13:21:27.609197605Z","level":"INFO","msg":"there are no new migrations to run (database is up to date)"}
{"time":"2026-04-04T13:21:27.609208784Z","level":"INFO","msg":"migrated to nil"}
{"time":"2026-04-04T13:21:27.609415485Z","level":"INFO","msg":"runner migration worker"}
{"time":"2026-04-04T13:21:27.609424348Z","level":"INFO","msg":"start temporal workflow"}
{"time":"2026-04-04T13:21:27.752408138Z","level":"INFO","msg":"[nats] message queue initialized successfully"}
Error: failed to init migration worker: failed to create migration activities: failed to init xorb component: failed to check xorb bucket:csghub-xnet existence: Access Denied.

原因：

此现象多见于使用阿里云OSS对象存储参数指定错误导致。

解决方案：

按照如下格式指定对象存储连接。

  --set global.objectStore.enabled=false \
  --set global.objectStore.external.endpoint="https://oss-cn-shenzhen-internal.aliyuncs.com" \
  --set global.objectStore.external.region="cn-shenzhen" \
  --set global.objectStore.external.encrypt=false \
  --set global.objectStore.external.secure=true \
  --set global.objectStore.external.pathStyle=false \

28. UPGRADE FAILED: conflict occurred while applying object /knative-serving /v1, Kind=Namespace​

现象：

level=WARN msg="upgrade failed" name=csghub error="conflict occurred while applying object /knative-serving /v1, Kind=Namespace: Apply failed with 1 conflict: conflict with \"manifestival\" using v1: .metadata.labels.app.kubernetes.io/name && conflict occurred while applying object /knative-serving-operator-aggregated-stable rbac.authorization.k8s.io/v1, Kind=ClusterRole: Apply failed with 1 conflict: conflict with \"clusterrole-aggregation-controller\": .rules"
Error: UPGRADE FAILED: conflict occurred while applying object /knative-serving /v1, Kind=Namespace: Apply failed with 1 conflict: conflict with "manifestival" using v1: .metadata.labels.app.kubernetes.io/name && conflict occurred while applying object /knative-serving-operator-aggregated-stable rbac.authorization.k8s.io/v1, Kind=ClusterRole: Apply failed with 1 conflict: conflict with "clusterrole-aggregation-controller": .rules

原因：

高版本 Kubernetes（例如 1.34+）默认开启了 SSA（Server-Side Apply），Helm 在应用资源时采用严格的字段校验，导致与旧资源字段冲突。

此问题将在 2.0.1+ 版本中修复。

临时解决方案：

使用 --server-side=false 参数禁用 Server-Side Apply：

helm upgrade --install csghub csghub/csghub -n csghub --create-namespace --server-side=false

29. csghub-agenticflow 初始化容器 wait-for-postgresql 一直未完成​

现象：

agenticflow 的初始化容器 wait-for-postgresql 一直处于等待状态，无法完成初始化。

原因：

agenticflow 服务有自己的数据库，数据库名为 csghub_agenticflow，但是 postgresql 数据库的创建仅在数据库初始化时有效，因此需要手动创建数据库。

解决方案：

手动创建 csghub_agenticflow 数据库：

kubectl exec -it csghub-postgresql-0 -n csghub -- su - postgres -lc 'psql -U csghub'
CREATE DATABASE csghub_agenticflow;

等待 Pod 自动重建或者手动快速重建：

kubectl rollout restart deploy csghub-agenticflow -n csghub

30. failed to upload object: failed to list object parts: The specified upload does not exist​

现象：

多源同步 LFS 文件失败，日志报错：

fail to download and upload lfs files: failed to upload object: failed to list object parts: The specified upload does not exist. The upload ID may be invalid, or the upload may have been aborted or completed.

原因：

Redis 中残留了无效的分片上传记录（upload-id），导致对象存储认为上传会话已失效。

临时解决方案：

登录 Redis 容器，清理对应模型路径的残留上传 ID：

redis-cli --scan --pattern "upload-id-models/tencent/HunyuanOCR-*"

redis-cli --scan --pattern "upload-id-models/tencent/HunyuanOCR-*" | xargs redis-cli DEL

清理完成后重新触发同步任务。

31. Jump-to-Studio 接口返回 400 / Envoy Gateway 拒绝含下划线的 Header​

现象：

调用 /api/v1/dataflow/studio/jump-to-studio 接口时，请求被 Envoy Gateway 拒绝，返回：

{
  "response_code": 400,
  "response_code_details": "http1.unexpected_underscore",
  "response_flags": "DPE"
}

原因：

该接口的客户端请求中携带了自定义 header user_name，其名称包含下划线字符。Envoy Gateway 默认将 headers_with_underscores_action 设置为 REJECT_REQUEST，导致请求在 codec 层被直接拒绝，无法到达后端服务。

参考：Envoy Gateway Issue #8351

排查步骤：

  1. 确认错误类型

    在 access log 中查找以下特征：

    "response_code": 400,
    "response_code_details": "http1.unexpected_underscore",
    "response_flags": "DPE"

    DPE（Downstream Protocol Error）表示请求在协议层被拒绝。

  2. 找出含下划线的 Header

    确认问题 header 为 user_name。

解决方案：

配置 ClientTrafficPolicy 允许下划线 Header

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: ClientTrafficPolicy
metadata:
  name: allow-underscore-headers
  namespace: csghub
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: listeners
    sectionName: http
  headers:
    withUnderscoresAction: Allow

32. ce 版用户管理无法创建/删除用户​

现象：

在 Casdoor 用户管理中创建新用户或删除用户时，提示操作成功，但实际并未生效。

原因：

ce 版安装后，内置的 OpenCSG 组织默认开启了软删除（Soft deletion），导致用户删除、新建操作被标记而非真正执行。

解决方案：

  1. 以 admin 用户登录 Casdoor，密码通过以下命令获取：

    docker exec -it csghub-omnibus cat /etc/csghub/init_root_password

  2. 进入 组织管理，找到 Built-in Organization 并点击进入

  3. 找到 Organizations 选项卡，点击组织 OpenCSG 的 Edit 按钮

  4. 关闭 Soft deletion 开关

  5. 点击 Save & Exit 保存

关闭软删除后，重新执行创建/删除操作即可正常生效。