Backstage Bitbucket Server 目录发现Entity Provider 安装、配置与源码原理【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文围绕 Backstage 软件目录Software Catalog的 Bitbucket Server 集成完整讲解如何通过backstage/plugin-catalog-backend-module-bitbucket-server提供的实体提供器Entity Provider自动发现 Bitbucket Server 上各仓库中的 catalog 配置文件默认catalog-info.yaml并将其注册为 Location 实体、进而接入目录处理流水线。读完本文你将掌握该 Provider 的安装注册方式、事件驱动通道的选择、catalog.providers.bitbucketServer全部配置项的含义与默认值并能从源码层理解其分页扫描、过滤、位置校验与增量更新机制。工作原理从静态注册到自动发现Backstage 目录的数据来源通常有两种方式在静态配置中声明 Location或通过 catalog-import 插件手工注册。当 Bitbucket Server 上的仓库数量庞大、变更频繁时这两种方式都难以维护。Bitbucket Server 集成为此提供了一个专用的实体提供器BitbucketServerEntityProvider其工作流程是通过 Bitbucket Server REST API 分页枚举全部项目Project与仓库Repository按配置的过滤器项目键、仓库 slug、是否跳过归档仓库筛选对命中的仓库构造catalogPath指向的 catalog 文件位置将其作为Location 实体输出Location 实体进入目录处理流水线后catalog 文件内声明的所有实体Component、API、System 等会被逐一解析并收录进目录。这套机制可以作为静态 Location 或手动注册的替代方案实现仓库里放了catalog-info.yaml目录就自动有对应实体的自动化效果。前置条件配置 Bitbucket Server 集成使用该 Provider 之前必须先完成 Bitbucket Server 集成配置因为 Provider 在启动时会用host去匹配已注册的集成实例详见下文源码剖析。在app-config.yaml的integrations节点下添加 Bitbucket Server 条目支持 Token 与 Basic Auth 两种认证方式# Token 认证 integrations: bitbucketServer: - host: bitbucket.mycompany.com apiBaseUrl: https://bitbucket.mycompany.com/rest/api/1.0 token: ${BITBUCKET_SERVER_TOKEN}# Basic Auth 认证 integrations: bitbucketServer: - host: bitbucket.company.com apiBaseUrl: https://bitbucket.mycompany.com/rest/api/1.0 username: ${BITBUCKET_SERVER_USERNAME} password: ${BITBUCKET_SERVER_PASSWORD}各字段说明字段必填说明host是Bitbucket Server 实例主机名如bitbucket.mycompany.comtoken否Bitbucket Server 期望的个人访问令牌Personal Access Tokenusername否Basic Auth 用户名password否Basic Auth 密码注意 token 也可作为 password 的替代品使用apiBaseUrl否Bitbucket Server REST API 地址自托管实例通常为https://host/rest/api/1.0安装与后端注册该 Provider 默认不会被安装需要先向 backend 包添加依赖。在 Backstage 仓库根目录执行yarn --cwd packages/backend add backstage/plugin-catalog-backend-module-bitbucket-server随后在 backend 入口新后端系统的packages/backend/src/index.ts中注册相关模块// 可选如果希望通过 HTTP 端点接收外部事件 // backend.add(import(backstage/plugin-events-backend)); // 可选如果希望改用 AWS SQS 而非 HTTP 端点接收外部事件 // backend.add(import(backstage/plugin-events-backend-module-aws-sqs)); backend.add(import(backstage/plugin-events-backend-module-bitbucket-server)); backend.add( import(backstage/plugin-catalog-backend-module-bitbucket-server), );注册后后端模块 catalogModuleBitbucketServerEntityProvider 会自动读取配置、实例化 Provider 并挂载到目录处理扩展点同时启动 BitbucketServerScmEventsBridge 用于接收 Bitbucket Server 的 webhook 事件。选择外部事件接收通道事件是 Provider 实现推式增量更新的关键。你需要决定如何从 Bitbucket Server 接收事件可选通道包括通过 HTTP 端点接收events-backend通过 AWS SQS 队列接收events-backend-module-aws-sqs通过 Google Pub/Sub 接收events-backend-module-google-pubsub通过 Kafka 主题接收events-backend-module-kafka。无论选择哪种通道都需要 Bitbucket Server 侧配置对应的 webhook 订阅将仓库的repo:refs_changed推送等事件投递到上述通道。目录发现配置详解在app-config.yaml的catalog.providers下添加bitbucketServer配置段可配置一个或多个 Provider 实例catalog: providers: bitbucketServer: yourProviderId: # 用于标识你摄入的数据集 host: bitbucket.mycompany.com catalogPath: /catalog-info.yaml # 默认值 filters: # 可选 projectKey: ^apis-.*$ # 可选正则表达式 repoSlug: ^service-.*$ # 可选正则表达式 skipArchivedRepos: true # 可选布尔值 validateLocationsExist: false # 可选布尔值 schedule: # 与 SchedulerServiceTaskScheduleDefinition 的选项一致 # 支持 cron、ISO duration、代码中使用的 human duration frequency: { minutes: 30 } # 支持 ISO duration、human duration timeout: { minutes: 3 }配置项说明host必填Bitbucket Server 实例主机名。注意该主机必须同时注册为 integration否则 Provider 启动时会报错见下文。catalogPath可选查找catalog-info.yaml的路径默认/catalog-info.yaml。以/开头时表示相对仓库根目录的绝对路径例如/catalog-info.yaml、/backstage/catalog-info.yaml。filters可选projectKey可选用于按项目键过滤的正则表达式repoSlug可选用于按仓库 slug 过滤的正则表达式skipArchivedRepos可选布尔值过滤掉已归档的仓库。validateLocationsExist可选默认false。为true时会在产出 Location 之前校验其对应的 catalog 文件在源仓库中真实存在避免为不存在的文件生成无意义的 Location。schedule可选调度配置用于周期性全量刷新包含以下子项frequency任务执行频率多久运行一次系统会尽量避免重叠调用timeout单次任务运行的最大耗时initialDelay可选首次执行前的等待时间scope可选global或local设置并发控制的作用域。提示frequency、timeout、initialDelay均支持 cron 表达式、ISO 时长如PT30M以及代码中常见的可读时长格式如{ minutes: 30 }。配置读取的两种形态从源码 BitbucketServerEntityProviderConfig.ts 可以看到配置读取支持两种形态单实例简写若catalog.providers.bitbucketServer节点下直接存在host键则按单个 Provider 处理其id固定为default多实例形态否则按keys()遍历每个子键将子键作为 Provider 的id因此yourProviderId会体现在 Provider 名称中。对应的 Provider 名称格式为bitbucketServer-provider:id见 BitbucketServerEntityProvider.ts日志与任务 ID 中均会出现。源码剖析发现流程与底层实现集成校验与调度绑定在 BitbucketServerEntityProvider.fromConfig 中通过ScmIntegrations.fromConfig(config)构建集成注册表并调用integrations.bitbucketServer.byHost(providerConfig.host)匹配集成实例——若找不到匹配集成会抛出InputError提示No BitbucketServer integration found that matches host ...这正是host 必须注册为 integration的源码依据调度来源二选一代码传入的schedule任务执行器或配置中的schedule两者都没有时抛错拒绝启动。全量刷新Refresh周期性任务最终调用 refresh调用findEntities()扫描并解析全部候选实体通过connection.applyMutation({ type: full, ... })一次性提交将 Provider 发现的所有实体与目录当前状态做全量对齐替换式更新。findEntities()的内部流程BitbucketServerEntityProvider.ts与前面工作原理一节完全对应使用 BitbucketServerClient 分页拉取项目/projects与仓库/projects/{key}/repos依次应用projectKey、repoSlug正则过滤与skipArchivedRepos过滤若开启validateLocationsExist会调用getFile()请求.../raw/catalogPath端点404 时跳过该仓库debug 日志其他异常状态码记 warn网络异常记 error对每个通过的仓库构造type: url、presence: optional的 Location 交给解析器。默认解析器 defaultBitbucketServerLocationParser 会把它转换为一个 Location 实体locationSpecToLocationEntity为每个实体补充bitbucket.org/default-branch注解默认分支信息供后续事件处理判断是否为默认分支推送。事件驱动的增量更新Provider 在connect()时订阅主题bitbucketServer.repo:refs_changedBitbucketServerEntityProvider.ts。收到推送事件后onRepoPush 会校验事件处理所需依赖catalogApi与auth即 Catalog 服务与认证服务是否齐全重新解析该仓库的 Location 实体并对比目录中已存在的 Location按target匹配只有当事件确实发生在默认分支上时才继续处理避免功能分支推送触发无意义的目录变更对仍在的实体执行connection.refresh()刷新处理对有增删的实体通过applyMutation({ type: delta, added, removed })做增量对齐。此外外部通道收到的 webhook 原始事件会先经过 BitbucketServerScmEventsBridge订阅bitbucketServer主题由 analyzeBitbucketServerWebhookEvent 解析事件类型与负载再发布为目录 SCM 事件供各 Provider 消费。测试验证该模块的单元测试覆盖了上述关键路径例如 BitbucketServerEntityProvider.test.ts 通过 MSW mock REST API验证了项目/仓库分页枚举、过滤规则项目键、仓库 slug、归档仓库、validateLocationsExist的行为以及repo:refs_changed事件触发的增量更新配置解析的测试见 BitbucketServerEntityProviderConfig.test.ts。如需深入理解可从这些文件入手。实战注意事项host 一致性catalog.providers.bitbucketServer.id.host必须与integrations.bitbucketServer列表中某一项的host完全一致否则 Provider 初始化即失败catalogPath 的写法以/开头表示仓库根目录下的绝对路径客户端请求 raw 文件时会剥离前导/见 BitbucketServerClient.getFile性能权衡全量刷新会遍历所有项目与仓库分页拉取仓库规模大时建议合理设置frequency拉长周期并尽量用filters缩小扫描范围validateLocationsExist会为每个候选仓库额外发起一次 raw 请求开启后扫描请求量明显上升仅在有需要时启用事件通道 vs 轮询周期性调度属于拉式兜底事件驱动属于推式实时更新两者可同时启用事件通道保证推送后的近实时同步调度保证最终一致性单实例简写如果只有一个 Provider 且不关心命名可直接在bitbucketServer下写host等键简写形态此时 Provider ID 为default。通过上述配置即可在 Backstage 中实现对 Bitbucket Server 仓库目录文件的自动发现与持续同步让目录数据与代码仓库始终保持一致。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考