Backstage 技术 FAQ 全解析：技术栈选型、插件架构、镜像构建与安全治理

导读

本文基于 Backstage 官方技术 FAQ 文档 docs/faq/technical.md，系统梳理开发者在技术选型与架构认知阶段最常遇到的核心问题：技术栈为何选 TypeScript + React + Node.js、插件机制如何运作、为什么插件不能通过配置动态安装、没有官方 Docker 镜像时如何用 yarn build-image 自建镜像、插件能否用 JavaScript 编写、安全性如何保障等。读完本文，你将获得一套与仓库源码一一对应的、可直接落地实践的技术决策依据。

---

一、Backstage 的技术栈：TypeScript、React 与 Node.js

核心技术选型

Backstage 是一个大规模 TypeScript 框架，其技术栈分为前后端两部分：

• 前端：基于 React 与 Material UI 构建；
• 后端：基于 Node.js 与 Express 框架。

从当前仓库的包结构可以直观印证这一选型：前端核心位于 packages/core-components、packages/frontend-plugin-api 等目录（以 tsx/ts 为主，内部大量使用 Material UI 组件）；后端核心位于 packages/backend-defaults、packages/backend-plugin-api 等目录（以 ts 为主，底层依赖 Express 提供 HTTP 服务）。

为什么选用 Material UI？

FAQ 给出的答案很直白：Backstage 内部一直就在使用 Material UI。更深层的原因是：

1. Google Material Design 是一套完整、成熟的设计体系，且生态中已有大量成熟的组件库与辅助库；
2. 在能力、可定制性和易用性之间取得了良好平衡；
3. Backstage 的核心目标之一是让插件开发者以尽量少的阻碍投入生产，Material UI 既让插件作者使用熟悉的通用技术，又提供了庞大的现成组件库。

从仓库看，packages/ui 与 packages/core-components 中包含了大量基于 Material UI 封装的可复用组件，而 packages/theme 负责主题定制，这正是"插件作者直接用成熟组件快速开发"这一理念的落地。

---

二、Backstage 中的三类用户角色与端到端使用流程

FAQ 定义了 Backstage 的三种主要用户画像，理解它们有助于明确各自的职责边界：

角色	职责
整合者（Integrator）	托管 Backstage 应用，配置应用内可用的插件
贡献者（Contributor）	通过编写插件为应用增加功能
软件工程师（Software Engineer）	使用应用的功能，与插件交互

端到端的"幸福路径"（happy path）是：整合者搭建并配置应用 → 贡献者编写插件扩展功能 → 软件工程师使用插件完成日常工作。这一角色划分贯穿整个仓库：@backstage/create-app 脚手架面向整合者，packages/create-app/templates/default-app 是整合者的起点模板；plugins 目录则是开源插件的集合，由贡献者维护。

---

三、插件机制：Backstage 的功能单元

什么是插件？

插件（Plugin）是 Backstage 提供功能的方式。它们用于将不同系统集成到 Backstage 前端中，让开发者无论访问何种工具或服务，都能获得一致的 UX。每个插件都被视为一个自包含的 Web 应用，可以包含几乎任何类型的内容；所有插件共用一套框架 API 和可复用的 UI 组件；插件既可以从后端获取数据，也可以通过代理（Proxy） 暴露的 API 获取数据。

源码级印证

• 插件即独立包：从 docs/plugins/structure-of-a-plugin.md 可以看到，一个插件的标准目录结构包含 package.json、src/plugin.ts、src/routes.ts 等，看起来就像一个"迷你项目"，这正是为了支持插件作为独立 npm 包发布；
• 统一框架 API：插件的定义入口是 createPlugin 与 createRoutableExtension，它们来自 @backstage/core-plugin-api（对应仓库 packages/core-plugin-api），前端新系统的插件定义则位于 packages/frontend-plugin-api；
• 数据获取链路：FAQ 提到的"代理"对应配置中的 proxy 段。以应用模板 packages/create-app/templates/default-app/app-config.yaml.hbs 为例，proxy.endpoints 用于为前端添加代理端点，典型用途是处理内部服务的 HTTPS 与 CORS；后端则由 @backstage/plugin-proxy-backend 提供实现。

为什么不能用配置动态安装插件？

FAQ 明确指出这是 Backstage 核心架构与开发流程的一部分，原因有二：

1. 插件的集成方式自由度极高：插件在"提供什么内容"和"如何集成进应用"方面拥有很大自由，若允许通过配置像集成代码那样集成插件，会引入大量复杂度；
2. 依赖共享与加载优化：把所有插件及其依赖打包进同一个应用 bundle，插件之间可以尽可能共享依赖，从而显著优化应用加载时间——"快"是用户体验和开发者体验的重要组成部分。

从仓库模板 packages/create-app/templates/default-app/packages/app/src/App.tsx 可以看出，前端应用通过 createApp({ features: [...] }) 以代码方式声明式地注册插件；而后端模板 packages/create-app/templates/default-app/packages/backend/src/index.ts 通过 createBackend() 与 backend.add(import(...)) 逐一注册后端插件。这正是"用代码集成插件"这一架构决策的直接体现。

---

四、镜像构建与部署：为什么没有官方 Docker 镜像？

原因：Backstage 不是开箱即用的打包服务

FAQ 解释，Backstage 并不是一个可以开箱即用的打包服务，要上手必须使用 @backstage/create-app 包来创建并定制你自己的 Backstage 应用。正因如此，上游不发布官方 Docker 镜像或 Helm chart。

使用 yarn build-image 自建镜像

在自己的应用中构建 Docker 镜像，可以使用应用模板内置的 yarn build-image 命令。该命令默认会把前端与后端打包进同一个镜像，供你用任意熟悉的工具部署。

从仓库模板可以还原完整的构建链路：

1. 根级脚本（packages/create-app/templates/default-app/package.json.hbs）：

   "build:backend": "yarn workspace backend build",
   "build-image": "yarn workspace backend build-image"
   

2. backend 包脚本（packages/create-app/templates/default-app/packages/backend/package.json.hbs）：

   "build-image": "docker build ../.. -f Dockerfile --tag backstage"
   

3. Dockerfile 的构建前提（packages/create-app/templates/default-app/packages/backend/Dockerfile）：构建镜像前，需在仓库根目录依次执行：

   yarn install --immutable
   yarn tsc
   yarn build:backend
   

   且宿主机构建步骤（yarn install、yarn build:backend）必须与 FROM 基础镜像使用相同的 Node 版本，版本不匹配会破坏原生模块。

Dockerfile 关键细节

模板中的 Dockerfile 本身即可作为自建镜像的参考实现：

• 基础镜像为 node:24-trixie-slim；
• 安装 libsqlite3-dev 以支持 sqlite3（若镜像中不用 sqlite3 可跳过，并应将 better-sqlite3 移入 devDependencies）；
• 切换到最小权限的 node 用户运行后端，WORKDIR /app；
• 先复制 skeleton.tar.gz（monorepo 中每个包的 package.json 骨架 + yarn.lock + 根 package.json）以执行 yarn workspaces focus --all --production，避免不必要的 Docker 缓存失效；
• 再复制 bundle.tar.gz 与 app-config*.yaml，启动命令为：

  CMD ["node", "packages/backend", "--config", "app-config.yaml", "--config", "app-config.production.yaml"]
  

• 注意启用 BuildKit（DOCKER_BUILDKIT=1），确保应用目录以 node 用户创建，否则 tar 解包会因权限问题失败。

Kubernetes 部署示例

FAQ 提到仓库的 contrib 目录提供了部署到 Kubernetes 的示例。当前仓库中对应路径为 contrib/kubernetes/basic_kubernetes_example_with_helm，其中包含 app.yaml、backend.yaml 以及一个完整的 Helm chart（backstage/Chart.yaml），可作为整合者部署自有镜像的起点。

FAQ 同时说明：未来可能会提供示例镜像用于快速体验 Backstage 的小部分功能，但这类镜像不会比 demo 站点提供更多功能。

---

五、插件开发语言：必须用 TypeScript 吗？

FAQ 的回答是：不需要，你可以按偏好使用 JavaScript。Backstage 核心 API 保持 TypeScript 编写，但不会强制插件也使用 TypeScript。

这与仓库的实践一致：核心包（如 packages/core-plugin-api）均以 TypeScript 编写并提供类型定义，而插件层则允许使用 JS。如果你在编写插件前想确认某个插件是否已存在，可以浏览 Plugin Directory（插件目录）搜索；若找不到，可在社区插件仓库的 issue 中搜索是否已有同类工作，如果没有，可以新建一个插件建议 issue 描述你的插件功能，以避免重复造轮子。

---

六、插件生态的维护与托管模式

开源插件放在哪？

FAQ 明确：贡献者可以把开源插件添加到本 monorepo 的 plugins 目录（对应仓库 plugins 目录，当前已有 api-docs、catalog、scaffolder、search、techdocs、kubernetes 等大量插件）。整合者随后配置哪些开源插件在其应用实例中可用；开源插件以 npm 包形式从开源仓库发布并被下载。

闭源插件怎么办？

FAQ 同样支持闭源场景：贡献者可以在他们自己的 Backstage 仓库的 plugins 目录中开发闭源插件，整合者也可以在本地从 monorepo 配置闭源插件。即"鼓励开源模型，但允许内部实验与闭源"。

对其他代码托管平台的支持

FAQ 提到 Backstage 选择 GitHub 是因为团队最熟悉该工具，因此 GitHub 集成会较早开发，但这并不排除对 GitLab、Bitbucket 等替代方案的集成——随着时间推移，社区很可能会贡献这些工具的插件。同时，Backstage 的实现可以托管在任何你认为合适的位置。

---

七、维护、安全与数据治理

谁在维护 Backstage？

Spotify 维护开源核心，但项目不同部分由不同公司与贡献者共同维护；同时期待一个庞大、多样化的开源插件生态，由原作者/贡献者或社区维护。关于部署，则由系统整合者（通常是组织内的基础设施团队）在自己的环境中维护 Backstage。仓库根目录的 OWNERS.md 体现了这种多角色治理结构。

是否有商业/托管版本？

是的，FAQ 指出存在多个商业合作伙伴提供托管版本、企业支持与咨询等服务。

安全性如何保障？

FAQ 强调团队认真对待安全：定期扫描仓库中的包与代码，并将依赖包更新到最新版本。而组织内部的部署安全则取决于你所在组织的部署与安全设置。对于敏感安全问题，建议通过 Spotify 的漏洞赏金计划报告，而不是通过 GitHub。

Backstage 会收集共享给 Spotify 的数据吗？

FAQ 明确回答：不会。Backstage 不向使用该平台的任何第三方收集遥测数据。Spotify 与开源社区可以访问 GitHub Insights（包含贡献者、提交、流量、依赖等信息），但 Backstage 是开源框架，数据由你掌控——你可以控制谁有权访问你提供的数据以及数据与谁共享。

能否用于构建开发者门户之外的东西？

FAQ 的回答是肯定的：核心前端框架可用于构建任何大型 Web 应用，前提是 (1) 多个团队分别构建应用的不同部分，(2) 你希望整体体验保持一致。FAQ 同时提到项目的 Phase 2（见 docs/overview/roadmap.md）会加入开发者门户与管理软件生态系统所需的特性，并保持 Backstage 的模块化。

如何参与贡献？

FAQ 建议"直接上手"：修复早期 bug 与 good first issues、编写开源插件、查看 CONTRIBUTING.md。仓库根目录还有 AGENTS.md、REVIEWING.md 等协作文档可供进一步了解。

---

八、总结：FAQ 背后的架构决策主线

纵观全文，Backstage 的技术 FAQ 实际上勾勒出了一条清晰的架构决策主线：

1. 技术栈统一：TypeScript 贯穿前后端，React + Material UI 保证插件 UI 的一致性与开发效率，Node.js + Express 提供轻量后端；
2. 插件即代码：插件是自包含的独立包，通过代码而非配置集成，以换取依赖共享与加载性能；
3. 自托管部署：不做官方镜像，由整合者用 yarn build-image 构建前后端一体的镜像，再借助 contrib 中的 Helm 示例部署到 Kubernetes；
4. 开放且可控：插件可开源可闭源，数据归使用者所有，安全由社区与整合者共同守护。

如果你需要进一步了解 Backstage 的组成组件，可继续阅读 docs/overview/what-is-backstage.md；若关心产品层面的 FAQ（如版本策略、Spotify 内部插件开源计划等），可参考 docs/faq/product.md 与 docs/faq/index.md。