1. Backstage开发者门户工程导论
在微服务与多云基础设施成为主流的今天，一个研发团队往往同时面对几十甚至上百个服务、仓库、流水线、文档站点和监控面板。工程师想新建一个服务，需要翻找模板仓库、复制脚手架、手动改 CI 配置、申请域名、登记文档；想了解某个服务归谁负责，又要在聊天记录、Wiki 和代码仓库之间来回跳转。这类"信息散落、入口割裂、流程靠口口相传"的状态，正是开发者门户（Developer Portal）要解决的核心问题。
Backstage 是 Spotify 开源、现由 CNCF 托管的开发者门户框架。它不是一个开箱即用的成品网站，而是一套"框架 + 插件 + 软件目录"的工程底座：框架提供前端外壳、后端服务、认证与权限骨架；插件提供具体能力；软件目录则把企业内部所有软件资产登记成统一、可查询、可关联的实体。理解这三者的分工，是学习 Backstage 工程的第一课。
开发者门户的价值定位
开发者门户的价值可以归纳为三个层面。第一是统一入口：把分散在多个系统的能力收敛到一个站点，工程师通过一个 URL 就能完成服务创建、文档查阅、CI 状态查看、告警定位。第二是降低认知负荷：新成员不必先记住"哪个系统管什么"，门户通过软件目录和插件把上下文直接呈现出来。第三是标准化与治理：通过软件模板（Software Template）把"新建服务"这类高频操作固化为可审计的流程，让最佳实践以代码形式沉淀，而不是停留在文档里。
需要强调的是，门户本身不替代 CI/CD、监控或工单系统，它是这些系统的聚合层与编排层。判断一个门户是否成功，关键看它是否真正减少了工程师在工具间切换的次数，而不是看它集成了多少个插件。
Backstage 核心架构
Backstage 在运行时分为前端应用（App）与后端服务（Backend）两部分，二者通过 HTTP API 通信。前端由 React 构建，核心是"外壳 + 路由 + 插件页面"；后端由 Node.js 构建，核心是插件化的服务注册与依赖注入。软件目录（Catalog）既提供后端 API，也提供前端页面，是连接二者的中枢。下图展示了这一架构的主要组成与数据流向。
从图中可以看到，前端负责呈现与交互，后端负责数据聚合与外部调用，数据库保存实体与任务状态，外部系统通过后端集成接入。软件目录贯穿前后端，是门户的"数据骨架"。
软件目录与插件化设计理念
软件目录的核心是实体（Entity）。每个实体用一份 YAML 描述文件（通常命名为 catalog-info.yaml）声明，包含 apiVersion、kind、metadata、spec 四个顶层字段。常见的 kind 有 Component（组件/服务）、API、System、Domain、Resource、Group、User 等。下面是一个最小可用的组件实体示例：
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: payment-service
description: 支付核心服务
annotations:
github.com/project-slug: myorg/payment-service
spec:
type: service
lifecycle: production
owner: group:default/payment-team
system: payment-platform
这份文件提交到代码仓库后，由 Catalog 的实体提供者（Entity Provider）按配置的规则自动发现并注册。实体之间通过 owner、system、dependsOn 等字段建立关系，门户据此渲染出"谁负责什么、谁依赖谁"的关系图。这正是软件目录区别于普通资产清单的关键：它记录的是带关系的图，而不是孤立的表格行。
插件化设计则解决了"门户能力如何扩展"的问题。Backstage 把每一项能力都做成插件：Catalog、Scaffolder、TechDocs 是官方核心插件，Kubernetes、GitHub Actions、Grafana 等是社区或自研插件。插件通过统一的扩展点（Extension Point）挂载到前端路由和后端服务上，彼此之间通过 API 引用而非硬编码依赖。这种设计带来两个直接好处：一是团队可以只启用自己需要的插件，避免门户臃肿；二是新能力可以独立开发、独立发布，不必改动框架核心。
典型企业应用场景
在实际企业中，Backstage 最常见的落地场景有四类。其一是服务创建标准化：通过 Software Template 定义"新建微服务"模板，工程师填写服务名、负责人、语言栈后，系统自动创建仓库、生成脚手架代码、提交 catalog-info.yaml、配置 CI 流水线，把原本半天的工作压缩到几分钟。其二是服务归属与依赖可视化：借助 Catalog 的关系图，快速定位故障影响面。其三是文档统一托管：TechDocs 把各仓库的 Markdown 文档聚合成统一站点，支持按实体维度检索。其四是研发度量与治理：通过插件聚合 CI 成功率、部署频率等指标，为平台团队提供治理依据。
学习路线图
学习 Backstage 工程建议按"先跑通、再理解、后扩展"的顺序推进。第一阶段搭建本地环境，用 npx @backstage/create-app 创建应用，跑通默认门户，理解前端与后端的启动方式。第二阶段深入软件目录，手写 catalog-info.yaml，配置实体提供者，观察实体如何被发现、解析、建立关系。第三阶段开发一个最小插件，理解扩展点与依赖注入机制。第四阶段接入真实外部系统，如 GitHub、Kubernetes、CI 平台，并配置认证与权限。第五阶段面向生产，处理部署、升级、性能与多团队协作治理。这条路线从"能用"逐步走向"能扩展、能治理"，与本课程后续章节的展开顺序一致。