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

Backstage 平台基础：架构概述、插件机制与服务目录核心模型

在深入“变更门禁与回滚判断”实战之前，必须先理解 Backstage 的平台底座。本章从三个维度拆解：整体架构（组件如何通信）、插件机制（功能如何扩展）、服务目录核心模型（数据如何组织）。这三个知识点是后续水位采集、门禁策略注入、回滚触发的基础。

2.1 Backstage 架构概述

Backstage 采用典型的前后端分离 + 插件化架构。前端为单页应用（SPA），后端由多个独立微服务组成，通过统一的 Backstage Backend 层暴露 API。核心组件包括：

组件	职责	关键技术
App	前端壳，负责路由、主题、插件注册	React + Material UI
Backend	统一后端网关，处理认证、授权、事件	Node.js + Express
Plugin	独立功能模块，前后端成对出现	React + 后端插件包
Service Catalog	元数据存储与查询引擎	SQLite / PostgreSQL + GraphQL
TechDocs	技术文档管理	Markdown + mkdocs

  架构要点： 所有插件共享同一个后端运行时，通过 PluginProvider 注册路由和数据库迁移。服务目录是全局唯一的元数据中心，所有插件都通过 Catalog API 读取实体信息。

2.2 插件机制

Backstage 的插件是“一等公民”。每个插件都是一个独立的功能单元，包含前端组件和后端逻辑。插件之间通过 Extension Points 和 Event Bus 解耦通信。

2.2.1 插件生命周期

注册：在 app-config.yaml 或 packages/app/src/App.tsx 中引入插件包。
初始化：后端插件调用 createPlugin 注册路由、数据库表、事件监听器。
运行时：前端通过 useApi 调用后端 API，后端通过 Router 处理请求。
卸载：通过配置移除插件引用，数据库表需手动清理。

2.2.2 插件与服务目录的交互模式

交互模式	说明	典型场景
读取	通过 `CatalogClient` 查询实体	变更门禁读取服务水位
写入	通过 `CatalogApi` 创建/更新实体	水位采集插件写入指标
订阅	监听实体变更事件	回滚判断触发通知
扩展	通过 `EntityProvider` 注入自定义实体	自定义水位实体类型

实战提示： 在编写水位采集插件时，优先使用 CatalogClient 的 queryEntities 方法批量读取服务列表，避免逐个调用造成性能瓶颈。

2.3 服务目录（Service Catalog）核心模型

服务目录是 Backstage 的“元数据大脑”。所有实体（Entity）都遵循统一的 Common Entity Model，由 kind、metadata、spec、relations 四部分组成。

2.3.1 实体结构

// 实体核心结构
{
  "apiVersion": "backstage.io/v1alpha1",
  "kind": "Component",          // 实体类型
  "metadata": {
    "name": "my-service",       // 唯一标识
    "namespace": "default",
    "title": "我的服务",
    "description": "示例服务",
    "labels": {
      "tier": "critical"
    },
    "annotations": {            // 扩展注解，用于存储水位数据
      "watermark/cpu": "75",
      "watermark/memory": "60"
    }
  },
  "spec": {
    "type": "service",
    "lifecycle": "production",
    "owner": "team-a",
    "system": "platform"
  },
  "relations": [
    {
      "type": "dependsOn",
      "targetRef": "component:default/database"
    }
  ]
}

2.3.2 核心 Kind 类型

Kind	含义	水位关联
Component	软件组件（服务、库、应用）	直接关联水位指标
API	接口定义	通过依赖关系间接关联
Resource	基础设施资源（数据库、队列）	水位采集目标
System	系统边界	聚合水位视图
Domain	业务域	跨系统水位对比

2.3.3 水位数据在实体中的存储策略

水位数据（CPU、内存、错误率等）不适合直接写入 spec 字段，因为 spec 是静态配置。推荐两种方式：

Annotations（注解）：适合低频更新的水位快照，如每日水位基线。通过 watermark/cpu 等键值对存储。
自定义实体类型：通过 EntityProvider 注册 Watermark 类型，包含时间序列数据，适合实时水位。

注意： 注解方式有大小限制（通常 256KB），不适合存储大量历史水位数据。实时水位场景必须使用自定义实体类型，并配合独立的时序数据库（如 Prometheus）存储原始指标。

2.4 本章小结

Backstage 架构分为 前端 SPA → 后端网关 → 插件运行时 → 数据存储 四层，所有插件共享服务目录。
插件通过 CatalogClient 读写实体，通过 事件总线 监听变更，实现水位采集与门禁判断的解耦。
服务目录实体模型由 kind、metadata、spec、relations 组成，水位数据优先存储在 annotations（快照）或 自定义实体类型（时序）中。