核心组件

本文列出 SupKube 三个代码库各自的组件划分，以及 Helm 安装后集群中会出现的具体资源，重点标注命名空间与权限范围方面容易踩坑的地方。

后端（supkube-backend）组件分组

分组	说明
internal/api/v1	所有 REST 接口的处理函数，按资源分文件（备份、还原、策略、存储位置、集群…）
internal/auth	认证三模式（OIDC/静态令牌/Basic）与 RBAC 权限表
internal/velerons	全局唯一的 Velero 命名空间解析（读 VELERO_NAMESPACE 环境变量）
internal/importpolicy	跨集群导入策略控制器（Continuous/Scheduled 两种模式）
internal/fingerprint	备份跨集群传递时的来源签名（HMAC-SHA256），配合导入策略的 fingerprintMode 使用
internal/advisor	两套独立评分/建议引擎：Backup Advisor 规则打分 与 还原/策略保存前的 Preflight 规则（当前 2 条规则：Azure Files 数据搬运的 IAM 权限提示、对运行中数据库做崩溃一致备份的提示）
internal/policypair	纯后台控制器，负责双模式策略"快照半区完成后自动触发导出半区"，无对外接口
internal/transform	Transform / TransformSet 的编译逻辑（封装 Velero 原生 ResourceModifierDoc）
internal/clusterhealth / internal/velerohealth	分别巡检"已注册的远端集群"与"本地 Velero 安装本身"的健康状态，均为只读
internal/gc	孤儿资源（VolumeSnapshotContent/VolumeSnapshot/PodVolumeBackup/DataUpload）清理
internal/csi	已知 CSI 驱动（Azure Disk/Files、AWS EBS、GCP PD、阿里云盘、腾讯云盘等）的 VolumeSnapshotClass 自动适配
internal/audit 与 internal/auth（审计部分）	两套彼此独立的审计记录：internal/auth/audit.go 把关键操作写入标准输出与固定命名空间 supkube 下的 Kubernetes 事件（GET /api/v1/audit-logs 读的是这一套，注意 Kubernetes 事件默认保留时间较短，不适合当长期合规记录）；internal/audit（SQLite，落盘在持久卷）是另一套独立的、面向未来长期留存场景的实现。
internal/metrics	Prometheus 指标，暴露在根路径 /metrics（不在 /api/v1 前缀下），当前主要是存活探针与许可证相关指标。
internal/vault	对接外部不可变存储服务的可选集成（默认关闭）
pkg/license	许可证 Ed25519 签名校验与状态机（详见许可证管理）

前端（supkube-frontend）结构

• src/router：路由表，除登录页外的所有页面都要求已登录；权限粒度的显隐（例如管理员专属的 Settings 标签页）在组件内部判断，不在路由层。
• src/views：一个页面一个文件；需要注意的是**"还原"没有独立可达路由**，/restores 会被重定向到 Observability 页的活动标签，实际发起还原走 Backups 页面的行内操作。
• src/api/velero.js：唯一的一个前端 API 封装文件，所有接口调用集中于此，支持通过运行时注入的 basePath 适配子路径部署。
• src/locales：仅 en.js 与 zh-CN.js 两个语言包。

Helm 安装后集群中的主要资源

先看整体拓扑，再看逐项清单：

                          ┌────────────────────────────────────────┐
     浏览器 ──── :80 ────▶│  <release>-frontend        Nginx       │
                          │  supkube.azurecr.io/frontend           │
                          │  静态资源 + 反向代理                    │
                          └───────┬───────────────┬────────────────┘
                        /api/v1/* │               │ /dex/*
                          ┌───────▼───────────────┼────────────────┐
                          │  <release>-backend    │    Go + Gin    │
                          │  supkube.azurecr.io/backend    :8080   │
                          │                       │                │
                          │  /metrics 在根路径，不在 /api/v1 下面   │
                          └───┬───────────────────┼────────────┬───┘
                              │ client-go         │            │
          ┌───────────────────▼──────┐  ┌─────────▼────────┐  ┌▼─────────────────┐
          │ Velero（内置子 Chart）    │  │ <release>-dex    │  │ supkube-local-   │
          │ Backup / Restore /       │  │ 内置身份代理      │  │ store  内置 MinIO │
          │ Schedule / BSL / VSL     │  │                  │  │ Deployment+PVC   │
          │                          │  │ auth.dex         │  │ +一次性 Job      │
          │ CRD: *.velero.io         │  │ .enabled=true    │  │ localStore       │
          └──────────────────────────┘  └──────────────────┘  │ .enabled=true    │
                                                              └──────────────────┘
          ┌──────────────────────────┐
          │ SupKube 自有 CRD          │   clusters.supkube.io
          │                          │   importpolicies.supkube.io
          └──────────────────────────┘

内置 MinIO 那个 Job 只在安装/升级后跑一次，负责建桶与配置对象锁，跑完即结束，看到它 Completed 是正常的。

资源	名称	说明
Deployment	<release>-backend、<release>-frontend	主体应用
Deployment	<release>-dex	内置 Dex 身份代理（auth.dex.enabled=true 时）
Deployment + PVC + Job	supkube-local-store*	内置 MinIO 本地备份库（localStore.enabled=true 时），Job 只在安装/升级后跑一次，负责建桶与配置 Object Lock
CRD	clusters.supkube.io	多集群注册表（Cluster），命名空间级作用域
CRD	importpolicies.supkube.io	跨集群导入策略
CRD（Velero 子 Chart带来）	backups.velero.io、restores.velero.io、schedules.velero.io、backupstoragelocations.velero.io 等	Velero 原生资源
ClusterRole + ClusterRoleBinding	<release>	详见下方权限范围说明

ServiceAccount 权限范围比想象中更宽

SupKube 后端使用的 ClusterRole 是集群范围（非按命名空间限制），除了对 Velero 相关资源的完整增删改查外，还对核心 API 组的 configmaps 与 secrets 拥有集群范围的完整增删改查权限——这是 Chart 自身注释里标注的已知技术债（计划中的 RBAC 收紧尚未落地），在做安全评审时请将其纳入威胁模型。

命名空间约定（容易踩坑，务必留意）

SupKube 对"命名空间"存在两套并行且互不知情的处理方式，二者不要混淆：

              helm install supkube -n <您选择的命名空间>
                              │
          ┌───────────────────┴────────────────────┐
          ▼                                        ▼
   轨道 A：跟随发布命名空间                 轨道 B：硬编码 "supkube"
   （config.veleroNamespace 为空时）        （写死在代码里，不跟随）
          │                                        │
          ├─ 内置 Velero                           ├─ 许可证 Secret
          │    = <您选择的命名空间>                 │    supkube-license
          │                                        ├─ 许可证状态事件
          └─ 外部 Velero                           ├─ Cluster CR
               = 字面量 "velero"                    │    + kubeconfig Secret
                                                   └─ 审计事件
          │                                        │
          └──────────────────┬─────────────────────┘
                             ▼
               只有 -n supkube 时两轨才重合

1. 随发布命名空间自动解析（config.veleroNamespace 为空时）：内置 Velero 场景下等于您 helm install -n <namespace> 选择的命名空间；外部 Velero 场景下默认为字面量 velero。
2. 硬编码为字面量 "supkube"，不跟随发布命名空间：许可证 Secret（supkube-license）与许可证状态事件、多集群注册的 Cluster CR 与其 kubeconfig Secret、以及基于 Kubernetes 事件的审计记录，这三处的命名空间都直接写死在代码里。

装到 supkube 以外的命名空间时，轨道 B 的三个子系统会静默失效——SupKube 本身照常启动、备份还原也正常，只是许可证读不到、多集群注册表读不到、审计写不进去。没有任何报错提示您装错了地方，这是最难自查的一类问题。

实践建议：始终使用 -n supkube 安装（与所有官方部署命令一致），可以让这两套逻辑的结果重合，避免任何一处踩坑。详见已知限制与产品边界。

镜像与端口

• 镜像仓库：supkube.azurecr.io/backend、supkube.azurecr.io/frontend（已开启匿名拉取）。
• 后端容器端口：8080；前端（Nginx）容器端口：80。

验证方法

# 确认关键资源都按预期出现在 supkube 命名空间
kubectl get deploy,cm,secret -n supkube
kubectl get crd clusters.supkube.io importpolicies.supkube.io

若 clusters.supkube.io、importpolicies.supkube.io 两个 CRD 均已存在，说明多集群与跨集群导入的基础设施已就绪。

相关文档

• 架构概览
• 配置总览
• 认证配置