1. IDP 网络拓扑概述

在内部开发平台（IDP）的工程化实践中，网络拓扑是描述平台各组件之间通信关系、数据流向与依赖边界的核心模型。它不仅是运维层面的网络架构图，更是 Backstage 作为开发者门户进行资源查询、依赖分析与故障定位的底层数据基础。

1.1 IDP 网络拓扑的定义

IDP 网络拓扑是指：在内部开发平台范围内，以服务（Service）、基础设施（Infrastructure）、数据存储（Data Store）和外部依赖（External Dependency）为节点，以网络协议（HTTP/gRPC/TCP）、API 调用、消息队列和DNS 解析为边，所构成的有向或带权图结构。它通常包含以下四层抽象：

1.2 核心价值

在 IDP 中构建和维护网络拓扑，直接服务于以下四个工程目标：

1. 故障快速定界：当线上出现超时或错误率飙升时，拓扑图可直观展示受影响的服务链路，帮助工程师在 30 秒内定位故障影响范围。
2. 变更影响分析：在服务升级、数据库迁移或网络策略变更前，拓扑能自动列出所有下游依赖方，避免“改一处、崩一片”。
3. 合规与安全审计：通过拓扑清晰展示哪些服务可以访问敏感数据存储、哪些服务存在公网暴露面，满足内部安全合规要求。
4. 资源成本优化：识别出不再被调用的“僵尸服务”或冗余的网络连接，为平台降本提供数据依据。

1.3 在 Backstage 中的角色与定位

Backstage 作为开发者门户，其核心能力之一是统一资源目录。网络拓扑在 Backstage 中承担以下三个关键角色：

• 实体关系引擎：Backstage 的 catalog 模块通过 EntityRelation 存储服务间的 dependsOn、providesApi、consumesApi 等关系，这些关系正是拓扑图的边数据来源。
• 可视化查询入口：开发者无需跳转到 Grafana 或 Kiali，直接在 Backstage 的服务详情页即可查看该服务的上下游拓扑，实现“一站式排障”。
• 插件生态锚点：拓扑数据可以被 techdocs、scaffolder、lighthouse 等插件复用。例如，在创建新服务时，Scaffolder 可根据拓扑自动推荐需要对接的已有服务。

下图展示了 IDP 网络拓扑在 Backstage 中的核心定位——作为连接实体注册与开发者交互的中间层：

1.4 拓扑数据在 Backstage 中的存储模型

Backstage 使用 Entity-Relation 模型来存储拓扑关系。每个实体（Entity）通过 spec.dependsOn 或 spec.consumesApis 字段声明依赖。以下是一个典型的服务实体 YAML 示例：

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
  namespace: default
spec:
  type: service
  lifecycle: production
  owner: team-payment
  dependsOn:
    - component:default/payment-service
    - resource:default/order-db
  providesApis:
    - api:default/order-api
  consumesApis:
    - api:default/payment-api

下表总结了拓扑数据在 Backstage 中的三种主要查询模式：