Backstage v1.5.0-next.2 变更解析Bitbucket Server 实体发现、GitHub PR 审查者与 TechDocs CLI 增强【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage这篇技术指南以 Backstage 仓库中的 v1.5.0-next.2 变更日志 为主线深度解析本次预发布版本中面向目录Catalog、脚手架Scaffolder与 TechDocs 的三项核心变化并结合仓库源码说明其底层实现与升级路径。读完本文你将掌握如何用BitbucketServerEntityProvider替代旧的BitbucketDiscoveryProcessor完成 Bitbucket Server 的自动实体发现如何在publish:github:pull-request动作中为 PR 添加审查者以及如何通过--docker-option为 TechDocs 的docker run注入自定义参数。版本背景与本次变更总览v1.5.0-next.2是 Backstage 1.5 正式版发布前的第二个预发布快照对应 docs/releases 目录下以next为后缀的系列变更日志。这类next版本承载了该周期内已经合并、但尚未进入稳定版的所有改动供早期采用者在升级前先行验证。本版本共涉及约 60 个包除了大量依赖版本同步更新Patch Changes之外真正值得关注的行为级变更集中在以下几处包变更类型核心内容backstage/plugin-catalog-backend-module-bitbucket-serverMinor新增BitbucketServerEntityProvider替代BitbucketDiscoveryProcessorbackstage/plugin-github-issuesMinor新增展示 GitHub Issues 的前端插件backstage/plugin-scaffolder-backendMinorpublish:github:pull-request支持reviewers与teamReviewersbackstage/core-componentsMinorButton/Link的to属性收窄为仅支持字符串techdocs/cliMinor新增--docker-option透传docker run参数backstage/cliPatchWebpack 配置补充.json与.wasm解析backstage/create-appPatchCORSAccess-Control-Allow-Methods增加PATCH与HEADbackstage/plugin-kubernetes-backendPatchClusterDetails新增customResources字段backstage/plugin-catalog-backend-module-gitlabPatchGitLab provider 支持projectPattern正则过滤下文将围绕目录数据接入、脚手架动作与 TechDocs 工具链这三个主题深入展开其余纯依赖升级在此不做赘述。一、Bitbucket Server 实体发现从 Processor 到 Entity Provider迁移背景为什么引入新的实体提供者在 Backstage 新后端系统New Backend System的演进中目录的数据接入方式正从处理器 静态 Location逐步迁移为Entity Provider 定时调度。本次变更日志明确指出新增的catalog-backend-module-bitbucket-server插件提供的BitbucketServerEntityProvider是BitbucketDiscoveryProcessor的替代品适用于 Bitbucket Server 场景Bitbucket Cloud 此前已有对应的替代实现。二者最大的差异在于接入方式Processor 属于旧的builder.addProcessor(...)注册链路而 Entity Provider 通过builder.addEntityProvider(...)注册并依赖调度器SchedulerService周期性执行发现任务同时支持基于事件如repo:refs_changed的增量刷新。迁移前基于 Processor 的旧写法变更日志给出的迁移前配置包含两部分。首先是代码侧在packages/backend/src/plugins/catalog.ts中注册处理器// packages/backend/src/plugins/catalog.ts builder.addProcessor( BitbucketDiscoveryProcessor.fromConfig(env.config, { logger: env.logger }), );对应的app-config.yaml通过静态 Location 描述发现目标# app-config.yaml catalog: locations: - type: bitbucket-discovery target: https://bitbucket.mycompany.com/projects/*/repos/*/catalog-info.yaml这种写法依赖通配符 URL 展开来枚举仓库灵活性有限且无法按需筛选项目与仓库。迁移后基于 Entity Provider 的新写法迁移后的代码同样位于packages/backend/src/plugins/catalog.ts改为注册实体提供者并显式传入调度任务每 30 分钟执行一次、超时 3 分钟// packages/backend/src/plugins/catalog.ts builder.addEntityProvider( BitbucketServerEntityProvider.fromConfig(env.config, { logger: env.logger, schedule: env.scheduler.createScheduledTaskRunner({ frequency: { minutes: 30 }, timeout: { minutes: 3 }, }), }), );配置侧则迁移到catalog.providers.bitbucketServer节点支持多 Provider 实例通过yourProviderId区分用于标识不同的数据集合# app-config.yaml catalog: providers: bitbucketServer: yourProviderId: # identifies your ingested dataset catalogPath: /catalog-info.yaml # default value filters: # optional projectKey: .* # optional; RegExp repoSlug: .* # optional; RegExp配置项的源码级展开从 BitbucketServerEntityProviderConfig.ts 可以看到当前版本的 Provider 配置远不止变更日志示例中的三个字段。readProviderConfigs会先判断catalog.providers.bitbucketServer下是否直接存在host键若存在则视为单 Provider 简写形式自动使用默认 Provider IDdefault否则遍历每个子键作为独立 Provider 配置。完整支持字段如下也可参考 config.d.ts 的类型声明配置项类型默认值说明hoststring必填Bitbucket Server 实例主机名必须与 integrations 中的integrations.bitbucketServer配置匹配catalogPathstring/catalog-info.yaml每个仓库中目录清单文件的相对路径filters.projectKeyRegExp无按项目键正则过滤不匹配的项目被跳过filters.repoSlugRegExp无按仓库 slug 正则过滤filters.skipArchivedReposboolean无跳过归档仓库validateLocationsExistbooleanfalse在发出实体前先校验目标文件是否存在存在 404 时跳过并记录 debug 日志schedule任务调度定义无代码中未传schedule时的配置级调度定义在 BitbucketServerEntityProvider.ts 中fromConfig会校验两件事一是integrations.bitbucketServer.byHost(host)必须能找到匹配的集成配置否则抛出InputError二是必须通过代码参数options.schedule或配置providerConfig.schedule提供至少一种调度来源二者都缺失时直接报错。这解释了为什么示例中必须显式传入env.scheduler.createScheduledTaskRunner(...)。底层发现流程分页遍历与过滤findEntities方法BitbucketServerEntityProvider.ts完整呈现了发现流程通过BitbucketServerClient分页拉取全部项目listProjects若配置了projectKey正则则先做匹配过滤对每个项目分页拉取仓库列表listRepositories依次应用repoSlug正则与skipArchivedRepos过滤若开启validateLocationsExist先请求catalogPath指向的文件404 则跳过该仓库通过defaultBitbucketServerLocationParser解析每个仓库的目录文件为实体并自动写入默认分支注解bitbucket.org/default-branch最终以full类型的applyMutation将全部实体一次性提交给目录连接EntityProviderConnection。此外Provider 在connect阶段会订阅bitbucketServer.repo:refs_changed事件主题对应仓库的refs_changedWebhook。收到推送事件后onRepoPush会根据默认分支是否变更来决定执行增量增删deltamutation或仅刷新现有 Location 实体——这一行为要求同时注入catalogApi与auth否则 Provider 会在事件处理时记录配置不完整错误。该事件桥接的实现在 BitbucketServerScmEventsBridge.ts对应的 Webhook 事件解析逻辑见 analyzeBitbucketServerWebhookEvent.ts。同期变化GitLab provider 的projectPattern同一版本中plugin-catalog-backend-module-gitlab 的 Patch 也为 GitLab provider 增加了类似的正则过滤能力projectPattern按项目命名空间筛选仓库providers: gitlab: stg: host: gitlab.stg.company.io branch: main projectPattern: john/ # new option entityFilename: template.yaml上例表示只保留命名空间以john/开头的项目。可以看出v1.5.0 周期内目录生态的整体趋势是把发现范围的控制权下沉到 Provider 配置层。二、Scaffolder 动作增强为 GitHub PR 自动添加审查者新参数reviewers与teamReviewers变更日志宣布publish:github:pull-request动作新增reviewers与teamReviewers两个参数用于在动作创建 PR 后自动添加审查者。该动作的完整定义位于 githubPullRequest.ts当前仓库中该模块的report.api.md同样列出了这两个可选参数report.api.md。参数语义如下参数类型作用reviewersstring[]作为审查者添加到 PR 的用户列表teamReviewersstring[]作为审查者添加到 PR 的团队列表底层实现两阶段调用 GitHub API从源码看添加审查者并不是createPullRequest的原子操作而是在 PR 创建成功之后执行的第二步。githubPullRequest.ts中核心流程为正常创建 PR返回pr.owner、pr.repo、pr.number若reviewers或teamReviewers任一参数存在则调用requestPullRequestReviewers对应 GitHub API 的POST /repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers在调用前会先对teamReviewers做去重[...new Set(teamReviewers)]避免重复添加团队成功后在日志中输出实际添加的用户与团队列表Added users [...] and teams [...] as reviewers to Pull request ...失败则抛出包含 PR 编号的错误信息。这套逻辑在 githubPullRequest.examples.ts 与对应的示例测试 githubPullRequest.examples.test.ts 中有完整的用例覆盖可以作为模板编写与验证脚手架模板的参考。三、TechDocs CLI--docker-option透传 Docker 运行参数命令行为变化techdocs/cli1.2.0-next.2新增了--docker-option选项允许在serve与serve:mkdocs两个命令中向底层执行的docker run追加任意参数。例如在容器内访问宿主机服务时可以注入--add-hosttechdocs-cli serve --docker-option --add-hostinternal.host:192.168.11.12 # 或针对仅启动 MkDocs 的场景 techdocs-cli serve:mkdocs --docker-option --add-hostinternal.host:192.168.11.12该选项在 commands/index.ts 中定义为可重复出现的变长参数DOCKER_OPTION...帮助信息给出的示例即是--add-hostinternal.host:192.168.11.12实际传递发生在 serve.ts 与 mkdocs.ts二者都将opts.dockerOption映射为底层 Docker 运行配置的dockerOptions字段。这对需要挂载代理、自定义 DNS 或注入额外网络配置的企业环境尤其有用。四、其余值得关注的变更backstage/core-componentsto属性类型收窄Button与Link组件的to属性此前因类型过于宽松实际只支持普通字符串却容易让使用者误以为支持react-router-dom的对象形式{ pathname, search, hash }导致运行时出现意外行为。本次变更将其收窄为仅接受string在编译期即可暴露这类误用。backstage/create-appCORS 方法补齐新创建的应用模板默认配置更新Access-Control-Allow-Methods增加了PATCH与HEAD。已部署实例若需要让前端跨域调用 PATCH/HEAD 请求需手动同步app-config.yamlcors: origin: http://localhost:3000 - methods: [GET, POST, PUT, DELETE] methods: [GET, POST, PUT, DELETE, PATCH, HEAD]Kubernetes 相关plugin-kubernetes-backend 的ClusterDetails接口新增customResources字段允许按集群指定覆盖自定义资源定义plugin-kubernetes 的错误报告表格新增 namespace 列。构建与 CLIbackstage/cli在 Webpack 配置中补充了.json与.wasm文件的默认解析支持与 webpack 默认行为保持一致backstage/plugin-catalog-backend改用 knex 非弃用形式的table.uniquebackstage/plugin-catalog-backend-module-github改善了catalogPath中通配符的支持。五、升级建议与验证路径本版本是next预发布快照包含尚未进入稳定版的 API 与配置变化。建议关注以下几点Bitbucket Server 用户如果当前使用BitbucketDiscoveryProcessor可参照第一节的双段迁移示例将 Processor 与bitbucket-discoveryLocation 替换为BitbucketServerEntityProvidercatalog.providers.bitbucketServer配置。注意fromConfig要求integrations.bitbucketServer中存在与host匹配的条目且必须提供调度来源。Scaffolder 模板作者如需在模板产出的 PR 上自动添加审查者可直接在publish:github:pull-request的input中声明reviewers与teamReviewers数组参考 githubPullRequest.examples.ts。TechDocs 维护者--docker-option可解决本地预览时的容器网络/主机映射问题需使用升级后的techdocs/cli版本。本版本对应的完整变更清单见 docs/releases各模块的更细粒度演进可进一步查阅对应包的CHANGELOG.md与 docs/api 文档。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考