📚 课程目录第4章平台门户选型与部署

4. 平台门户选型与部署：选择 Backstage 作为门户，使用 Helm 部署并配置基本插件

在云原生安全治理体系中，平台门户是开发者和平台团队交互的统一入口。本章聚焦于选择 Backstage 作为平台门户，并通过 Helm 完成其部署与基础插件配置。Backstage 由 Spotify 开源，采用插件化架构，天然适合集成 Calico 网络策略的准入控制与可视化能力。

4.1 为什么选择 Backstage

Backstage 在平台工程领域已成为事实标准，其核心优势在于统一的开发者体验与强大的插件生态。下表对比了主流平台门户方案，帮助理解选型依据：

特性	Backstage	Kubeapps	自定义 Portal
插件架构	原生插件化，社区活跃	仅支持 Helm Chart 管理	需自研，维护成本高
Kubernetes 集成	内置 K8s 插件，支持 CRD	仅部署层面	需自行开发
网络策略可视化	可通过自定义插件实现	不支持	需深度开发
RBAC 与权限	内置 RBAC，支持 OIDC	基础 RBAC	需集成
社区与文档	CNCF 孵化，文档完善	VMware 维护，更新较慢	无社区支持

Backstage 的插件化架构允许我们后续无缝集成 Calico 策略展示、准入控制状态面板以及策略审计日志，这是其他方案难以做到的。

4.2 部署架构概览

下图展示了 Backstage 在 Kubernetes 集群中的部署架构，以及它与 Calico 准入控制器的关系：

4.3 使用 Helm 部署 Backstage

Helm 是部署 Backstage 到 Kubernetes 的首选方式。我们使用 Bitnami 维护的官方 Chart，它提供了生产级别的默认配置。

4.3.1 添加 Helm 仓库并准备 values 文件

# 添加 Bitnami 仓库
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

# 创建自定义 values 文件 backstage-values.yaml
cat << 'EOF' > backstage-values.yaml
global:
  postgresql:
    auth:
      postgresPassword: "backstage-secret"
      database: "backstage"
      username: "backstage"
      password: "backstage-pass"

backstage:
  appConfig:
    app:
      title: "安全策略治理门户"
      baseUrl: "https://backstage.example.com"
    backend:
      baseUrl: "https://backstage.example.com"
      listen:
        port: 7007
    auth:
      providers:
        guest: {}
    kubernetes:
      serviceLocatorMethod:
        type: "multiTenant"
      clusterLocatorMethods:
        - type: "config"
          clusters:
            - name: "production"
              url: "https://kubernetes.default.svc"
              authProvider: "serviceAccount"
              skipTLSVerify: false
EOF

4.3.2 执行 Helm 安装

# 创建命名空间
kubectl create namespace backstage

# 使用 Helm 安装
helm install backstage bitnami/backstage \
  --namespace backstage \
  --values backstage-values.yaml \
  --version 12.3.0 \
  --timeout 10m

部署验证：安装完成后，使用 kubectl get pods -n backstage 确认所有 Pod 处于 Running 状态。Backstage 主容器与 PostgreSQL 容器应分别就绪。

4.4 配置基本插件

Backstage 的核心能力来自插件。我们首先配置三个基础插件：Kubernetes 插件、TechDocs 插件和Catalog 插件，为后续集成 Calico 策略管理奠定基础。

4.4.1 启用 Kubernetes 插件

Kubernetes 插件允许 Backstage 直接读取集群资源，是实现网络策略可视化的前提。

# 在 backstage-values.yaml 的 appConfig 中添加插件配置
backstage:
  appConfig:
    # ... 其他配置
    techdocs:
      builder: "local"
      generators:
        techdocs: "local"
    kubernetes:
      # 启用插件
      enabled: true
      # 配置集群访问
      clusterLocatorMethods:
        - type: "config"
          clusters:
            - name: "production"
              url: "https://kubernetes.default.svc"
              authProvider: "serviceAccount"
              skipTLSVerify: false
              dashboardUrl: "https://kubernetes-dashboard.example.com"
              dashboardApp: "standard"
              # 使用 ServiceAccount 令牌
              serviceAccountToken: ${K8S_SA_}

安全注意：ServiceAccount 令牌应通过 Kubernetes Secret 注入，而非明文写在 values 文件中。建议使用 external-secrets 或 Vault 集成管理敏感信息。

4.4.2 配置 Catalog 与 TechDocs

Catalog 插件管理服务与组件注册，TechDocs 提供文档中心功能，两者共同构成门户的内容基础。

插件名称	用途	配置要点
@backstage/plugin-catalog	服务、组件、API 的注册与发现	配置 `catalog.locations` 指向 YAML 定义文件
@backstage/plugin-techdocs	Markdown 文档渲染与浏览	设置 `techdocs.builder` 为 `local` 或 `external`
@backstage/plugin-kubernetes	K8s 资源查看与状态监控	配置集群连接与 RBAC 权限

# 在 app-config.yaml 中配置 Catalog 位置
catalog:
  locations:
    - type: url
      target: https://github.com/example/backstage-catalog/blob/main/catalog-info.yaml
      rules:
        - allow: [Component, API, Resource, System]

techdocs:
  builder: 'local'
  generators:
    techdocs: 'local'
  publisher:
    type: 'local'

4.5 插件加载与验证

完成配置后，需要重新部署 Backstage 以加载新插件：

# 升级 Helm Release
helm upgrade backstage bitnami/backstage \
  --namespace backstage \
  --values backstage-values.yaml \
  --reuse-values

# 验证插件是否加载成功
kubectl logs -n backstage -l app.kubernetes.io/name=backstage --tail=50 | grep "plugin"

日志中应出现类似 Plugin kubernetes loaded、Plugin catalog loaded 的确认信息。此时访问 Backstage 前端，侧边栏应显示 Kubernetes、Catalog 和 Docs 菜单项。

  关键检查点：
  确认 Backstage Pod 日志无插件加载错误
确认 Kubernetes 插件能列出集群中的 Pod 和 Service
确认 Catalog 插件能读取到注册的组件实体
确认 TechDocs 能正常渲染示例文档

4.6 为 Calico 集成做准备

基础插件就绪后，我们为后续章节的 Calico 策略集成预留扩展点：

自定义插件目录：在 Backstage 项目中创建 plugins/calico-policy 目录，用于存放 Calico 策略展示插件代码。
API 代理配置：在 app-config.yaml 中预留 Calico API 代理路径，例如 /api/calico 指向 Calico 的 Kubernetes API 端点。
权限模型：配置 Backstage RBAC 策略，为不同团队分配 Calico 策略的查看与编辑权限。

# 在 app-config.yaml 中预留 Calico 代理配置
proxy:
  endpoints:
    '/calico-api':
      target: 'https://kubernetes.default.svc/apis/projectcalico.org/v3'
      allowedHeaders:
        - 'Authorization'
        - 'Content-Type'
      headers:
        Authorization: 'Bearer ${CALICO_SA_}'

至此，Backstage 平台门户已成功部署并配置了核心基础插件，为后续集成 Calico 网络策略准入控制与可视化功能奠定了坚实的平台基础。