📚 课程目录第2章 Backstage平台基础

Backstage 平台基础：架构、插件机制、软件目录与网络拓扑的关系

Backstage 是由 Spotify 开源并捐赠给 CNCF 的开发者门户平台，其核心设计理念是“统一抽象层”。在 IDP 网络拓扑查询场景中，Backstage 充当了拓扑数据的聚合与呈现中枢。理解其架构分层、插件扩展机制以及软件目录（Software Catalog）的数据模型，是后续优化查询性能与设计样本留存策略的理论前提。

2.1 整体架构分层

Backstage 采用典型的三层架构，每一层职责清晰，通过标准接口解耦：

层级	核心组件	职责说明	与网络拓扑的关联
前端层	App、Plugins、TechDocs	用户界面渲染、插件 UI 聚合、单页应用路由	拓扑图可视化、查询交互入口、实时筛选面板
后端层	Backend、Plugin Backends、Catalog API	业务逻辑处理、数据聚合、权限校验、事件分发	拓扑数据查询接口、缓存策略、样本留存服务
数据层	Database、Catalog Store、TechDocs Store	元数据持久化、实体关系存储、全文索引	网络设备/链路实体存储、拓扑关系图数据库

  架构要点： 前端不直接访问数据库，所有拓扑查询必须经过后端插件 API。这一约束保证了样本留存策略可以在后端统一实施，避免前端绕过审计。

2.2 插件机制：拓扑查询的扩展基础

Backstage 的插件（Plugin）是功能独立、可组合的微前端模块。每个插件拥有自己的前端组件和后端逻辑，通过统一的 createPlugin 接口注册到系统中。对于网络拓扑查询，插件机制提供了以下关键能力：

独立部署与隔离： 拓扑插件可以独立迭代，不影响其他插件（如 CI/CD、文档）的稳定性。
标准化 API 路由： 后端插件自动挂载到 /api/<plugin-id> 路径，便于统一鉴权和流量治理。
事件总线（Event Bus）： 插件之间通过 EventBroker 通信，拓扑变更事件可触发样本留存任务。
权限集成： 通过 PermissionFramework 控制不同团队对拓扑数据的查询范围。

实践建议： 在 IDP 项目中，建议将“网络拓扑查询”封装为一个独立插件（如 plugin-network-topology），后端包含查询优化中间件和样本留存服务，前端提供交互式拓扑图组件。这样既保持了架构清晰，又便于后续性能调优。

2.3 软件目录（Software Catalog）与网络拓扑的关系

Software Catalog 是 Backstage 的核心数据模型，采用实体（Entity）及其关系（Relation）来描述所有软件资源。网络拓扑本质上也是一种实体关系图，Catalog 的数据模型天然适合承载拓扑信息。

2.3.1 实体模型映射

Catalog 实体类型	网络拓扑对应对象	关键属性示例
`Component`	网络设备（路由器、交换机、防火墙）	`name`, `ipAddress`, `deviceType`, `location`
`Resource`	网络链路、带宽资源、子网	`bandwidth`, `linkType`, `vlanId`
`System`	网络区域（数据中心、POP 点、VPC）	`region`, `environment`, `owner`
`Domain`	网络自治域（AS）、租户隔离域	`asn`, `tenantId`, `securityZone`

2.3.2 关系模型：拓扑边的表达

Catalog 使用 Relation 来表达实体之间的连接。在网络拓扑中，这些关系直接对应物理或逻辑链路：

dependsOn：设备 A 依赖设备 B 提供路由可达性。
provides：设备 A 为设备 B 提供网络服务（如 DHCP、DNS）。
hasPart：一个网络区域包含多个子网或设备。
memberOf：设备属于某个安全组或集群。

2.4 实体描述文件（catalog-info.yaml）示例

网络设备在 Backstage 中通过 YAML 描述文件注册。以下是一个核心路由器的实体定义示例：

# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: core-router-01
  description: 核心骨干路由器，连接数据中心 A 与 B
  annotations:
    network/ip-address: "10.0.0.1"
    network/device-type: "router"
    network/asn: "64512"
    network/location: "dc-a-rack-01"
spec:
  type: network-device
  lifecycle: production
  owner: group:netops
  system: system:dc-a-network
  dependsOn:
    - component:core-router-02
    - resource:link-dc-a-to-dc-b
  provides:
    - resource:bgp-session-as64512

关键约束： 网络拓扑查询的样本留存策略必须与 Catalog 的实体生命周期对齐。当实体被标记为 lifecycle: deprecated 或 lifecycle: removed 时，对应的拓扑样本应自动归档或标记过期，避免留存无效数据影响查询性能。

2.5 拓扑查询的 Catalog 查询路径

当用户在前端发起网络拓扑查询时，Backstage 内部的数据流路径如下：

前端插件 调用 catalogClient.getEntities() 或自定义拓扑 API。
后端 Catalog API 解析查询条件（如 filter: { kind: 'Component', 'spec.type': 'network-device' }）。
数据层 执行 SQL 或图查询，返回匹配的实体列表及其关系。
后端插件 对结果进行拓扑关系组装（如构建邻接表、计算路径）。
样本留存服务 在返回结果前，根据配置策略记录查询样本（原始查询、耗时、结果集大小）。
前端接收拓扑数据，渲染为交互式网络图。