60 秒将你的 Backstage 目录变成真正的 C4 架构
Backstage 是那个目录。如果你在平台团队工作,你大概率花了几个月时间精心维护 catalog-info.yaml 文件、配置注解、修正 dependsOn 链接,以及在 Slack 上回答"为什么这个服务没出现"的问题。这份工作是真实的。它代表了你系统的真实地图。
但事情是这样:Backstage 的设计目标是列出你的软件,而不是建模它。组件页面有用。关系稀疏。C4 插件是事后想到的。你可以在一个扁平列表中滚动浏览 700 个服务,但你看不到它们如何拼接在一起。
如果你想要一个真正的架构视图,通常你有一个选择:在另一个工具中手动重建你的目录,或者将就 Backstage 提供的内容。
今天,这个选择消失了。
Archyl 现在直接导入你的 Backstage Software Catalog。 一次 curl、一次上传,你已经精心维护过的每个 System、Component、Resource 和 API 都将作为完整、可导航的 C4 模型出现 —— 关系、OpenAPI 契约、基础设施资源和元数据都完整保留。
60 秒,三个步骤
Backstage 通过单个 REST 端点暴露其完整的实体目录。拉取它,丢入 Archyl,完成。
第一步 —— 导出你的目录
curl -H "Authorization: Bearer $BACKSTAGE_TOKEN" \
https://backstage.your-company.com/api/catalog/entities \
-o entities.json
这就是整个导出。该端点流式传输 Backstage 知道的每个实体:Systems、Components、Resources、APIs、Groups、Users —— 一切。对于大多数组织,你会得到一个 5–30 MB 的 JSON 数组,包含数千个条目。
如果你在没有认证的情况下测试(一些 Backstage 实例允许在内部网络上公开读取目录),你可以去掉 Authorization 标头。如果你需要按 kind 过滤以保持文件较小,Backstage 支持查询参数:?filter=kind=component,kind=system,kind=api,kind=resource 会将响应缩减为 Archyl 实际映射的内容。
第二步 —— 打开导入对话框
在 Archyl 中,点击 导入项目(或在现有项目内的 导入),选择 Backstage 标签页,然后上传 entities.json 或直接粘贴它。
Archyl 会验证文件,然后在写入任何东西之前,准确显示将要创建的内容 —— 系统数量、容器数量、API 契约数量、关系数量。
第三步 —— 点击导入
你的项目被填充了。一个包含约 3000 个实体的 9 MB 目录在数秒内导入。你现在可以点击任何系统,在 C4 Level 2 中查看其容器布局,深入 API,并跨整个栈跟踪 dependsOn 边。
实际映射的内容
从 Backstage 导入的难点不在于读取 JSON —— 而在于在两种不同的心智模型之间翻译。Backstage 用类型化关系连接的扁平实体来思考。C4 用嵌套层级来思考。Archyl 是这样架起桥梁的:
| Backstage | Archyl | 备注 |
|---|---|---|
System |
C4 System (Level 1) | 跨命名空间的同名系统会自动消歧义 |
Component |
归属 System 下的 Container | service → service, cronworkflow → worker, website → web_app |
Resource |
归属 System 下的 Container | 类型感知:s3-bucket → file_storage; rds-instance、dynamo-db-table、valkey-cluster、opensearch-domain → database; kafka-topic、sqs-queue → message_queue; repository → library |
API(带 spec.definition) |
API 契约 | OpenAPI 3、gRPC、GraphQL、AsyncAPI 规范以内联方式保留,并链接到提供者/消费者组件 |
dependsOn、dependencyOf |
depends_on 关系 |
双向对会被自动去重 |
consumesApi |
uses 关系 |
通过 API 解析到其实际的提供者组件 |
producesTo、producedBy |
publishes_to 关系 |
|
consumesFrom、consumedBy |
consumes_from 关系 |
|
versionedIn、versions |
depends_on 关系 |
标记为 "source code" |
metadata.namespace、spec.lifecycle、spec.type、metadata.tags |
标签 | 全部转移用于过滤和叠加 |
User、Group |
跳过 | 人员图谱不是 C4 概念 |
没有 spec.system 的 Component 和 Resource 会进入一个名为 Uncategorized 的合成系统,这样就不会有任何东西被静默丢弃。
实践中最重要的两个细节:
- API 契约带着内容一起来。 每个包含
spec.definition的 BackstageAPI实体(你的内联 OpenAPI YAML、你的 gRPC.proto)都会作为 Archyl API 契约导入,完整规范附加并链接到提供者组件。无需手动重新上传规范。 - Resource 类型被保留。 一个 Kafka topic 不会变成一个通用的 "service" —— 它是一个
message_queue容器。一个 RDS 实例是database。一个 S3 bucket 是file_storage。你的可视化模型反映了每个基础设施部分的实际本质。
关于资源膨胀的一句话
如果你的组织在 Kubernetes 上重度运行,你的 Backstage 目录可能有数百 —— 也许数千 —— 个从集群自动发现的 external-secret、repository、datadog-service 和 load-balancer 资源。我们全部导入。
乍一看可能很多。确实是。
但你有几个选项:
- 保留并过滤。 每个导入的容器都带有
type:external-secret(或其他)标签。Archyl 的叠加层和标签过滤器允许你在图中隐藏它们,同时保持可查询。 - 批量删除噪音。 如果你不想在模型中看到某个类别,每个类型只需两次点击就能删除整个类别。
- 使用过滤器重新导出。 使用 Backstage 的
?filter=查询参数,在导入前排除你不关心的资源种类。
我们选择导入所有内容,因为替代方案 —— 静默丢弃我们认为你不需要的数据 —— 更糟。是你精心维护了你的目录。由你决定保留什么。
你实际上得到什么
Backstage 目录告诉你什么存在。Archyl 架构告诉你什么正在发生。
一旦你的目录在 Archyl 中存活,你就解锁了 Backstage 根本做不到的事情:
真正的 C4 图表。 交互式、可缩放、可在所有四个层级 —— System Context、Container、Component 和 Code —— 之间导航。点击任何服务深入其内部。跨整个栈跟踪一个关系。
漂移检测。 Archyl 持续将你记录的架构与你仓库中的实际代码进行比较。当你的目录说"服务 A 调用服务 B",但代码六个月前就停止这样做了,你会发现 —— 而不是在事故中发现。
架构合规性规则。 编码"支付域之外的服务不能调用 legacy-auth-api",或"所有外部调用必须经过 API 网关"。Archyl 自动强制执行,并在每个 PR 上暴露违规。
API 契约智能。 你一直喂给 Backstage 的 OpenAPI 规范现在生活在架构内部,与生产者和消费者关联。news-api 中的破坏性变更?精确查看哪些下游服务依赖于它。
与架构挂钩的 DORA 指标。 将部署频率、交付时间、变更失败率和 MTTR 连接到特定的系统、容器和团队。看哪些架构部分健康,哪些陷入困境。
Architecture Decision Records。 终于有一个地方在什么旁边写下为什么,直接链接到受影响的系统和组件。
MCP 集成。 你团队中的每个 AI 编码代理 —— Claude Code、Cursor、Windsurf —— 共享相同的架构上下文。停止反复向你的 LLM 解释你的服务如何拼接。
Backstage 目录回答"我们运行哪些服务?"。Archyl 回答"它们如何连接,什么在漂移,什么处于风险中,我们应该投资在哪里?"。导入你的目录意味着你不必在两者之间选择。
用于 AI 代理工作流
通过 Archyl 的 MCP 服务器暴露相同的导入。让 Claude Code、Cursor 或任何 AI 编码代理使用 format: "backstage" 和你的 entities.json 内容指向 import_dsl 工具 —— 你的架构就会落地,无需任何人触碰浏览器。
使用 import_dsl 工具:
- projectId: <你的项目 UUID>
- content: <entities.json 的内容>
- format: "backstage"
当你从 CI 脚本化目录同步,或者你希望 AI 助手在 Backstage 重大更新后刷新模型时很有用。
现在试试
如果你的团队今天运行 Backstage,你字面意义上离一个完整的 C4 架构只有一次 curl 之遥。
- 运行上面的 curl。
- 打开 Archyl,点击 导入项目,选择 Backstage。
- 看着你的服务、API、队列和数据库拼接成一个可导航的架构。
导入在每个套餐上都有效,包括免费层。我们认为你的决定不应该取决于你的目录是否可移植 —— 它应该取决于你接下来想用它做什么。
你的 Backstage 目录一直在等待成为一个架构。去让它成为吧。