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 数据库的形态不需要任何专用工具就能融入绝大多数现有发布流水线。一、部署前的前置条件在开始部署之前本系列前面的步骤已经为你准备好了三样东西它们是本节一切讨论的基础Docker 镜像按照 001-docker.md构建 Docker 镜像构建出的镜像同时打包了前端与后端是唯一需要被部署的产物。PostgreSQL 数据库按照 002-database.md配置生产数据库配置的可达数据库。生产环境不能用本地开发时的 SQLite——它不跨重启持久化数据也不支持多实例部署。真实认证提供方按照 003-authentication.md配置认证替换掉默认的 guest 登录。默认的 Guest 认证提供方 明确不适用于容器化/生产环境任何人只要能访问你的实例就共享同一身份和同一权限等级。从源码看默认 Docker 镜像的启动命令中直接带上了app-config.yaml和app-config.production.yaml两个配置文件这也印证了镜像构建 → 环境变量注入 → 配置分层这条链路的重要性详见下文配置与密钥一节。二、每个部署都需要什么六大必需要素无论你选择哪个平台一次完整的 Backstage 部署都必须覆盖以下六个关注点要素说明容器镜像从你的仓库构建并推送到运行时可以拉取的 registry。你在 构建 Docker 镜像 一节构建的镜像就是被部署的产物。配置与密钥以环境变量或挂载文件的方式交付给运行中的容器包括数据库凭据、认证提供方 client secret、各类集成 token。可达的 PostgreSQL运行实例能够用上一步的凭据连接到的数据库详见 配置生产数据库。网络入口通常是 ingress、负载均衡器或反向代理负责把后端暴露在7007 端口上并通过 HTTPS 提供给用户。带健康检查的运行时容器停止响应时能自动重启、发布新镜像时能滚动更新的运行时平台。app.baseUrl与backend.baseUrl在app-config.production.yaml中设置为用户访问 Backstage 的公网 URL。认证提供方和前端都依赖这两个值与实际入口一致。其中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 引入任何新基础设施。部署目标适用场景Kubernetes组织已经在 Kubernetes 上运行服务。Amazon ECS / Fargate使用 AWS 且倾向于托管容器调度。Google Cloud Run想要 GCP 上完全托管、按请求驱动的容器运行时。Azure Container Apps使用 Azure 且想要托管容器平台。传统 VM 或 PaaS更愿意直接在反向代理后面运行 Node.js 进程。Docker Compose小型安装或概念验证PoC。平台差异配置交付方式选择不同平台真正变化的不是 Backstage 本身而是配置与密钥的交付机制。结合 配置分层的原理可以总结出通用规律镜像只构建一次各环境只替换配置文件和环境变量。例如Kubernetes使用 Secret envFrom注入环境变量AWS使用 ECS 任务定义中的环境变量或引用 Secrets ManagerGCPCloud Run 的--set-env-vars/ Secret ManagerDocker Composeenvironment:字段或.env文件。由于配置通过环境变量注入同一个镜像可以在开发、预发、生产多个环境间复用。社区贡献的部署指南对于 Kubernetes 之外的平台仓库的 contrib/docs/tutorials 目录维护了社区贡献的实战指南与本主题强相关的包括aws-fargate-deployment.mdECS / Fargate 部署aws-deployment.mdAWS 部署通用流程aws-alb-aad-oidc-auth.mdAWS ALB Azure AD OIDC 认证heroku-deployment.md、koyeb-deployment.md、flightcontrol-deployment.mdPaaS 平台部署。此外部署总览 解释了所有这些指南共同依赖的底层模型无状态应用 外部 PostgreSQL 单镜像产物。Kubernetes 是官方维护的参考路径Backstage 官方维护了 Kubernetes 路径的参考指南 Deploying with Kubernetes它逐步讲解了 namespace、Secret、Deployment、Service以及如何在集群内连接 PostgreSQL。核心步骤结合 k8s.md 的完整 YAML概括为创建 namespacekubectl create namespace backstage或 apply Namespace 定义。创建 PostgreSQL Secretbase64 编码的用户名密码注意base64 只是编码不是加密应启用集群的 Encryption at Rest。创建 PersistentVolume / PersistentVolumeClaim与 PostgreSQL Deployment、Service。创建 Backstage SecretGitHub token 等与 Backstage Deployment。创建 Backstage Service将 80 端口映射到 pod 的 7007。通过 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还是传统 VMBackstage 都能原样融入不需要学习新的部署范式。六、部署完成之后你的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Backstage 生产环境部署指南：从 Docker 镜像到多副本运行
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 数据库的形态不需要任何专用工具就能融入绝大多数现有发布流水线。一、部署前的前置条件在开始部署之前本系列前面的步骤已经为你准备好了三样东西它们是本节一切讨论的基础Docker 镜像按照 001-docker.md构建 Docker 镜像构建出的镜像同时打包了前端与后端是唯一需要被部署的产物。PostgreSQL 数据库按照 002-database.md配置生产数据库配置的可达数据库。生产环境不能用本地开发时的 SQLite——它不跨重启持久化数据也不支持多实例部署。真实认证提供方按照 003-authentication.md配置认证替换掉默认的 guest 登录。默认的 Guest 认证提供方 明确不适用于容器化/生产环境任何人只要能访问你的实例就共享同一身份和同一权限等级。从源码看默认 Docker 镜像的启动命令中直接带上了app-config.yaml和app-config.production.yaml两个配置文件这也印证了镜像构建 → 环境变量注入 → 配置分层这条链路的重要性详见下文配置与密钥一节。二、每个部署都需要什么六大必需要素无论你选择哪个平台一次完整的 Backstage 部署都必须覆盖以下六个关注点要素说明容器镜像从你的仓库构建并推送到运行时可以拉取的 registry。你在 构建 Docker 镜像 一节构建的镜像就是被部署的产物。配置与密钥以环境变量或挂载文件的方式交付给运行中的容器包括数据库凭据、认证提供方 client secret、各类集成 token。可达的 PostgreSQL运行实例能够用上一步的凭据连接到的数据库详见 配置生产数据库。网络入口通常是 ingress、负载均衡器或反向代理负责把后端暴露在7007 端口上并通过 HTTPS 提供给用户。带健康检查的运行时容器停止响应时能自动重启、发布新镜像时能滚动更新的运行时平台。app.baseUrl与backend.baseUrl在app-config.production.yaml中设置为用户访问 Backstage 的公网 URL。认证提供方和前端都依赖这两个值与实际入口一致。其中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 引入任何新基础设施。部署目标适用场景Kubernetes组织已经在 Kubernetes 上运行服务。Amazon ECS / Fargate使用 AWS 且倾向于托管容器调度。Google Cloud Run想要 GCP 上完全托管、按请求驱动的容器运行时。Azure Container Apps使用 Azure 且想要托管容器平台。传统 VM 或 PaaS更愿意直接在反向代理后面运行 Node.js 进程。Docker Compose小型安装或概念验证PoC。平台差异配置交付方式选择不同平台真正变化的不是 Backstage 本身而是配置与密钥的交付机制。结合 配置分层的原理可以总结出通用规律镜像只构建一次各环境只替换配置文件和环境变量。例如Kubernetes使用 Secret envFrom注入环境变量AWS使用 ECS 任务定义中的环境变量或引用 Secrets ManagerGCPCloud Run 的--set-env-vars/ Secret ManagerDocker Composeenvironment:字段或.env文件。由于配置通过环境变量注入同一个镜像可以在开发、预发、生产多个环境间复用。社区贡献的部署指南对于 Kubernetes 之外的平台仓库的 contrib/docs/tutorials 目录维护了社区贡献的实战指南与本主题强相关的包括aws-fargate-deployment.mdECS / Fargate 部署aws-deployment.mdAWS 部署通用流程aws-alb-aad-oidc-auth.mdAWS ALB Azure AD OIDC 认证heroku-deployment.md、koyeb-deployment.md、flightcontrol-deployment.mdPaaS 平台部署。此外部署总览 解释了所有这些指南共同依赖的底层模型无状态应用 外部 PostgreSQL 单镜像产物。Kubernetes 是官方维护的参考路径Backstage 官方维护了 Kubernetes 路径的参考指南 Deploying with Kubernetes它逐步讲解了 namespace、Secret、Deployment、Service以及如何在集群内连接 PostgreSQL。核心步骤结合 k8s.md 的完整 YAML概括为创建 namespacekubectl create namespace backstage或 apply Namespace 定义。创建 PostgreSQL Secretbase64 编码的用户名密码注意base64 只是编码不是加密应启用集群的 Encryption at Rest。创建 PersistentVolume / PersistentVolumeClaim与 PostgreSQL Deployment、Service。创建 Backstage SecretGitHub token 等与 Backstage Deployment。创建 Backstage Service将 80 端口映射到 pod 的 7007。通过 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还是传统 VMBackstage 都能原样融入不需要学习新的部署范式。六、部署完成之后你的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考