2. Backstage 架构概览：核心组件、数据流与插件通信机制

在排查 IDP 自助门户故障之前，必须理解 Backstage 的运行时骨架。Backstage 采用 单页应用（SPA）前端 + 模块化后端 的架构，所有功能通过插件（Plugin）组装。本节从组件、数据流、通信三个维度拆解其核心设计。

2.1 三大核心组件

2.2 数据流全景

一次典型的用户操作（例如在 Catalog 页面查看服务信息）会经过以下数据路径：

1. 用户交互 → 浏览器中的 Plugin 前端组件触发事件。
2. 前端路由 → App 层将 URL 映射到对应 Plugin 页面。
3. API 请求 → Plugin 前端通过 fetch 或 useApi 调用 Backend 网关。
4. 后端路由 → Backend 将请求转发到目标 Plugin 后端。
5. 数据返回 → Plugin 后端处理业务逻辑（查询数据库、调用外部系统），返回 JSON。
6. 状态更新 → Plugin 前端更新 React 状态，重新渲染 UI。

2.3 插件通信机制

Backstage 的插件之间不允许直接耦合，所有跨插件通信必须通过以下三种标准化方式：

2.4 插件注册与依赖解析

每个插件在 app-config.yaml 或 packages/app/src/plugins.ts 中注册。Backend 启动时会执行依赖拓扑排序：

// packages/app/src/plugins.ts 示例
export const plugins = [
  catalogPlugin,          // 依赖：无
  scaffolderPlugin,       // 依赖：catalogPlugin
  techdocsPlugin,         // 依赖：catalogPlugin
  kubernetesPlugin,       // 依赖：catalogPlugin, scaffolderPlugin
  lighthousePlugin,       // 依赖：catalogPlugin
];

依赖解析失败时，Backend 日志会输出类似 Plugin "kubernetes" depends on "scaffolder" but it is not registered 的错误。

2.5 故障排查速查表