在 Kubernetes 上部署 Backstage：从本地 minikube 到生产集群的完整实践指南-港品优选

在 Kubernetes 上部署 Backstage：从本地 minikube 到生产集群的完整实践指南

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage

本文基于 docs/deployment/k8s.md 编写，配套仓库源码与 contrib 示例作为补充依据。

导读

Backstage 是一个用于构建开发者门户（Developer Portal）的开源框架，其设计目标之一就是适配容器化部署模型：Backstage 本身是一个无状态应用，数据全部存放在外部 PostgreSQL 数据库中，因此非常适合运行在 Kubernetes 集群上。本文完整讲解如何在 Kubernetes 上从零部署一套 Backstage：涵盖本地 minikube 环境搭建、命名空间创建、PostgreSQL 数据库（Secret / PersistentVolume / Deployment / Service）创建、Backstage 应用实例（Secret / Deployment / Service）创建，以及生产化部署的后续步骤。读完本文你将能够：

使用kubectl与 minikube 在本地搭建并验证一套完整的 Backstage 环境；
理解并编写 Backstage 部署所需的全部 Kubernetes 对象定义（Namespace、Secret、PersistentVolume、PersistentVolumeClaim、Deployment、Service）；
将 Backstage 配置（app-config.yaml）与 Kubernetes 环境变量、Secret 打通，实现数据库连接与鉴权配置注入；
掌握生产部署的收尾工作：可靠的持久卷、Ingress/负载均衡暴露服务、镜像更新策略。

部署模型总览

Kubernetes 是用于部署、扩缩容和管理容器化应用的系统。Backstage 天然适配这一模型：它以无状态应用（stateless application）的形式运行，配合外部 PostgreSQL 数据库持久化数据。

值得注意的一点是：Backstage 软件目录（Software Catalog）的实体定义文件本身也使用 Kubernetes 对象格式，这一点在 descriptor-format.md 中有详细说明。也就是说，如果你已经熟悉 Kubernetes 的 YAML 对象写法，那么阅读 Backstage 的实体定义文件也会相当顺手。

由于 Kubernetes 集群的部署工具与模式多种多样，官方文档给出的核心建议是：在已有 Kubernetes 环境上部署 Backstage 时，"用你部署其他一切服务的方式"来部署它。本文提供的是在典型集群中让 Backstage 跑起来所需的基础 Kubernetes 对象定义。

一个完整的部署由两大块组成：

PostgreSQL 数据库：通过独立的 Kubernetes Deployment 运行，使用 Secret 保存凭据、PersistentVolume/PersistentVolumeClaim 持久化数据、Service 提供稳定的访问入口；
Backstage 应用实例：通过 Kubernetes Deployment 运行打包好的 Docker 镜像，通过 Secret 注入鉴权 Token 等敏感配置，通过 Service 将 7007 端口暴露给集群内其他组件。

本地测试环境：kubectl + minikube

在生产集群部署之前，可以先用本地环境验证上述所有概念。需要两个工具：

kubectl：Kubernetes 命令行工具，用于向集群下发各种对象定义；
minikube：在本地机器上创建一个单节点 Kubernetes 集群。

以 Mac + Homebrew 为例的安装方式如下（其他平台请参考 minikube 官方安装文档）：

$ brew install minikube $ minikube start ... Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default.

minikube start完成后，kubectl会被自动配置为指向名为minikube的集群与default命名空间。此时执行kubectl命令所做的变更都会应用到该本地集群，可以验证系统组件是否正常运行：

$ kubectl get pods -A

当教程结束后，使用minikube stop停止集群以释放资源。

提示：minikube 也可以用于本地构建并安装 Backstage 镜像，详见下文「创建 Backstage deployment」小节中关于minikube docker-env的用法。

创建命名空间（Namespace）

在多租户环境下，部署通常被分配到独立的命名空间中以实现服务隔离。可以通过kubectl直接创建：

$ kubectl create namespace backstage namespace/backstage created

也可以先编写 Namespace 定义文件再应用：

# kubernetes/namespace.yaml apiVersion: v1 kind: Namespace metadata: name: backstage

$ kubectl apply -f kubernetes/namespace.yaml namespace/backstage created

后续所有与 Backstage 相关的对象（Secret、PVC、Deployment、Service 等）都将放在backstage命名空间下，并在各自定义中通过namespace: backstage显式声明。

创建 PostgreSQL 数据库

生产环境中 Backstage 使用 PostgreSQL 作为数据库。为了将数据库与 Backstage 应用部署隔离，可以为 PostgreSQL 单独创建一个 Kubernetes Deployment。整个过程分为四步：Secret（凭据）、持久化存储（PV/PVC）、Deployment（数据库实例）、Service（访问入口）。

创建 PostgreSQL Secret

首先创建一个 Kubernetes Secret，保存 PostgreSQL 的用户名与密码。该 Secret 同时会被 PostgreSQL 数据库和 Backstage 两个 Deployment 引用：

# kubernetes/postgres-secrets.yaml apiVersion: v1 kind: Secret metadata: name: postgres-secrets namespace: backstage type: Opaque data: POSTGRES_USER: YmFja3N0YWdl POSTGRES_PASSWORD: aHVudGVyMg==

Kubernetes Secret 中的 data 字段是base64 编码的。可以在命令行生成：

$ echo -n "backstage" | base64 YmFja3N0YWdl

安全提醒：Secret 只是 base64 编码，并未加密。请务必为集群启用 Kubernetes Encryption at Rest。如果希望把 Secret 存进 Git，可以考虑 SealedSecrets 或其他解决方案。

应用该 Secret：

$ kubectl apply -f kubernetes/postgres-secrets.yaml secret/postgres-secrets created

创建 PostgreSQL 持久化存储（PV + PVC）

PostgreSQL 需要持久卷来存储数据。下面同时创建一个PersistentVolume（PV）与PersistentVolumeClaim（PVC）。本例声明了整块卷，但 PVC 实际上也可以只申请卷的一部分容量：

# kubernetes/postgres-storage.yaml apiVersion: v1 kind: PersistentVolume metadata: name: postgres-storage namespace: backstage labels: type: local spec: storageClassName: manual capacity: storage: 2G accessModes: - ReadWriteOnce persistentVolumeReclaimPolicy: Retain hostPath: path: '/mnt/data' --- apiVersion: v1 kind: PersistentVolumeClaim metadata: name: postgres-storage-claim namespace: backstage spec: storageClassName: manual accessModes: - ReadWriteOnce resources: requests: storage: 2G

该文件包含两种 kind 的定义，用一行**三连横线（---）**分隔。这种语法便于将相关联的 Kubernetes 定义合并到单个文件中一次性应用。

注意卷标签中的type: local：它使用 Kubernetes 节点上的本地磁盘创建卷。在生产场景中，通常应改用可用性更高的 PersistentVolume 类型（如云厂商的块存储、网络附加存储等），这一点会在「进一步步骤」中再次强调。

应用存储卷与声明：

$ kubectl apply -f kubernetes/postgres-storage.yaml persistentvolume/postgres-storage created persistentvolumeclaim/postgres-storage-claim created

创建 PostgreSQL Deployment

接下来为数据库本身创建 Kubernetes Deployment 描述文件：

# kubernetes/postgres.yaml apiVersion: apps/v1 kind: Deployment metadata: name: postgres namespace: backstage spec: replicas: 1 selector: matchLabels: app: postgres template: metadata: labels: app: postgres spec: containers: - name: postgres image: postgres:13.2-alpine imagePullPolicy: 'IfNotPresent' ports: - containerPort: 5432 envFrom: - secretRef: name: postgres-secrets env: - name: POSTGRES_HOST value: postgres.backstage - name: POSTGRES_PORT value: '5432' volumeMounts: - mountPath: /var/lib/postgresql/data name: postgresdb subPath: data volumes: - name: postgresdb persistentVolumeClaim: claimName: postgres-storage-claim

对 Kubernetes 新手来说，这段定义信息量较大，拆开来看：

metadata块描述了这个 Deployment（应用的一个或多个实例）的基本信息；
spec块描述期望状态（desired state）：请求 Kubernetes 创建 1 个副本（正在运行的 PostgreSQL 实例），并用给定的 podtemplate创建副本；template 中又包含 Kubernetes 元数据与期望状态；
template 的spec中定义了一个容器，来源于官方发布的postgres:13.2-alpineDocker 镜像，暴露 5432 端口（PostgreSQL 默认端口）；
envFrom+secretRef让 Kubernetes 把之前创建的 Secret 中的值注入为容器环境变量；
volumeMounts引用了为部署创建的持久卷，挂载路径为 PostgreSQL 期望的数据目录/var/lib/postgresql/data，并使用subPath: data隔离出独立子目录；
volumes中通过persistentVolumeClaim引用前面创建的 PVCpostgres-storage-claim。

应用 PostgreSQL Deployment 并查看 Pod 状态：

$ kubectl apply -f kubernetes/postgres.yaml deployment.apps/postgres created $ kubectl get pods --namespace=backstage NAME READY STATUS RESTARTS AGE postgres-56c86b8bbc-66pt2 1/1 Running 0 21s

进入 Pod 验证数据库可连接：

$ kubectl exec -it --namespace=backstage postgres-56c86b8bbc-66pt2 -- /bin/bash bash-5.1# psql -U $POSTGRES_USER psql (13.2) backstage=# \q bash-5.1# exit

创建 PostgreSQL Service

数据库 Pod 已经运行，但其他 Pod 如何连接它？Kubernetes Pod 是瞬态的——它们可能被停止、重启或动态创建，因此不应直接连接 Pod，而应创建 KubernetesService。Service 负责跟踪 Pod 并将流量导向正确的位置：

# kubernetes/postgres-service.yaml apiVersion: v1 kind: Service metadata: name: postgres namespace: backstage spec: selector: app: postgres ports: - port: 5432

这里的selector: app: postgres与 PostgreSQL Deployment 中 pod template 的标签app: postgres对应，Service 会将流量路由到带有该标签的 Pod。应用该 Service：

$ kubectl apply -f kubernetes/postgres-service.yaml service/postgres created $ kubectl get services --namespace=backstage NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE postgres ClusterIP 10.96.5.103 <none> 5432/TCP 29s

创建完成后，集群内的其他 Pod（包括 Backstage）可以通过服务名postgres访问数据库。

创建 Backstage 实例

数据库就绪后，开始创建 Backstage 实例，步骤与 PostgreSQL 部署类似。

创建 Backstage Secret

对于 Backstage 的配置类 Secret（如鉴权 Token），可以参照上面的 PostgreSQL Secret 方式创建，同样需要 base64 编码：

# kubernetes/backstage-secrets.yaml apiVersion: v1 kind: Secret metadata: name: backstage-secrets namespace: backstage type: Opaque data: GITHUB_TOKEN: VG9rZW5Ub2tlblRva2VuVG9rZW5NYWxrb3ZpY2hUb2tlbg==

应用该 Secret：

$ kubectl apply -f kubernetes/backstage-secrets.yaml secret/backstage-secrets created

创建 Backstage Deployment

创建 Backstage Deployment 前，需要先构建 Docker 镜像，具体方法见 docs/deployment/docker.md。本例使用标准的host build方式：前端被打包进后端镜像并由后端一并提供。

创建 Backstage Deployment 描述文件：

# kubernetes/backstage.yaml apiVersion: apps/v1 kind: Deployment metadata: name: backstage namespace: backstage spec: replicas: 1 selector: matchLabels: app: backstage template: metadata: labels: app: backstage spec: containers: - name: backstage image: backstage:1.0.0 imagePullPolicy: IfNotPresent ports: - name: http containerPort: 7007 envFrom: - secretRef: name: postgres-secrets - secretRef: name: backstage-secrets # 如果应用启用了健康检查，取消注释： # https://backstage.io/docs/plugins/observability#health-checks # readinessProbe: # httpGet: # port: 7007 # path: /healthcheck # livenessProbe: # httpGet: # port: 7007 # path: /healthcheck

要点说明：

镜像引用：生产部署中，image通常是一个完整的容器仓库 URL（例如 AWS 的 ECR）。本地用 minikube 测试时，可以把本地 Docker 守护进程指向 minikube 内置的 Docker 仓库，然后重新构建镜像完成安装：
```
$ eval $(minikube docker-env) $ yarn build-image --tag backstage:1.0.0
```
数据库连接无需额外配置网络：由于 PostgreSQL Service 运行在同一个集群中，Kubernetes 会自动把POSTGRES_HOST和POSTGRES_PORT环境变量注入 Backstage 容器（此处的POSTGRES_HOST即服务名postgres）。这些变量配合 Secret 注入的凭据，可以在 Backstage 的app-config.yaml中直接使用：
```
backend: database: client: pg connection: host: ${POSTGRES_HOST} port: ${POSTGRES_PORT} user: ${POSTGRES_USER} password: ${POSTGRES_PASSWORD}
```
如果有app-config.production.yaml，也需要同步应用这段配置。关于${...}环境变量语法与 PostgreSQL 客户端的更多说明，可参考 docs/getting-started/config/database.md。
重要：修改app-config.yaml后，务必重新构建 Docker 镜像，改动才会进入新的镜像。
健康检查探针（Probe）：上面被注释的readinessProbe/livenessProbe对应后端/healthcheck路由。在新版后端系统中，健康检查由 Root Health 服务提供，rootHttpRouter默认暴露/.backstage/health/v1/readiness与/.backstage/health/v1/liveness端点（详见 docs/backend-system/core-services/root-health.md），并可通过backend.health.headers为健康检查响应追加自定义响应头（例如在多变服务环境中用于唯一标识本服务的service-name头）。在配置探针时请依据所部署 Backstage 版本实际启用的健康检查路径进行调整。

应用 Deployment 并确认运行状态：

$ kubectl apply -f kubernetes/backstage.yaml deployment.apps/backstage created $ kubectl get deployments --namespace=backstage NAME READY UP-TO-DATE AVAILABLE AGE backstage 1/1 1 1 1m postgres 1/1 1 1 10m $ kubectl get pods --namespace=backstage NAME READY STATUS RESTARTS AGE backstage-54bfcd6476-n2jkm 1/1 Running 0 58s postgres-56c86b8bbc-66pt2 1/1 Running 0 9m

如果遇到问题，可以查看 Pod 中的容器日志（-f表示持续跟踪输出）：

# -f 跟踪日志，<pod> -c <container> 指定容器 $ kubectl logs --namespace=backstage -f backstage-54bfcd6476-n2jkm -c backstage

创建 Backstage Service

与 PostgreSQL Service 类似，需要为 Backstage 创建一个 Kubernetes Service，将请求连接到正确的 Pod：

# kubernetes/backstage-service.yaml apiVersion: v1 kind: Service metadata: name: backstage namespace: backstage spec: selector: app: backstage ports: - name: http port: 80 targetPort: http

这里selector告诉 Service 要指向哪些 Pod；端口映射把常规 HTTP 的 80 端口转换为 Pod 上的后端 HTTP 端口（7007，即 Deployment 中containerPort: 7007对应name: http的端口）。

应用该 Service：

$ kubectl apply -f kubernetes/backstage-service.yaml service/backstage created

至此，一个可运行的 Backstage 部署已经完成。要一睹成果，可以把本地端口转发到该 Service：

$ sudo kubectl port-forward --namespace=backstage svc/backstage 80:80 Forwarding from 127.0.0.1:80 -> 7007

输出显示 7007 是因为port-forward本身并不真正支持 Service——它会“作弊”地查找该 Service 的第一个 Pod，并连接到映射的 Pod 端口。

同时，app-config.yaml中的app.baseUrl与backend.baseUrl需要与这里的转发地址一致（本例使用默认 HTTP 端口 80，故省略端口号）：

# app-config.yaml app: baseUrl: http://localhost organization: name: Spotify backend: baseUrl: http://localhost listen: port: 7007 cors: origin: http://localhost

如果使用了鉴权提供者（auth provider，参见 docs/auth/index.md），也需要为它配置同样的地址，鉴权弹窗才能正常工作。

完成以上步骤后，在浏览器打开http://localhost，即可访问部署在 Kubernetes 上的 Backstage 实例。

生产化部署的进一步步骤

上述流程已经走完了 Backstage 上 Kubernetes 的大部分路径，但距离完整的生产部署还有几步收尾工作：

使用更可靠的持久卷

上面配置的PersistentVolume使用的是 Kubernetes 节点本地存储（type: local/hostPath）。生产环境应替换为云磁盘、网络附加存储（NAS）或其他比节点生命周期更持久的存储方案，以避免节点重建导致数据丢失。

暴露 Backstage Service

上文创建的 Kubernetes Service（ClusterIP）默认无法从集群外部访问。通常通过以下两种方式之一暴露：

Kubernetes Ingress：在集群入口统一做路由与（可选）TLS 终止；
外部负载均衡器：直接为 Service 分配外部可访问的 IP。

更新 Deployment 镜像

要将 Kubernetes 部署更新到新发布的 Backstage Docker 镜像版本，只需修改backstage.yaml中的镜像 tag，然后重新应用：

$ kubectl apply -f kubernetes/backstage.yaml

生产环境下该镜像 tag 通常是一个完整的容器仓库 URL，指向存放构建产物的地方——可以是自建的基础设施，也可以是云厂商提供的托管仓库。

仓库配套资源：可参考的 Kubernetes 示例

当前仓库的 contrib/kubernetes/basic_kubernetes_example_with_helm 目录提供了额外的参考实现，值得对照阅读：

裸 YAML 版本：app.yaml（前端 Deployment，镜像spotify/backstage:latest，端口 80）、backend.yaml（后端 Deployment，镜像spotify/backstage-backend:latest，端口 7007）、service.yaml（分别为前端 Service 80 端口与后端 Service 7007 端口）、ingress.yaml（将/路由到前端 Service、/backend路由到后端 Service）——这个示例演示了前端与后端分离部署的形态；
Helm 版本：backstage/目录下包含Chart.yaml、values.yaml与templates/（deployment.yaml、service.yaml、ingress.yaml、_helpers.tpl）。values.yaml中对app与backend两套组件分别提供了replicaCount、image.repository/image.tag/image.pullPolicy、service.type/service.port、ingress（hosts / tls / annotations）、resources、securityContext等可调参数，模板中还内置了 liveness / readiness 探针（对根路径做 HTTP 检查）与imagePullSecrets支持。

注意：该 contrib 目录的 README 明确标注为 deprecated，官方推荐使用由 Backstage 社区维护的 Backstage Helm Charts；同时这些示例仅展示最小化配置，并未包含安全加固的最佳实践，生产环境请参考 Kubernetes 官方安全文档与所在组织的规范。

总结

本文完整演示了 Backstage 在 Kubernetes 上的部署路径：从本地 minikube 验证环境出发，依次创建命名空间、PostgreSQL 的 Secret / PV+PVC / Deployment / Service，再到 Backstage 的 Secret / Deployment / Service，最后通过kubectl port-forward在浏览器中访问实例。这套对象定义完整覆盖了「无状态应用 + 外部数据库」的部署模型，而contrib目录中的 Helm 与前后端分离示例则为生产化提供了更多形态参考。将本地存储替换为高可用持久卷、通过 Ingress 或负载均衡暴露服务、按发布节奏滚动更新镜像，即可平滑过渡到完整的生产部署。

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析