企业官网建设流程全解析

Backstage 生产环境部署指南：从 Docker 镜像到多副本运行

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

导读

本文是 Backstage 部署黄金路径（golden path）系列中的第 004 篇，面向平台管理员（Admins），讲解如何把已经构建好的 Docker 镜像、PostgreSQL 数据库和认证配置真正落地到生产环境。读完本文，你将掌握 Backstage 部署所必需的六大要素（镜像、配置与密钥、数据库、网络入口、健康检查运行时、baseUrl）、如何按组织现有基础设施选择部署目标（Kubernetes、ECS、Cloud Run、VM 等），以及多副本、密钥管理、健康检查与 HTTPS 等运营要点。

Backstage 的设计理念很明确：最好的部署方式，就是与你组织部署其他软件完全相同的方式。它被设计成"无状态 Node.js 应用 + 外部 PostgreSQL 数据库"的形态，不需要任何专用工具就能融入绝大多数现有发布流水线。

一、部署前的前置条件

在开始部署之前，本系列前面的步骤已经为你准备好了三样东西，它们是本节一切讨论的基础：

1. Docker 镜像：按照 001-docker.md（构建 Docker 镜像）构建出的镜像同时打包了前端与后端，是唯一需要被部署的产物。
2. PostgreSQL 数据库：按照 002-database.md（配置生产数据库）配置的可达数据库。生产环境不能用本地开发时的 SQLite——它不跨重启持久化数据，也不支持多实例部署。
3. 真实认证提供方：按照 003-authentication.md（配置认证）替换掉默认的 guest 登录。默认的 Guest 认证提供方 明确不适用于容器化/生产环境，任何人只要能访问你的实例就共享同一身份和同一权限等级。

从源码看，默认 Docker 镜像的启动命令中直接带上了app-config.yaml和app-config.production.yaml两个配置文件，这也印证了"镜像构建 → 环境变量注入 → 配置分层"这条链路的重要性（详见下文"配置与密钥"一节）。

二、每个部署都需要什么：六大必需要素

无论你选择哪个平台，一次完整的 Backstage 部署都必须覆盖以下六个关注点：

其中baseUrl的配置是整个部署的"隐性地基"——认证回调、前端 API 请求、CORS 全部以它为准。最小的生产配置如下：

app: baseUrl: https://backstage.example.com backend: baseUrl: https://backstage.example.com listen: port: 7007

为什么是 7007 端口

7007 并非随意选择。从仓库配置可见，app-config.yaml 与 app-config.docker.yaml 中backend.listen.port的默认值都是 7007，同时 packages/backend/Dockerfile 的EXPOSE声明也与之对应。Kubernetes 参考部署中，Service 的targetPort指向的正是这个 HTTP 端口。因此，ingress、负载均衡器、探针（probe）配置都应围绕 7007 展开。

三、选择部署目标

Backstage 可以在任何能运行 Node.js 容器的地方运行。选择与组织现有运维能力匹配的方案即可——你不需要为运行 Backstage 引入任何新基础设施。

平台差异：配置交付方式

选择不同平台，真正变化的不是 Backstage 本身，而是"配置与密钥"的交付机制。结合 配置分层的原理，可以总结出通用规律：镜像只构建一次，各环境只替换配置文件和环境变量。例如：

• Kubernetes：使用 Secret +envFrom注入环境变量；
• AWS：使用 ECS 任务定义中的环境变量，或引用 Secrets Manager；
• GCP：Cloud Run 的--set-env-vars/ Secret Manager；
• Docker Compose：environment:字段或.env文件。

由于配置通过环境变量注入，同一个镜像可以在开发、预发、生产多个环境间复用。

社区贡献的部署指南

对于 Kubernetes 之外的平台，仓库的 contrib/docs/tutorials 目录维护了社区贡献的实战指南，与本主题强相关的包括：

• aws-fargate-deployment.md：ECS / Fargate 部署；
• aws-deployment.md：AWS 部署通用流程；
• aws-alb-aad-oidc-auth.md：AWS ALB + Azure AD OIDC 认证；
• heroku-deployment.md、koyeb-deployment.md、flightcontrol-deployment.md：PaaS 平台部署。

此外，部署总览 解释了所有这些指南共同依赖的底层模型（无状态应用 + 外部 PostgreSQL + 单镜像产物）。

Kubernetes 是官方维护的参考路径

Backstage 官方维护了 Kubernetes 路径的参考指南 Deploying with Kubernetes，它逐步讲解了 namespace、Secret、Deployment、Service，以及如何在集群内连接 PostgreSQL。核心步骤（结合 k8s.md 的完整 YAML）概括为：

1. 创建 namespace：kubectl create namespace backstage（或 apply Namespace 定义）。
2. 创建 PostgreSQL Secret：base64 编码的用户名密码（注意：base64 只是编码不是加密，应启用集群的 Encryption at Rest）。
3. 创建 PersistentVolume / PersistentVolumeClaim与 PostgreSQL Deployment、Service。
4. 创建 Backstage Secret（GitHub token 等）与 Backstage Deployment。
5. 创建 Backstage Service，将 80 端口映射到 pod 的 7007。
6. 通过 ingress 或外部负载均衡器暴露服务。

Backstage Deployment 的核心片段如下（生产环境中image通常替换为容器 registry 的完整 URL）：

# 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 # Uncomment if health checks are enabled in your app: # readinessProbe: # httpGet: # port: 7007 # path: /healthcheck # livenessProbe: # httpGet: # port: 7007 # path: /healthcheck

对应的数据库连接配置放在app-config.production.yaml（记得改配置后重建镜像）：

backend: database: client: pg connection: host: ${POSTGRES_HOST} port: ${POSTGRES_PORT} user: ${POSTGRES_USER} password: ${POSTGRES_PASSWORD}

注意POSTGRES_HOST/POSTGRES_PORT无需额外接线：PostgreSQL 与 Backstage 在同一个集群时，Kubernetes 会自动把这两个环境变量注入 Backstage 容器。

四、运营要点：上线前值得做对的事

在向用户开放之前，有四个运营细节适用于所有部署，值得一次做对：

1. 运行多个副本

在负载均衡器后面运行多个实例。Backstage 是无状态的，多个实例可以共享同一个 PostgreSQL 数据库对外提供服务。插件之间通过数据库协调状态与工作分配——这正是 002-database.md 中提到的"每个插件拥有独立数据库 schema、后端启动时自动迁移"设计的直接收益。

在 Kubernetes 中，把spec.replicas从 1 改为 3 即可：

spec: replicas: 3

无需额外配置。更详细的扩展策略（水平扩展、拆分后端、前端独立部署）参见 007-scaling.md 与 扩展 Backstage 部署。

2. 安全地存储密钥

容器平台通常提供密钥原语——Kubernetes Secrets、AWS Secrets Manager、GCP Secret Manager、Azure Key Vault 等。应从配置中通过环境变量引用这些密钥，而不是把凭据提交进代码仓库。

Backstage 配置使用${VAR_NAME}语法引用环境变量（详见 配置优先开发 与 配置读取）。这种方式让密钥远离配置文件，同时保证同一镜像可以在不同环境通过改变变量来复用。

3. 启用健康检查

将平台的 readiness 和 liveness 探针接到 Backstage 的健康端点上，让不健康的实例被自动移出轮询并重启。

健康端点的具体路径取决于后端版本（参考 observability.md）：

• 新版后端（1.29.0 之后）：由RootHealthService提供/.backstage/health/v1/readiness与/.backstage/health/v1/liveness两个端点，详见 Root Health Service 文档；
• 新版后端（1.29.0 之前）：健康检查正走向"插件化"，可以在后端模块中用rootHttpRouter自建/healthcheck路由：

  const healthCheck = createBackendPlugin({ pluginId: 'healthcheck', register(env) { env.registerInit({ deps: { rootHttpRouter: coreServices.rootHttpRouter }, init: async ({ rootHttpRouter }) => { rootHttpRouter.use('/healthcheck', (req, res) => { res.json({ status: 'ok' }); }); }, }); }, });

• 旧后端：参考仓库旧版 packages/backend/src/index.ts 中的/healthcheck路由实现。

在 Kubernetes 中，对应的探针配置即上一节 YAML 中注释掉的readinessProbe/livenessProbe片段。

4. 在 HTTPS 后面运行

在 ingress、负载均衡器或反向代理处终结 TLS，并确保公网 URL 与app.baseUrl、backend.baseUrl一致。这一步与第一节的 baseUrl 配置直接联动：认证提供方的回调地址、前端的 API 请求地址都以此为准，不一致会导致登录弹窗失效或请求被 CORS 拦截。

如果需要让 Backstage 运行在公司的正向代理之后，参见 corporate proxy 指南。

五、从源码看"无状态 + 外部数据库"的架构基础

Backstage 之所以能像普通软件一样部署，根植于其运行架构（详见 部署总览 与 架构总览）：

• 单镜像包含全部：前端由@backstage/plugin-app-backend插件内置于后端进程中提供（默认部署形态），因此只需要部署一个容器；
• 无状态进程：后端进程本身不保存业务状态，状态落在外部 PostgreSQL 中。这也意味着进程可以被任意销毁重建，天然适配容器的"不可变实例"模型；
• 数据库即协调器：多实例间的状态共享与任务分配通过数据库完成（例如 catalog 处理进度、scaffolder 任务），这是水平扩展能够成立的根基；
• 配置分层注入：镜像内只带基础配置，app-config.production.yaml与部署平台注入的环境变量在启动时合并，实现"一次构建、到处运行"。

这套模型意味着：你在组织内如何部署其他 Node.js 服务，就如何部署 Backstage——无论是 Kubernetes、ECS、Cloud Run，还是传统 VM，Backstage 都能原样融入，不需要学习新的部署范式。

六、部署完成之后

你的 Backstage 实例已经部署完成。接下来，本系列建议继续学习如何跨环境高效管理配置——这也是运维 Backstage 长期最核心的技能之一：

• 配置优先开发（Config-first development）：理解配置分层（app-config.yaml基础配置、app-config.local.yaml本地覆盖、app-config.production.yaml生产覆盖）与${VAR}环境变量语法；
• 后续章节还会覆盖 监控（OpenTelemetry 可观测性）与 扩展 主题。

整个部署黄金路径的起点是 构建 Docker 镜像，前置依赖是 数据库 与 认证；而 部署系列索引 提供了这条路径的完整地图，方便你按需回看任意一步。

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