Backstage 导入
将您的 Backstage 目录导入 Archyl

Backstage 列出您正在运行的东西。Archyl 把同一份目录变成可导航的 C4 模型：System 成为系统，Component 和 Resource 成为容器，每个 API 实体成为一份契约，其 spec 原样保留，并与提供和消费它的服务相连。您继续使用 Backstage。所有权不会一起迁移过来，您得到的是两个 C4 层级作为起点。

查看定价
catalog-info.yamlBackstage
1apiVersion: backstage.io/v1alpha1
2kind: Component
3metadata:
4  name: checkout-api
5spec:
6  type: service
7  system: storefront
8  owner: payments-squad
9  providesApis: [checkout]
10  dependsOn:
11    - resource:orders-db
Reading…
app.archyl.com
Aurora Commerce/Containers
Search the architecture…K
ALMDKS
AI
导入内容

一切都能迁移到 Archyl

导入过程中，你的架构模型会完整保留。

Systems

每个 System 实体都会成为一个 C4 软件系统，保留其描述和标签。跨 namespace 重名的两个 System 会被重命名而不是合并，导入结果会告诉您是哪些。

Components

Component 会成为容器，挂在拥有它们的 System 之下，归属关系从 spec.system 或 partOf 关系解析得出。它们的 spec.type 会被映射：service 映射为服务，website 映射为 Web 应用，cronworkflow 映射为 worker，library 映射为库。

Resources

Resource 同样会成为容器，类型从 spec.type 得出。RDS 实例和 Valkey 集群成为数据库，Kafka topic 和 SQS 队列成为消息队列，S3 bucket 成为文件存储。

API spec

API 实体会成为 Archyl 的 API 契约。内联的 spec.definition 原封不动地保留，按 HTTP、gRPC、GraphQL 或 async 分类，并与提供和消费它的容器相连。

Relations

dependsOn、consumesApi、producesTo、consumesFrom 和 versionedIn 会成为带类型的关系。Backstage 对大多数 relations 会同时给出两个方向，导入只保留其中一个。consumesApi 这条边会穿过 API 一直解析到真正提供它的容器。

Namespace 与 lifecycle

您的 metadata.tags 原样带过来，namespace、lifecycle 和 type 也会作为带前缀的标签一并带上，让您在 Backstage 里精心整理的分组在架构模型中继续存在。

分步进行

几分钟完成迁移，而不是几天

无需复杂工具，无需手动重新录入。

1

导出目录

调用您 Backstage 的 catalog API 并保存响应。entities 端点会把它知道的每一个 System、Component、Resource 和 API 作为一个 JSON 数组返回。

2

选择 Backstage 格式

在 Archyl 的导入对话框中，选择 "Backstage" 标签页。它直接接受 Backstage 导出的 entities 数组，无需任何改造。

3

上传或粘贴 entities.json

上传文件或直接粘贴，然后进行校验。在您正式提交导入之前，Archyl 会报告 JSON 中的所有错误。

4

导入，然后读一遍警告

Archyl 会构建模型，并报告它创建了多少系统、容器、API 契约和关系，以及每一个不得不重命名的实体。之后请自行分配所有者：Backstage 的 Group 和 User 不会被导入。

你将获得

迁移后 Archyl 为你带来的能力

导入完成后，这些能力将直接作用于你带来的模型。

漂移检测

获取 0-100% 的健康评分，展示您的文档与实际代码库的匹配程度。在漂移积累之前发现它。

合规性规则

定义架构规则并运行自动化检查，确保您的系统保持在既定的防护范围内。

DORA 指标

跟踪部署频率、交付周期、变更失败率和恢复时间，同时监控架构健康状况。

MCP 服务器（191 个工具）

通过 191 个专业 MCP 工具从 Claude、Cursor 或 Windsurf 查询架构数据。

架构决策记录

将 ADR 直接链接到 C4 元素，使每个设计决策都有可追溯的上下文。

API 契约

将 OpenAPI、AsyncAPI 或 GraphQL 模式附加到容器和组件。保持契约与架构的版本一致。

团队在迁移前常问的问题

我们必须离开 Backstage 吗？

不必，而且大多数团队都不应该这么做。Backstage 是开发者门户，Archyl 是架构模型。导入读取的是目录导出文件，从不触碰您的 Backstage 实例，两者可以并行运行。Archyl 回答的是扁平目录回答不了的问题：这些服务如何拼接在一起、哪些地方已经与代码发生漂移、其中一个改动会让哪些契约失效。

导入能给我几个 C4 层级？

两个。System 落在 C4 第 1 层，Component 和 Resource 都作为容器落在第 2 层。Backstage 没有比 Component 更低的实体 kind，因此没有东西可以填充第 3 层。组件和代码元素需要您之后手动补充，或者把 Archyl 的 AI 发现指向代码仓库，再审批它给出的建议。

所有权会一起迁移吗？

不会。User 和 Group 实体会被跳过，ownedBy 关系也不会被映射，因此 spec.owner 不会变成 Archyl 中的所有者。这是唯一需要提前规划的事情：如果您使用 Archyl 的所有权地图，请在导入之后分配所有者。

我们的 OpenAPI 和 gRPC spec 会怎样？

带有内联 spec.definition 的 API 实体会把这份 spec 原封不动地保留为 Archyl 的 API 契约，按 spec.type 归类为 HTTP、gRPC、GraphQL 或 async，并与提供和消费它的容器相连。没有内联定义的 API 实体同样会导入，保留名称、描述和类型，只是没有正文。

导入会跳过什么？

User 和 Group 实体，以及指向它们的 ownedBy 关系。Location 和 Template 实体。metadata.annotations 和 metadata.links 这两个块，这意味着 TechDocs 指针不会被带过来。映射集合之外的 relations 会被忽略。对于重复和被重命名的实体，导入会给出警告。上面这些 kind 是在没有警告的情况下被丢弃的，所以本页把它们一一列出。

我们的目录里有几千个自动发现的 Resource，它们都会进来吗？

会。每一个 Resource 都会被导入，因为悄悄丢掉您精心整理过的数据，比导入得过多更糟。每个容器都会保留一个来自其 Backstage spec.type 的类型标签，嘈杂的类别仍然可以识别；您也可以在导出之前，用 Backstage 的 filter 查询参数在源头收窄导入范围。

目录变化后我们可以重新导入吗？

可以。再导出、再导入一次即可。Archyl 按名称匹配，更新它找到的内容，创建新增的内容，因此模型会跟随目录，而不是与之分叉。如果您想在 CI 中执行，同一套导入也通过 MCP 服务器的 import_dsl 工具以 backstage 格式对外提供。

永久免费方案

把您的目录看成一张架构图

一次导出、一次导入，您已经整理好的系统、服务、resource 和 API spec 就成为一个 C4 模型，之上还有漂移检测、合规性规则和 MCP 服务器。Backstage 继续做它该做的事。

  • 无需信用卡
  • 五分钟完成设置
  • 查看者始终免费
预约演示阅读快速入门

将Backstage目录导入Archyl: Backstage到C4

把Backstage Software Catalog变成可导航的C4模型。System、Component、Resource和内联API spec从entities.json导入。所有权仍留在Backstage。

backstage

Backstage

Backstage 导入

将您的 Backstage 目录导入 Archyl

Backstage 列出您正在运行的东西。Archyl 把同一份目录变成可导航的 C4 模型：System 成为系统，Component 和 Resource 成为容器，每个 API 实体成为一份契约，其 spec 原样保留，并与提供和消费它的服务相连。您继续使用 Backstage。所有权不会一起迁移过来，您得到的是两个 C4 层级作为起点。

将 Backstage 目录导入 Archyl | Backstage 到 C4

把您的 Backstage Software Catalog 变成可导航的 C4 架构模型。System、Component、Resource 和内联 API spec 从 entities.json 导入。所有权仍留在 Backstage。

Backstage 到 C4, Backstage 目录导入, 导出 Backstage 目录, Backstage 架构图, Backstage software catalog C4 模型, Backstage 架构文档

Systems

每个 System 实体都会成为一个 C4 软件系统，保留其描述和标签。跨 namespace 重名的两个 System 会被重命名而不是合并，导入结果会告诉您是哪些。

Components

Component 会成为容器，挂在拥有它们的 System 之下，归属关系从 spec.system 或 partOf 关系解析得出。它们的 spec.type 会被映射：service 映射为服务，website 映射为 Web 应用，cronworkflow 映射为 worker，library 映射为库。

Database

Resources

Resource 同样会成为容器，类型从 spec.type 得出。RDS 实例和 Valkey 集群成为数据库，Kafka topic 和 SQS 队列成为消息队列，S3 bucket 成为文件存储。

FileText

API spec

API 实体会成为 Archyl 的 API 契约。内联的 spec.definition 原封不动地保留，按 HTTP、gRPC、GraphQL 或 async 分类，并与提供和消费它的容器相连。

ArrowLeftRight

Relations

dependsOn、consumesApi、producesTo、consumesFrom 和 versionedIn 会成为带类型的关系。Backstage 对大多数 relations 会同时给出两个方向，导入只保留其中一个。consumesApi 这条边会穿过 API 一直解析到真正提供它的容器。

Namespace 与 lifecycle

您的 metadata.tags 原样带过来，namespace、lifecycle 和 type 也会作为带前缀的标签一并带上，让您在 Backstage 里精心整理的分组在架构模型中继续存在。

调用您 Backstage 的 catalog API 并保存响应。entities 端点会把它知道的每一个 System、Component、Resource 和 API 作为一个 JSON 数组返回。

FileCode

选择 Backstage 格式

在 Archyl 的导入对话框中，选择 "Backstage" 标签页。它直接接受 Backstage 导出的 entities 数组，无需任何改造。

上传或粘贴 entities.json

上传文件或直接粘贴，然后进行校验。在您正式提交导入之前，Archyl 会报告 JSON 中的所有错误。

导入，然后读一遍警告

Archyl 会构建模型，并报告它创建了多少系统、容器、API 契约和关系，以及每一个不得不重命名的实体。之后请自行分配所有者：Backstage 的 Group 和 User 不会被导入。

CircleCheckBig

Activity

获取 0-100% 的健康评分，展示您的文档与实际代码库的匹配程度。在漂移积累之前发现它。

定义架构规则并运行自动化检查，确保您的系统保持在既定的防护范围内。

ChartColumn

DORA 指标

跟踪部署频率、交付周期、变更失败率和恢复时间，同时监控架构健康状况。

MCP 服务器（191 个工具）

通过 191 个专业 MCP 工具从 Claude、Cursor 或 Windsurf 查询架构数据。