Backstage 为什么不是产品而是框架
一句话总结
Backstage 是 Spotify 把内部使用的开发者门户于 2020 年开源并捐赠给 CNCF 的项目（2022 年晋升为孵化级）。它不是装好就能直接使用的产品，而是用来搭建你自己门户的框架。不了解这一区别就贸然引入，一定会失败。
为什么需要它
向一个达到一定规模的组织提出下面这些问题，通常都得不到答案。
- 我们公司有多少个服务？
- 这个服务的负责人是谁？凌晨 3 点该叫醒谁？
- 谁在使用这个 API？现在把它下线，会破坏什么？
- 新来的开发者要完成第一次部署，需要读什么？
答不上来并不是因为没有信息，而是因为信息分散。负责人写在 Wiki 里，部署记录在 CI 仪表板上，依赖关系在某个人的脑子里，文档则躺在三年前的 Confluence 中。每一处单独看都是最新的，拼在一起却画不出任何完整的图景。
Backstage 的答案是：建立软件目录，并让这个目录从代码仓库中自动填充。 所有权信息如果就放在代码旁边（catalog-info.yaml），迁移代码时会一起迁移，也会经过评审，长期过期不更新的概率会大大降低。
工作原理
三根支柱
初次接触 Backstage，需要了解三样东西。
- 软件目录（Software Catalog）——我们拥有的一切及其相互关系的清单。它是 Backstage 的心脏。
- 软件模板（Software Templates / Scaffolder）——按黄金路径创建新服务的装置。
- TechDocs——把放在代码旁边的 Markdown 文档渲染后显示在门户中的功能。
在此之上还有插件生态。Kubernetes、CI、On-call 值班、成本、安全扫描器等各个工具的信息，都被拉取到实体页面中。这正是门户的核心价值——不是把工具合并成一个，而是以实体（服务）为中心汇集并展示信息。
前端插件与后端插件
Backstage 分为两个应用。
| 前端 | 后端 | |
|---|---|---|
| 是什么 | React 应用 | Node.js 服务 |
| 插件的作用 | 提供页面、标签页、卡片、图标 | API 端点、数据采集、对外部系统的认证 |
| 示例 | 实体页面上的“Kubernetes”标签页 | 查询集群并获取工作负载的服务 |
| 为什么要分开 | 浏览器中不应放置凭据 | 令牌和 Secret 只保存在服务器上 |
这种分离在安全上很重要。如果前端插件直接调用 Kubernetes API，用户的浏览器里就需要持有集群凭据。因此由后端插件代为调用，前端只调用后端的端点。
为什么它不是产品
要使用 Backstage，需要通过 npx @backstage/create-app 创建属于你自己的应用源码树。此后它就是你自己的代码。添加插件要修改代码、构建、部署，升级也由你自己负责。
这个选择的利弊很分明。
- 优点——可以按组织需要随意修改。可以开发并接入内部专用插件，也可以用本组织的语言来定义信息结构。
- 缺点——需要有人长期维护。必须有一支能处理 TypeScript/React 的团队常驻投入，升级负担会持续产生。
因此在 CBA 考试中，如果出现“安装 Backstage 就能得到可直接使用的门户吗？”之类的题目，答案是否定的。引入决策不是技术选型，而是人力配置决策。如果没有一支团队把这个框架当作产品来对待，6 个月后就会多出一个无人升级、被遗弃的门户。
在现场相遇的样子
只看作者自己的 7 节点家庭实验室，就能明白为什么需要目录。一个集群里运行着 Cilium（CNI）、MetalLB（L4 LB）、Cilium Gateway API（L7）、csi-driver-nfs（存储）、GPU Operator（4 块 GPU）、KubeVirt+CDI（虚拟化）、CloudNativePG（数据库）、kube-prometheus-stack（可观测）、Gitea（10.0.0.200）、Argo CD（10.0.0.201）、Harbor（10.0.0.202）和 Grafana（10.0.0.203）。每一个都有各自的来龙去脉——Gateway API 需要 CRD v1.6.1，KubeVirt 的 containerDisk 路径存在缺陷，需要用 DataVolume 绕过。
即使是一个人独自运维的家庭实验室，如果不把这份清单和来龙去脉记下来，半年后也会迷路，组织就更不用说了。把“有什么、为什么这样配置、谁清楚”放到人的脑子之外——这就是目录存在的理由。
这个集群反复给出的教训——“状态是 Ready”和“实际在正常工作”是两个不同的命题——同样适用于门户设计。在实体页面上放几个绿色徽章很容易，难的是这些徽章是否与真实的用户体验相连。门户只是汇集信息的工具，汇集起来并不等于这些信息就是真的。
下一项测验要确认什么
本模块以测验收尾。下一个模块将学习目录的实体种类与关系，并在 /root/cba-catalog/ 中亲手编写一整套 catalog-info.yaml。实验环境中没有 Backstage 本身，因此会通过编写实体文件，并用集群标签来表达其所有权信息的方式来学习。