Skip to main content

目录配置

处理器​

目录的概念是处理器来执行目录摄取任务，如从远程源读取原始实体数据、解析、转换和验证。 这些处理器配置在catalog.processors配置键。

静态位置配置​

目录的最简单配置，如默认的@backstage/create-app模板，就是声明性地添加指向 YAML 文件的位置，并使用静态配置.

地点被添加到目录的catalog.locations键：

catalog:
  locations:
    - type: url
      target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/artist-lookup-component.yaml

url类型的位置由目录中包含的标准处理器 (UrlReaderProcessor因此无需对处理器进行配置。 该处理器然而需要整合来了解如何检索给定的 URL。 在上述示例中，您需要配置GitHub 集成来读取 github.com 上的文件。

通过静态配置添加的位置无法通过目录位置 API 删除。 要删除这些位置，必须从配置中删除它们。

语法错误或其他类型的错误出现在catalog-info.yaml错误不会导致处理中止。

当多个catalog-info.yaml的文件具有相同的metadata.name此操作将被记录，以便进一步调查。

本地文件(类型：文件)配置​

除 url 位置外，您还可以使用file位置类型从本地文件系统引入内容。 您只能将其用于本地开发、测试设置和示例数据，而不能用于生产数据。 您也不能在其中使用占位符，如$text不过，您可以相对于当前文件引用其他文件。 请参阅完整的此处的目录示例数据集以获取大量实例。

下面是一个例子，将all.yaml注意使用../../从后端程序的当前执行路径向上提升两级。 这通常是packages/backend/.

catalog:
  locations:
    - type: file
      target: ../../examples/all.yaml

集成处理器​

集成可能只是提供一种机制来处理url外部提供商的位置类型，或者它们还可能包括额外的开箱即用处理器，例如 GitHub发现处理器会扫描 GitHub 组织，以查找实体描述符文件.

检查集成文档，了解每个集成提供的功能。

定制处理器​

要从已在跟踪软件的现有系统中摄取实体，也可以编写一个定制处理器在现有系统和 Backstage 的描述符格式之间进行转换。外部集成.

目录规则​

默认情况下，目录只允许摄取类型为Component,API和Location为了允许添加其他类型的实体，需要在目录中添加规则。 规则可以在单独的catalog.rules键，或添加到静态配置的位置。

例如，配置如下

catalog:
  rules:
    - allow: [Component, API, Location, Template]

  locations:
    - type: url
      target: https://github.com/org/example/blob/master/org-data.yaml
      rules:
        - allow: [Group]

我们可以添加以下类型的实体Component,API,Location或Template从任何地点，以及Group实体从org-data.yaml，也会被读取为静态配置的位置。

请注意，如果catalog.rules键存在时，它将取代默认值，这意味着如果您希望仍然允许使用默认类型，则需要为默认类型添加规则。

以下配置将拒绝任何类型的实体添加到目录中：

catalog:
  rules: []

只读模式​

处理程序提供了一种很好的方法，当与静态位置配置或发现处理器，如发现 GitHub为了强制使用处理器来定位实体，我们可以将目录配置为readonly该配置禁止使用目录 API 注册和删除位置。

catalog:
  readonly: true

注意，任何依赖目录 API 来创建、更新和 > 删除实体的插件都无法在此模式下运行。

按 UUID 删除实体、DELETE /entities/by-uid/:uid在使用该模式时，可以重新发现它。明确删除.

这种配置的常见用例是，当组织有一个远程源，需要将其镜像到Backstage时。 要使Backstage成为该远程源的镜像，用户就不能同时在Backstage注册新的实体，例如目录-导入插件。

清理孤儿实体​

简而言之，实体可能会通过多种途径成为孤儿，例如，当目录信息 YAML 文件从版本控制系统中的一个地方移动到另一个地方而没有更新目录中的注册时。 出于安全考虑，默认行为是标记孤儿实体，并将其保留下来。 您可以阅读有关孤儿实体的更多信息这里.

不过，如果你希望自动删除孤儿实体，可以使用以下配置，所有带有孤儿实体标签的实体最终都会被删除。

catalog:
  orphanStrategy: delete

处理间隔​

处理环负责以一定的时间间隔在所有实体上运行已注册的处理器。 这个时间间隔可以用processingIntervalapp-config 参数。

catalog:
  processingInterval: { minutes: 45 }

值是一个持续时间对象，包含一个或多个字段years,months,weeks,days,hours,minutes,seconds和milliseconds您可以将它们组合起来，例如{ hours: 1, minutes: 15 }这意味着处理循环大约每 75 分钟访问一次实体。

请注意，这只是建议的最小值，实际间隔时间可能会更长。 目录内部会将该数字放大一个小系数，并在该范围内选择随机数来分散负载。 如果目录超载，无法在间隔时间内处理所有实体，那么处理任何给定实体的运行间隔时间也可能比此处指定的时间更长。

将该值设置得过低，可能会导致处理器查询的外部系统(如容纳目录信息文件的版本控制系统)耗尽速率限制。