Backstage 官方 Kubernetes Helm Chart 部署指南：App 前端与 Backend 全参数解析

导读

本文基于 Backstage 仓库中随附的官方基础 Kubernetes Helm 示例（位于 contrib/kubernetes/basic_kubernetes_example_with_helm），系统讲解使用 Helm 在 Kubernetes 上部署 Backstage 开发门户时所需的全部可配置参数、模板渲染原理与最小化部署实践。读完本文，你将掌握 App 前端与 Backend 两套组件的镜像、副本、Service、Ingress、资源配额、安全上下文等核心参数的取值与默认行为，并能直接基于仓库内的 values.yaml 与裸 YAML 示例完成一次可运行的 Backstage 部署。

一、示例整体结构与定位

仓库在 contrib/kubernetes/basic_kubernetes_example_with_helm 目录下提供了一套"基础 Kubernetes + Helm"的部署示例，其内部组织如下：

路径	作用
backstage/Chart.yaml	Helm Chart 元数据，Chart 名为 backstage，版本 0.1.1-alpha.12
backstage/values.yaml	全部默认值，App 前端与 Backend 两组配置的权威来源
backstage/templates/_helpers.tpl	Helm 模板辅助函数，负责名称、标签、ServiceAccount 的生成规则
backstage/templates/deployment.yaml	Deployment 模板，按 app.enabled / backend.enabled 条件渲染两组工作负载
backstage/templates/service.yaml	Service 模板，为前后端分别暴露集群内访问入口
backstage/templates/ingress.yaml	Ingress 模板，将外部流量按路径路由到前后端服务
app.yaml / backend.yaml / ingress.yaml / service.yaml	不使用 Helm 时的手写裸 Kubernetes 清单，展示等价的最小配置

需要特别说明的是，该目录的 README.md 明确标注本示例 已被标记为废弃（deprecated），未来会从仓库移除；官方建议迁移到独立维护的 backstage/charts 仓库获取更完善的 Helm Chart。同时该 README 提醒：这些示例"旨在展示最小化配置，不包含生产级 Kubernetes 部署的最佳安全实践"，生产环境的安全加固（网络策略、Secrets 管理、Pod 安全标准等）需要结合 Kubernetes 官方安全文档或组织自身规范另行落实。

二、App 前端（Frontend）Values 参数全表

backstage/README.md 将参数分为 App/Frontend 与 Backend 两大类。App 前端对应 Backstage 的前端应用容器，完整参数如下：

参数	说明	默认值
app.enabled	是否渲染前端应用配置（生成 Deployment 等资源）	true
app.nameOverride	覆盖赋予 App 前端的名称	""
app.fullnameOverride	覆盖 App 前端的完整名称	""
app.replicaCount	App 前端 Pod 的副本数	1
app.image.repository	App 前端容器镜像仓库	spotify/backstage
app.image.tag	拉取的 App 前端镜像标签	latest
app.image.pullPolicy	镜像拉取策略	Always
app.service.type	App 前端 Service 类型	ClusterIP
app.service.port	App 前端服务端口	80
app.ingress.enabled	是否创建 Ingress	false
app.ingress.annotations	App 前端 Ingress 注解	{}
app.ingress.hosts[].host	App 前端访问主机名	backstage.local
app.ingress.hosts[].paths[]	App 前端提供服务的路径	["/"]
app.imagePullSecrets[]	拉取 app.image.repository 镜像所需的镜像密钥	[]
app.podSecurityContext	App 前端 Pod 级安全上下文	{}
app.securityContext	Deployment 内容器级安全上下文设置	{}
app.resources	Kubernetes Pod 资源 requests/limits	{}
app.nodeSelector	调度 App 前端 Pod 的节点选择器	{}
app.tolerations	调度 App 前端 Pod 的容忍度（污点容忍）	{}
app.affinity	App 前端 Pod 的亲和性设置	{}

注意：原文档表格中 app.imagePullSecrets[] 等行以 app. 为前缀书写，实际对应 values.yaml 中 app: 层级下的同名键；阅读时需结合层级上下文理解。

三、Backend Values 参数全表

Backend 对应 Backstage 的后端（含 catalog、scaffolder 等插件服务）容器，参数结构与应用端一一对应：

参数	说明	默认值
backend.enabled	是否渲染后端配置	true
backend.nameOverride	覆盖赋予后端的名称	""
backend.fullnameOverride	覆盖后端的完整名称	""
backend.replicaCount	后端 Pod 的副本数	1
backend.image.repository	后端容器镜像仓库	spotify/backstage
backend.image.tag	拉取的后端镜像标签	latest
backend.image.pullPolicy	镜像拉取策略	Always
backend.service.type	后端 Service 类型	ClusterIP
backend.service.port	后端服务端口	80
backend.ingress.enabled	是否创建后端 Ingress	false
backend.ingress.annotations	后端 Ingress 注解	{}
backend.ingress.hosts[].host	后端访问主机名	backstage.local
backend.ingress.hosts[].paths[]	后端提供服务的路径	["/"]
backend.imagePullSecrets[]	拉取 backend.image.repository 镜像所需的镜像密钥	[]
backend.podSecurityContext	后端 Pod 级安全上下文	{}
backend.securityContext	后端容器级安全上下文设置	{}
backend.resources	Kubernetes Pod 资源 requests/limits	{}
backend.nodeSelector	调度后端 Pod 的节点选择器	{}
backend.tolerations	调度后端 Pod 的容忍度	{}
backend.affinity	后端 Pod 的亲和性设置	{}

四、默认值源码解读：values.yaml 与模板行为

4.1 values.yaml 中的默认配置

backstage/values.yaml 是 Helm 渲染的实际输入，与 README 表格相比提供了更完整的默认细节，包括 README 中未展开的几个关键点：

• App 前端默认 enabled: true、replicaCount: 1、镜像 spotify/backstage:latest、pullPolicy: Always、Service 端口 80、Ingress 主机 backstage.local 且路径为 /；
• Backend 默认 enabled: false（与 README 表格中的 true 不同，以 values.yaml 为准）、镜像为 spotify/backstage-backend:latest、pullPolicy: IfNotPresent、Service 端口 7007、Ingress 路径为 /backend；
• 两组组件都预置了注释掉的常用配置示例，例如 Pod 安全上下文的 fsGroup: 2000、容器安全上下文的 capabilities.drop: ALL、runAsNonRoot: true、runAsUser: 1000，以及资源配额示例 cpu: 100m / memory: 128Mi，取消注释即可启用；
• Ingress 的 TLS 配置（tls: []）以及 kubernetes.io/ingress.class: "nginx" 注解同样以注释形式给出，便于按 Ingress Controller 类型启用。

4.2 名称与标签的模板规则

templates/_helpers.tpl 定义了名称生成规则：

• backstage.name：默认取 Chart 名 backstage，可用 nameOverride 覆盖；
• backstage.fullname：优先使用 fullnameOverride；否则若 Release 名已包含 Chart 名则直接使用 Release 名，否则拼接为 <releaseName>-<chartName>；所有名称统一 trunc 63 并去掉尾部 -，以符合 Kubernetes DNS 命名规范对名称字段 63 字符的限制；
• backstage.app.labels / backstage.backend.labels：输出标准的 app.kubernetes.io/name、helm.sh/chart、app.kubernetes.io/instance、app.kubernetes.io/version、app.kubernetes.io/managed-by 标签，分别以 -app、-backend 后缀区分前后端；
• backstage.app.serviceAccountName / backstage.backend.serviceAccountName：当 serviceAccount.create 为 true 时使用 serviceAccount.name，否则回退到 default。

4.3 Deployment 的渲染条件与探针

templates/deployment.yaml 是最核心的渲染逻辑：

• 使用 {{- if .Values.app.enabled }} 与 {{- if .Values.backend.enabled }} 分别包裹前后端 Deployment，通过开关控制是否生成资源；
• Deployment 名称分别为 {{ fullname }}-app 与 {{ fullname }}-backend，与标签体系保持一致；
• 容器名分别为 <chartName>-app 与 <chartName>-backend，镜像字符串为 "{{ repository }}:{{ tag }}" 拼接而成；
• 前后端均配置了 livenessProbe 与 readinessProbe，通过 httpGet 请求 / 路径检查存活与就绪状态；需要留意的是，模板中后端容器声明了 containerPort: 80，但探针端口引用的是名为 backend 的端口，这与 values.yaml 中后端 Service 端口 7007 存在差异，实际部署时需按自身后端镜像暴露的端口校准；
• imagePullSecrets、podSecurityContext、securityContext、resources、nodeSelector、affinity、tolerations 全部通过 toYaml . | nindent 原样注入，保证任意复杂结构都能透传。

4.4 Service 与 Ingress

templates/service.yaml 与 templates/ingress.yaml 分别渲染前后端 Service 与 Ingress：

• Service 使用 ClusterIP 类型，App 前端端口为 80、后端为 7007（以 values.yaml 默认值为准），targetPort 对应容器端口名 app / backend；
• Ingress 默认 enabled: false，启用后按 hosts[].host 与 paths[] 生成路由规则，TLS 通过 tls[] 配置。

五、不使用 Helm 的裸 Kubernetes 清单对照

对于希望直接 kubectl apply 而非使用 Helm 的场景，目录根级提供了等价的最小清单，是理解整套部署模型最直观的参考：

• app.yaml：前端 Deployment，副本数 1，镜像 spotify/backstage:latest，imagePullPolicy: IfNotPresent，容器端口 80（命名 app），标签 app: backstage、component: frontend；
• backend.yaml：后端 Deployment，镜像 spotify/backstage-backend:latest，容器端口 7007（命名 backend），标签 component: backend；
• service.yaml：一个文件内以 --- 分隔定义两个 ClusterIP Service——backstage（端口 80 → targetPort app）与 backstage-backend（端口 7007 → targetPort backend），通过 selector 精确匹配各自的 app + component 标签；
• ingress.yaml：演示了前后端路由共存的方式——同一主机名 <HOSTNAME> 下，路径 / 转发到前端 Service backstage（端口 frontend），路径 /backend 转发到后端 Service backstage-backend（端口 backend）。注意该清单使用 extensions/v1beta1 API 版本，在现代 Kubernetes（v1.22+）中该版本已移除，应改用 networking.k8s.io/v1，这也从侧面印证了该示例确属较早时期编写。

六、最小化部署实操要点

综合以上信息，完成一次基于本示例的 Backstage 部署，核心步骤如下：

1. 准备镜像：确定前后端容器镜像。App 前端默认 spotify/backstage:latest，后端默认 spotify/backstage-backend:latest；私有镜像仓库场景需通过 app.imagePullSecrets / backend.imagePullSecrets 注入拉取凭证；
2. 修改 values：在 backstage/values.yaml 中设置 app.enabled: true、backend.enabled: true，按需调整 app.image.tag、backend.image.tag 与 replicaCount；
3. 安装 Chart：在 backstage/ 目录下执行 helm install <release-name> .（可另加 -f 指定自定义 values 文件），或者先 helm template 预览渲染结果再落盘应用；
4. 暴露访问入口：开启 app.ingress.enabled 并配置 hosts 与 tls，或手动应用根级 ingress.yaml（注意先将 <HOSTNAME> 替换为真实域名，并把 API 版本升级为 networking.k8s.io/v1）；
5. 验证：通过 Service 端口或 Ingress 地址访问前端，确认 / 返回前端页面、/backend 能被后端正常响应。

七、结论与适用边界

本示例的价值在于：它以最小、可读的方式完整展示了 Backstage 前后端分离架构在 Kubernetes 上的映射关系——前端容器暴露 80、后端容器暴露 7007，通过 component: frontend / component: backend 标签区分两组资源，再由 Service 与 Ingress 按路径 / 与 /backend 完成流量路由。app.enabled / backend.enabled 的开关设计、统一的名称与标签辅助函数、以及 toYaml 透传机制，共同构成了这套 Chart 的骨架。

使用时务必注意三点边界：其一，该示例已在目录 README 中被官方标注为废弃，仅适合学习参考，生产环境请迁移到官方维护的 Backstage Helm Charts；其二，示例明确不包含生产级安全实践（如 Secret 管理、网络策略、非 root 运行等），需要在部署时自行补齐；其三，仓库与模板中的镜像默认值、API 版本（如 extensions/v1beta1）均为历史版本设定，实际部署应结合当前集群版本与镜像发布情况调整。

参考文件索引

• Chart 参数文档：本文核心依据，App/Backend 参数全表
• 示例目录总览与废弃声明
• 默认值配置
• Chart 元数据
• 名称与标签辅助函数
• Deployment 模板
• 裸清单示例、backend.yaml、service.yaml、ingress.yaml