故障排查
本文汇总最常见的报错形态（认证/许可证/存储）与对应的自助诊断脚本，多数问题可以在打开工单前自行定位。
前置条件
已能通过 kubectl 访问目标集群，并有权限查看 supkube 与 Velero 所在命名空间的资源。
先确认版本与健康探针
curl -s http://<your-supkube-host>/api/v1/status
这个接口免认证，任何时候都应该能拿到 {"status":"ok", ...}；拿不到说明后端 Pod 本身不健康或网络不通，应优先排查 kubectl get pods -n supkube。
认证类错误
| HTTP 状态 | 响应体特征 | 含义 |
|---|---|---|
401 | {"error":"missing or malformed Authorization header"} | 没带 Authorization 头，或格式不对 |
401 | {"error":"invalid API token"} / {"error":"invalid token: ..."} | 令牌本身校验失败（静态令牌哈希不匹配，或 JWT 签名/过期校验失败） |
403 | {"error":"insufficient role","required":"admin","current":"editor"} | 角色不足 |
403 | {"error":"namespace not in your scope","namespace":"prod","scope":["dev"]} | editor 角色的命名空间作用域不包含目标命名空间 |
403 | {"error":"endpoint not in RBAC table (this is a SupKube bug — please report)"} | 后端 RBAC 权限表遗漏该接口，这是产品缺陷，请联系厂商并附上具体接口路径 |
详见认证配置。
许可证类错误（HTTP 402）
{ "error": "license required or expired — creating new backups is blocked; restores and read access remain available", "state": "missing" }
只会出现在新建备份、新建/触发策略这三个写操作上；查看数据、发起还原、一键快照都不受影响。排查步骤见许可证管理。
Velero 自身健康：velero-health
界面 Dashboard 与 GET /api/v1/velero-health 会展示一个只读自检结果，覆盖：Velero 主控制器就绪状态、每个 BSL 的凭据 Secret 是否存在、node-agent DaemonSet 就绪情况。这个自检从不自动修复，只做展示。
若怀疑是"BSL 凭据 Secret 建在了错误的命名空间"（历史上真实发生过、导致 Velero 卡在 Init:0/2 长达数十小时的问题），可以直接跑：
./hack/velero-preflight.sh <kube-context>
# 或检查所有已配置的 context：
./hack/velero-preflight.sh --all
它会自动发现集群中实际运行 Velero 的命名空间（不假设一定叫 velero），逐一确认 Velero Pod 是否 Running、其挂载的每个 Secret 是否确实存在于同一命名空间、以及每个 BSL 是否 Available。
卡住的备份
如果一个 Backup 长时间停留在某个中间状态无法删除，先用普通删除；仍然卡住时，使用行菜单里的"强制删除"（POST /api/v1/backups/:name/force-delete）。这个操作会跳过正常的级联 DeleteBackupRequest 流程、直接清空 finalizer，可能在对象存储上残留未清理的数据文件，仅作为紧急处理手段，不建议作为日常流程。
插件/组件状态页给出的 helm upgrade 命令对不上
Settings → 插件管理页面会展示 Velero / Dex / 本地备份库三个可开关组件的状态，并给出对应的 helm upgrade ... --set <key>=<value> 命令供管理员复制执行（后端本身不会代为执行 helm）。如果您的 Helm Release 名称不是默认的 supkube，页面里给出的命令会用错误的 Release 名称——请自行把命令中的 Release 名替换成您实际使用的名称，再执行。
日志查看器（Log Viewer）的限制
Observability → 日志标签页支持查看 backend/frontend/dex/velero/node-agent 五个固定组件的日志（这是一个写死的映射表，不能自行添加任意 Pod）。默认拉取最近 1 小时、每个 Pod 最多 500 行（可调整，单 Pod 上限 2000 行，时间跨度上限 24 小时，合并后总行数硬上限 10000 行）。这是客户端每 5 秒轮询刷新，不是服务端推送的实时流，网络较差时会有明显的刷新延迟感。
生成完整诊断包
需要联系厂商支持时，建议先自行生成诊断包，脱敏后再发送：
./hack/supkube_debug.sh -n supkube --velero-ns velero --anonymize -o ./supkube-debug
该脚本会收集 SupKube 与 Velero 两个命名空间的 Pod 描述与日志、全部 Velero 自定义资源、集群快照相关 CRD，并且只收集 Secret 的名称/类型/存在时间等元信息，绝不收集 Secret 内容；加 --anonymize 会把业务命名空间名统一替换为 ns-anon-N 形式。
安装期常见的两处 fail-fast
以下两种情况会让 helm install/helm upgrade 在渲染阶段直接失败（还没有向集群提交任何资源），报错信息里会说明原因：
- 启用了内置 Dex（
auth.dex.enabled=true）但没有设置auth.dex.publicURL。 - 没有设置
eula.accept=true。
详见在线安装。
验证方法
按上述表格或脚本定位到具体的错误类别后，重新执行触发问题的操作，确认返回结果符合预期（状态码、buildStamp、velero-health 全绿等）。