Backstage Azure DevOps Discovery 指南用实体提供者自动发现目录实体【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本指南完整讲解 Backstage 中 Azure DevOps 集成的自动发现能力如何通过 Azure DevOps 实体提供者Entity Provider推荐方案或 Azure DevOps Discovery 处理器Processor自动爬取整个 Azure DevOps 组织/项目/仓库将与路径模式匹配的catalog-info.yaml注册进软件目录。读完本文你将掌握从依赖准备、安装插件、配置多提供者到理解底层代码搜索调用链的完整实战方案摆脱手动注册实体的繁琐工作。概述从静态位置到自动发现在 Backstage 软件目录中实体通常通过静态目录配置或 catalog-import 插件手动添加。当组织内仓库数量庞大时逐条维护位置location成本很高。Azure DevOps 集成为此提供了一个专门的实体提供者它会爬取整个 Azure DevOps 组织通过配置的路径模式匹配并注册所有符合条件的目录实体。这可以作为静态位置或手动添加方式的理想替代方案。本文涉及的核心模块位于仓库 plugins/catalog-backend-module-azure其中包含两个实现途径AzureDevOpsEntityProvider推荐基于后端调度器周期性刷新配置在catalog.providers.azureDevOps下AzureDevOpsDiscoveryProcessor传统方案通过azure-discovery类型的位置在目录处理流程中按需触发。前置依赖Code Search 功能必须开启Azure 发现功能由 Azure DevOps 的Code Search代码搜索功能驱动该功能默认可能未启用Azure DevOps Services云版在组织设置Organization Settings中查看已安装的扩展列表Azure DevOps Server本地版在集合设置Collection Settings中查看。如果未列出 Code Search 扩展可从 Visual Studio Marketplace 搜索安装ms.vss-code-search扩展。为什么依赖它从源码可以看出实体提供者的整个发现逻辑都建立在 Azure DevOps 代码搜索 API 之上——codeSearch 会向_apis/search/codesearchresults接口发起 POST 请求搜索条件为path:path repo:repo proj:project。没有 Code Search发现流程将无法执行。Azure 集成配置认证前提必须先完成 Azure 集成 的配置提供host与认证凭据云版用户host必须为dev.azure.com本地部署用户设置为本地主机名。认证方式支持服务主体client secret / 托管身份、个人访问令牌PAT等例如integrations: azure: - host: dev.azure.com credentials: - clientId: ${AZURE_CLIENT_ID} clientSecret: ${AZURE_CLIENT_SECRET} tenantId: ${AZURE_TENANT_ID}安装插件由于 Azure 发现提供者不属于默认提供者需要先安装 Azure 目录插件# 在 Backstage 根目录下执行 yarn --cwd packages/backend add backstage/plugin-catalog-backend-module-azure随后在后端入口注册该模块// packages/backend/src/index.ts backend.add(import(backstage/plugin-catalog-backend)); backend.add(import(backstage/plugin-catalog-backend-module-azure));从模块注册源码 catalogModuleAzureDevOpsEntityProvider.ts 可以看到该模块会检查配置中是否存在catalog.providers.azureDevOps存在时调用AzureDevOpsEntityProvider.fromConfig将提供者挂载到目录处理扩展点catalogProcessingExtensionPoint并通过catalogScmEventsServiceRef桥接 Azure DevOps 的 SCM 事件webhook实现更及时的增量感知。配置提供者一个或多个 provider在app-config.yaml中新增一个或多个提供者配置catalog: providers: azureDevOps: yourProviderId: # 标识你的数据集 / 提供者与配置变更无关 organization: myorg project: myproject repository: service-* # 匹配所有以 service-* 开头的仓库 path: /catalog-info.yaml schedule: # 可选选项同 SchedulerServiceTaskScheduleDefinition # 支持 cron、ISO 时长、human duration代码中的人类可读时长 frequency: { minutes: 30 } # 支持 ISO 时长、human duration timeout: { minutes: 3 } yourSecondProviderId: # 标识你的数据集 / 提供者与配置变更无关 organization: myorg project: * # 匹配所有项目 repository: * # 匹配所有仓库 path: /catalog-info.yaml anotherProviderId: # 另一个标识符 organization: myorg project: myproject repository: * # 匹配所有仓库 path: /src/*/catalog-info.yaml # 在 /src 目录内深层查找文件 yetAnotherProviderId: # 再来一个哈哈 :) host: selfhostedazure.yourcompany.com organization: myorg project: myproject branch: development参数详解参数必填说明host可选默认值为dev.azure.com对于旧版{org}.visualstudio.com域名或本地部署on-premise实例为必填。organization必填组织 slug本地部署用户为 Collection 名称。project必填项目 slug。支持通配符见上方示例*表示搜索所有项目。项目名含空格时需用单双引号包裹如project: My Project Name。repository可选仓库名支持通配符未设置时搜索所有仓库。path可选查找catalog-info.yaml的位置默认为/catalog-info.yaml。branch可选要使用的分支名。schedule可选调度配置选项同SchedulerServiceTaskScheduleDefinitionschedule.frequency—任务运行频率。系统会尽力避免重叠调用。支持 cron、ISO 时长、代码中使用的人类可读时长。schedule.timeout—单次任务调用的最大执行时长。支持 ISO 时长与人类可读时长。schedule.initialDelay可选首次调用前应经过的时间。schedule.scope可选global或local设置并发控制的作用域。配置解析的默认值可以从源码中得到印证config.ts 中host缺省为dev.azure.com、repository缺省为*、path缺省为/catalog-info.yamlschedule则通过readSchedulerServiceTaskScheduleDefinitionFromConfig读取与文档描述完全一致。关于 path 参数的注意事项path参数遵循与 Azure DevOps Web 界面搜索相同的规则可在 Azure DevOps 官方搜索文档中查阅更多细节。branch参数生效的前提是目标分支必须加入 Azure DevOps 仓库的Searchable branches可搜索分支列表。操作步骤进入 Azure DevOps打开要添加分支的仓库点击屏幕左下角的Settings设置在左侧导航栏选择Options选项在Searchable branches区域点击Add按钮添加新分支在弹出窗口中输入要添加的分支名称并点击Add添加的分支会出现在 Searchable branches 列表中。分支被索引并变为可搜索需要一些时间。底层原理实体提供者如何工作代码搜索与分页实体提供者的核心逻辑在 AzureDevOpsEntityProvider.refresh 中每次刷新都会调用codeSearch获取匹配文件列表然后对每个文件构造url类型的位置location并执行applyMutation({ type: full, entities })全量提交给目录。codeSearch的实现细节值得关注azure.ts云版dev.azure.com或*.visualstudio.com请求地址为https://almsearch.dev.azure.com本地部署则使用https://host搜索请求体为searchText: path:path repo:repo proj:project这正是通配符语义的来源指定了branch时会额外设置filters: { Branch: [branch] }分页以PAGE_SIZE 1000为页大小通过$skip滚动直到body.count items.length为止。位置Location构造每个匹配到的文件会被构造成如下 URL 形式的位置AzureDevOpsEntityProvider.createObjectUrlhttps://host/organization/project/_git/repository?pathfile.path[versionGBbranch]其中versionGBbranch中的GB前缀是 Azure DevOps 对分支名的 URL 编码约定——这一点在处理器Processor的 parseUrl 中也有对应处理解析version参数时会剥离GB前缀。提供者 vs 处理器两种方案的差异除了推荐使用的实体提供者仓库还保留了传统的AzureDevOpsDiscoveryProcessorAzureDevOpsDiscoveryProcessor.ts。它的工作方式是响应azure-discovery类型的位置例如target: https://dev.azure.com/org/project # 简写形式 target: https://dev.azure.com/org/project?path/catalog-info.yaml target: https://dev.azure.com/org/project/_git/repo # 指定单个仓库两种方案对比如下维度AzureDevOpsEntityProvider推荐AzureDevOpsDiscoveryProcessor触发方式按schedule周期性调度亦可由代码传入调度器在目录处理管道中按需触发配置位置catalog.providers.azureDevOps下多个提供者静态位置中的azure-discovery类型位置 presencerequiredAzureDevOpsEntityProvider.tsoptional通配符匹配可能部分不存在动态性刷新即全量applyMutation支持 webhook 事件桥依赖处理流程触发从源码结构看提供者是针对持续自动发现设计的首选方案处理器则更多保留用于静态位置场景的兼容。验证与测试仓库为提供者提供了完整的单元测试可作为配置与行为预期的参考AzureDevOpsEntityProvider.test.ts。测试通过ConfigReader构造integrations.azure与catalog.providers.azureDevOps配置mockcodeSearch结果后断言applyMutation提交的位置 URL 是否符合预期同时验证通配符项目/仓库、host覆盖、branch追加versionGB等行为。实际部署时可先在一个测试组织中使用project: *、repository: *观察发现结果再逐步收敛匹配范围。总结Azure DevOps Discovery 让 Backstage 目录与 Azure DevOps 仓库保持自动同步成为现实。推荐的落地路径是确认组织/集合已开启Code Search按 Azure 集成文档 配置认证云版 host 为dev.azure.com安装backstage/plugin-catalog-backend-module-azure并注册模块在catalog.providers.azureDevOps下按需配置一个或多个提供者善用project/repository通配符与schedule刷新策略若需指定非默认分支先将其加入 Azure DevOps 仓库的 Searchable branches 列表。掌握这套配置后新增仓库只需放入约定路径的catalog-info.yaml便会在下一次调度刷新时自动进入 Backstage 软件目录。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考