Backstage v1.6.0 版本深度解读React Router v6 兼容、CLI 现代化与搜索能力全面增强【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage导读Backstage v1.6.0 是软件目录Software Catalog、开发者门户生态在 2022 年 9 月左右发布的一个重要版本。本版本横跨前端路由体系、CLI 工具链、目录服务、搜索、Scaffolder、认证等多个核心模块其中最值得关注的是全仓库对React Router v6 stable 的兼容性升级、CLI 将构建转译器从 sucrase 切换为swc、新增validateEntity校验接口与MultipleAnalyticsApi多分析后端能力以及全新的playlist播放列表插件与user-settings-backend后端服务。阅读本文后你将掌握 v1.6.0 的主要破坏性变更与迁移步骤、关键新增 API 的调用方式以及升级到该版本时需要注意的配置与工程实践。本文以仓库中的 docs/releases/v1.6.0-changelog.md 为主体结合仓库内对应模块的源码实现展开说明。版本总览一次横跨前端与后端的系统性升级v1.6.0 变更涉及约 90 个包既有新插件首发backstage/plugin-playlist、backstage/plugin-user-settings-backend也有大量 Patch 级修复与依赖升级。可以概括为以下几条主线React Router v6 stable 全面兼容core-app-api、core-components、test-utils以及数十个前端插件techdocs、search、catalog、permission 等都在本版本完成或开始适配 React Router v6。CLI 工具链现代化backstage/cli升到 0.19.0转译器从 sucrase 切换为 swc新增new、repo clean、migrate react-router-deps等命令。目录服务能力增强catalog-client新增validateEntitycatalog-backend支持实体 Provider 主动刷新、允许配置未知类型 location。搜索体验升级search-react新增SearchAutocomplete自动补全组件SearchResult支持query属性并提供SearchResultList/SearchResultGroup布局组件。认证与身份演进IdentityClient被标记废弃全面转向IdentityApiDefaultIdentityClientauth-backend的 Auth0 集成改用passport-auth0并支持audience参数。新插件首发playlist软件目录收藏清单、user-settings-backend用户设置持久化到数据库。CLI 0.19.0swc 转译、新命令与测试迁移backstage/cli0.19.0是本版本中影响面最广的变更之一涉及所有使用 Backstage CLI 的开发者。从 sucrase 切换到 swcCLI 将测试与构建的转译器从sucrase切换为swc。sucrase 在 Jest mock 支持上相对宽松而 swc 更严格地遵循 Jest 标准。文档给出了两种需要修改的典型测试写法无效写法在jest.mock工厂中直接引用jest.fn()的返回值const mockCommandExists jest.fn(); jest.mock(command-exists, () mockCommandExists);这种写法会抛出引用错误对应 Jest 官方文档中calling jest.mock with the module factory parameter的例子。需要改为延迟到 mock 被调用时才执行const mockCommandExists jest.fn(); jest.mock( command-exists, () (...args: any[]) commandExists(...args), );jest.spyOn与星号导入starred imports冲突由于 import 是不可变的对import * as something from ./something再执行jest.spyOn(something, test)会报TypeError: Cannot redefine property。正确做法是对星号导入的模块整体jest.mock让其中的函数从一开始就是jest.fn()jest.mock(../../helpers, () ({ executeFrameHandlerStrategy: jest.fn(), }));此外hot(App)用法与react-hot-loader已彻底被移除取代它的是 CLI 开箱即用的React Refresh。如果你在迁移后遇到测试运行困难可以在根package.json中临时回退到旧的 sucrase 转换配置jest: { transform: { \\.(js|jsx|ts|tsx|mjs|cjs)$: backstage/cli/config/jestSucraseTransform.js, \\.(bmp|gif|jpg|jpeg|png|frag|xml|svg|eot|woff|woff2|ttf)$: backstage/cli/config/jestFileTransform.js, \\.(yaml)$: jest-transform-yaml } }从仓库结构看packages/cli/config 目录正是 CLI 内置 jest 配置与各 transform 的存放位置可在升级后对照检查。新命令new、repo clean、migrate react-router-depsCLI 在本版本引入或调整了多个命令命令说明backstage-cli new取代create-plugin与create命令。新命名使其可以作为 yarn script 使用yarn create是保留字。create-app模板默认脚本更新为new: backstage-cli new --scope internalbackstage-cli repo clean清理仓库根目录并在所有包中运行 clean 脚本。根package.json的clean脚本建议改为clean: backstage-cli repo cleanbackstage-cli migrate react-router-deps辅助迁移到 React Router v6 stableversions:bump现在即使新版本在当前范围内也会更新package.json的依赖范围同时兼容 Yarn 3plugin:diff被废弃官方建议改用 bespoke 脚本如manypkg/get-packages枚举 monorepo 中的包同时CLI 新增了对 webpack dev server自定义证书的支持221e951298skeleton.tar.gz会排序条目以优化 Docker 层缓存cc63eb8611并移除了对 Lerna 的内部依赖——使用 Backstage CLI 全部功能不再要求安装 Lerna。根 package.json 与 remove-plugin 的移除remove-plugin命令已从 CLI 中删除。已有应用需要把根package.json做如下调整- remove-plugin: backstage-cli remove-plugin new: backstage-cli new --scope internaleslint-plugin-jest 升级到^27.0.0属于大版本更新包含部分破坏性变更可能让部分测试出现新的 lint 报错大多数可以通过yarn backstage-cli repo lint --fix自动修复。React Router v6 stable路由系统的核心升级backstage/core-app-api1.1.0将路由系统升级为与 React Router v6 stable 兼容这是本版本前端侧最重要的工作。核心变更点FlatRoutes兼容 v670299c99d5路由组件适配新版本 API。RoutedTabs与TechDocsReaderPage等组件适配core-components的RoutedTabs与 techdocs 的 reader 页面见 plugins/techdocs都针对 v6 做了兼容处理。React Router 依赖调整为 peer dependenciescore-app-api、test-utils以及大量前端插件都将 react-router 相关依赖改为 peer 依赖避免多实例冲突。Route子树内的pathprop 被忽略f9ec4e46e3v6 下Route元素树内部的组件若带有pathprop 会被忽略但不再报错。权限组件的废弃PermissionedRoute→RequirePermissionbackstage/plugin-permission-react将PermissionedRoute标记为废弃因为其用法与 React Router v6 stable 不兼容取而代之的是RequirePermission组件import { RequirePermission } from backstage/plugin-permission-react; RequirePermission permission{...} {/* 受保护的内容 */} /RequirePermission测试工具链的同步调整backstage/test-utils1.2.0中测试应用渲染的元素不再包裹Routes和Route因为这与 v6 不兼容。如果你的插件测试依赖这种包裹结构升级时需要同步调整。若希望手动迁移自己的应用或插件CLI 提供的migrate react-router-deps命令正是为此设计的辅助工具。软件目录validateEntity 校验接口与 Provider 刷新catalog-client 新增validateEntitybackstage/catalog-client1.1.0新增validateEntity方法调用后端的/validate-entity端点。仓库源码 packages/catalog-client/src/CatalogClient.ts 展示了其实现方法接收entity与locationRef两个参数调用 OpenAPI 客户端后响应ok时返回{ valid: true }仅当状态码为400时解析错误列表并返回{ valid: false, errors }其他非 2xx 状态直接抛出ResponseError。对应的测试位于 packages/catalog-client/src/CatalogClient.test.ts覆盖了合法实体、非法实体与异常响应等场景。这一能力对实现导入实体前校验的前端工具如 catalog-import 场景非常有用。catalog-backend 1.4.0Provider 可主动刷新、未知类型 location 可控backstage/plugin-catalog-backend1.4.0的 Minor 变更包括refresh函数EntityProviderConnection新增refresh方法6e63bc43f2实体 Provider 可以主动调度刷新而不必等待轮询周期对应的类型定义落在 packages/catalog-node 与 plugins/catalog-backend 中9743bc788c。允许通过配置注册未知类型 locationdd395335bcLocation service 不再默认拒绝未知类型的 location可通过配置放开。搜索索引保留超长字段的 null 值651c9d6800超长字段值以 null 形式保留在索引中便于按存在性过滤。hasAnnotation权限规则支持可选值07dda0b746错误消息写入数据库/日志前会限制长度以防性能问题06e2b077a1catalog 策略失败时错误消息会包含实体引用679f7c5e95。实验性CatalogProcessingExtensionPoint支持一次接受多个 provider 与 processor62788b2ee8并新增实验性的catalogServiceRef用于在新后端系统中获取CatalogClient7d7d947352。GitHub / Microsoft Graph Provider 相关修复catalog-backend-module-github支持按topic包含或排除仓库3a62594a11可为GitHubEntityProvider配置主机以对接GitHub Enterprise287a64bf97。catalog-backend-module-msgraph修复userExpand/groupExpand配置被忽略的问题c1d32d2b76用户查询增加$select属性并从microsoftGraphOrg配置读取queryModea246d5a9b8。搜索体验升级自动补全与可组合的结果布局backstage/plugin-search-react1.1.0是本次搜索模块的升级重点引入了多个新组件。SearchAutocomplete自动补全新增SearchAutocomplete组件与SearchAutocompleteDefaultOption用于渲染带图标、主文本、副文本的选项。仓库实现位于 plugins/search-react/src/components/SearchAutocomplete/SearchAutocomplete.tsx并配有 storybook 与测试SearchAutocomplete.stories.tsx、SearchAutocomplete.test.tsx。基本用法import { SearchAutocomplete, SearchAutocompleteDefaultOption } from backstage/plugin-search-react; const SearchPage () { const [inputValue, setInputValue] useState(); const options useAsync(async () { // 获取并返回自动补全选项 }, [inputValue]); return ( SearchAutocomplete options{options} inputValue{inputValue} inputDebounceTime{100} onInputChange{handleInputChange} getOptionLabel{option option.title} renderOption{option ( SearchAutocompleteDefaultOption icon{OptionIcon /} primaryText{option.title} secondaryText{option.text} / )} / ); };techdocs 的TechDocsSearch组件也改用该组件以统一搜索体验ca8d5a6eae。SearchResult支持queryprop 与两种布局组件SearchResult现在接受可选的queryprop 直接从搜索 API 请求结果未定义时仍从 context 消费结果SearchResult query{query} {({ results }) ( List {results.map(({ document }) ( DefaultResultListItem key{document.location} result{document} / ))} /List )} /SearchResult同时新增两个布局组件SearchResultListLayout以列表渲染结果与SearchResultGroupLayout以分组渲染结果并提供了二者的带状态封装SearchResultList与SearchResultGroup。后者支持filterOptions与renderFilterField可组合出带过滤器的搜索结果分组例如按 Lifecycle / Owner 过滤软件目录结果——这在搜索并分组软件目录结果的场景中可以直接套用完整示例见 docs/releases/v1.6.0-changelog.md 中CatalogResultsGroup组件。搜索上下文去重SearchContextProvider新增inheritParentContextIfAvailablepropca8d5a6eae把原先在SearchModal、SearchBar等组件中重复的是否存在父上下文检查收敛到 context provider 中。注意开启该属性后不会在有父上下文时创建本地 context因此不能与initialState一起使用会触发类型错误。Scaffolder 1.6.0表单增强与后端任务改进前端backstage/plugin-scaffolder1.6.0与后端backstage/plugin-scaffolder-backend1.6.0都有实质更新。前端表单能力next版本支持异步校验3424a8075dcreate/next下新增审查步骤review step192d856495。可调整步骤表单布局ad036784e9。EntityTagPicker字段支持showCounts显示并排序计数并可配置helperText6522e459aa修复EntityPicker空字符串 bug9ffb75616d与复杂依赖下 uiSchema 生成问题de336de9cd。Scaffolder 页面新增可关闭的 Error Bannerf0510a20b5。后端任务与动作任务 Worker 默认数量从 1 提升到 350467bc15b执行模板的任务并发能力显著增强相关实现可参考 plugins/scaffolder-backend/src/scaffolder/tasks/TaskWorker.ts 及其测试 TaskWorker.test.ts。github:publish动作支持配置 homepageea2eee9e6agitlab:publish输出新增projectId7db9613671Azure 建仓输出新增repositoryIdd1f7ba58e3。publish:file动作被移除2df9955f4a官方建议改用模板编辑器测试模板。支持处理模板中构建时无效但目标仓库内有效的损坏符号链接096631e571模板动作 context 中注入用户信息de8ee4afe3。DatabaseTaskStore现在应通过PluginDatabaseManager创建而非直接传Knex以便正确跳过迁移选项import { DatabaseManager, getRootLogger, loadBackendConfig } from backstage/backend-common; import { DatabaseTaskStore } from backstage/plugin-scaffolder-backend; const config await loadBackendConfig({ argv: process.argv, logger: getRootLogger() }); const databaseManager DatabaseManager.fromConfig(config, { migrations: { skip: true } }); const databaseTaskStore await DatabaseTaskStore.create(databaseManager);新插件首发playlist 与 user-settings-backendplaylist软件目录收藏清单backstage/plugin-playlist、backstage/plugin-playlist-backend、backstage/plugin-playlist-common三个包以 0.1.0 版本首发d3737da337。playlist 允许用户将目录实体整理进可分享的清单后端配套了权限permission相关依赖详情可查看仓库中的 plugins/playlist 相关 README。user-settings-backend用户设置持久化backstage/plugin-user-settings-backend0.1.0新增108cdc3912将用户相关设置存入数据库。与之配套前端backstage/plugin-user-settings0.4.8新增了UserSettingsStorage—— 一个StorageApi的实现可作为WebStorage的即插即用替代品与新的后端插件配合实现用户设置的跨端持久化8448b53dd6。WebStorage可观察对象返回JsonValue项的语义也在本版本得到澄清。认证与身份IdentityApi 迁移与 Auth0 audienceIdentityClient→IdentityApi/DefaultIdentityClientbackstage/plugin-auth-node将IdentityClient标记为废弃迁移目标为IdentityApiDefaultIdentityClientDefaultIdentityClient上的authenticate函数同样废弃应改用getIdentity。create-app模板已内置该配置迁移步骤为在packages/backend/src/index.ts的makeCreateEnv中创建并返回 identityimport { DefaultIdentityClient } from backstage/plugin-auth-node; function makeCreateEnv(config: Config) { ... const identity DefaultIdentityClient.create({ discovery, }); ... return { ..., identity } }后端插件升级时在RouterOptions中加入identity: IdentityApi即可在路由处理中获取当前用户router.get(/user, async (req, res) { const user await identity.getIdentity({ request: req }); ... });auth-backend侧scaffolder 等插件已改用getIdentity获取登录用户身份2cbd533426。Auth0 集成改用 passport-auth0 并支持 audiencebackstage/plugin-auth-backend0.16.0将 auth0 集成更新为使用passport-auth0库。auth.providers.auth0.*配置下新增可选audience参数配置后可以连接到正确的 API 获取权限、访问令牌与完整 profile 信息。同时废弃的AtlassianAuthProvider类被移除请改用providers.atlassian.create(...)2fc41ebf07。RedirectInfo类型重命名为OAuthStartResponsea291688bc5。允许向 JWT 添加杂项 claims5b011fb2e6Cloudflare Access Provider 在CloudflareAccessResult中附带 JWTe1ebaeb332。后端基础设施KubernetesContainerRunner、Helmet 6 与连接池保活KubernetesContainerRunnerbackend-common0.15.1实现了KubernetesContainerRunner一个基于 Kubernetes Job 运行容器的ContainerRunner实现bf3cc134eb可用于在集群中执行构建/脚手架容器。文档给出了完整示例通过KubeConfig加载集群配置指定命名空间、Job 名称前缀与挂载基础卷再定义 Pod 模板必须包含与mountBase.volumeName同名的卷定义最后调用runContainer指定镜像与参数。这一能力在 packages/backend-common 中可直接使用。Helmet 6 默认策略变化多个后端包app-backend、graphql-backend、kubernetes-backend、vault-backend升级helmet到^6.0.0。注意以下策略不再默认生效helmet.contentSecurityPolicy不再默认设置block-all-mixed-content指令helmet.expectCt不再默认设置可显式开启并将在 Helmet 7 中移除。DatabaseManager 连接池保活与允许主机端口范围DatabaseManager新增 keep-alive 刷新循环保持连接池活跃c3c90280be并支持传入可选logger以记录连接池相关日志DatabaseManager.fromConfig(config, { logger: root })的写法也已进入 create-app 模板。允许主机allowed hosts配置现在支持端口范围e3b1993788reading: allow: - host: *.examples.org:900-1000isomorphic-git包装器新增branch命令709f468330修复读取大型 zip 归档时条目被跳过或截断的问题0c780278e0。容器化与 Dockerfile 最佳实践更新create-app的packages/backend/Dockerfile在本版本有两处关键改进208d6780c9以最小权限的node用户运行新增USER node指令并通过COPY --chownnode:node确保所有应用文件归属node用户。设置NODE_ENV production所有 Node.js 模块以生产模式运行日志格式切换为默认生产格式JSON。FROM node:16-bullseye-slim RUN apt-get update \ apt-get install -y --no-install-recommends libsqlite3-dev python3 build-essential \ rm -rf /var/lib/apt/lists/* \ yarn config set python /usr/bin/python3 USER node WORKDIR /app ENV NODE_ENV production COPY --chownnode:node yarn.lock package.json packages/backend/dist/skeleton.tar.gz ./ RUN tar xzf skeleton.tar.gz rm skeleton.tar.gz RUN yarn install --frozen-lockfile --production --network-timeout 300000 rm -rf $(yarn cache dir) COPY --chownnode:node packages/backend/dist/bundle.tar.gz app-config*.yaml ./ RUN tar xzf bundle.tar.gz rm bundle.tar.gz CMD [node, packages/backend, --config, app-config.yaml, --config, app-config.production.yaml]日志格式变化示例从2022-08-10T11:36:05.478Z catalog info Performing database migration typeplugin变为{level:info,message:Performing database migration,plugin:catalog,service:backstage,type:plugin}若希望保留原有格式可在packages/backend/src/index.ts中显式设置彩色格式的 root loggergetRootLogger, setRootLogger, createRootLogger, coloredFormat, useHotMemoize, ... async function main() { setRootLogger(createRootLogger({ format: coloredFormat })); const config await loadBackendConfig({其他值得关注的插件更新TechDocsGCP Cloud Storage 发布器新增projectId配置项可覆盖凭据包中的隐式项目 IDaa524a5377见 plugins/techdocs-nodeS3/GCS 发布器修复未携带bucketRootPath的问题。Tech Insights允许在单个 scorecard 上展示不同类型的检查结果但包含三个BREAKING变更移除getScorecardsDefinition方法改由getCheckResultRenderers返回渲染组件、CheckResultRenderer类型改为暴露component工厂方法、EntityTechInsightsScorecardContent/EntityTechInsightsScorecardCard的title参数变为必填自定义渲染通过TechInsightsClient构造函数的renderers参数注入。Azure DevOps新增EntityAzureReadmeCard6c1c59b96e安装两步走先yarn add --cwd packages/app backstage/plugin-azure-devops再在实体页面中通过EntitySwitch.Case if{isAzureDevOpsAvailable}包裹卡片maxHeight属性可控制最大显示高度默认 100%。Dynatrace表格视觉改进、支持查看近期 Synthetics 结果并增加实例外链e44c0b3811。Stack Overflow后端 collator 支持分页拉取全部问题默认最大页数 100可用maxPage配置79040f73f7。Azure DevOps BackendcreateRouter现在需要额外的reader: UrlReader参数Azure 配置既可以放在azureDevOps下host/token/organization也可以放在integrations.azure下。Kubernetes Backend新增skipMetricsLookup配置项a57d29d572并导出KubernetesClientProvider与 auth-translator 相关模块。集成层GitHub App token 缓存从 10 分钟提升到 50 分钟同时缓存 app installations配置多个 GitHub App 时建议添加allowedInstallationOwners以最大化性能收益f76f22c649。Bitbucket Server 集成修复了 token 优先级问题42918e085c。升级建议与注意事项结合整个变更列表升级到 v1.6.0 时建议重点关注测试兼容性swc 转译对 mock 写法更严格运行yarn backstage-cli repo lint --fix修复 eslint-plugin-jest 新规则并参照上文改写不规范的 jest.mock / jest.spyOn。React Router v6 迁移使用backstage-cli migrate react-router-deps检查依赖注意PermissionedRoute已被RequirePermission取代。身份 API 迁移将IdentityClient/authenticate替换为IdentityApigetIdentity。数据库与容器DatabaseTaskStore/DatabaseDocumentStore改用PluginDatabaseManager创建确认 Dockerfile 的USER node与NODE_ENV production带来的日志格式变化是否符合预期。Helmet 6如依赖block-all-mixed-content或expectCt需要显式配置。被移除的能力publish:fileaction、remove-plugin命令、plugin:diff命令均已移除或废弃请改用官方推荐方案。完整的逐包变更明细可查阅仓库中的 docs/releases/v1.6.0-changelog.md。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Backstage v1.6.0 版本深度解读：React Router v6 兼容、CLI 现代化与搜索能力全面增强
Backstage v1.6.0 版本深度解读React Router v6 兼容、CLI 现代化与搜索能力全面增强【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage导读Backstage v1.6.0 是软件目录Software Catalog、开发者门户生态在 2022 年 9 月左右发布的一个重要版本。本版本横跨前端路由体系、CLI 工具链、目录服务、搜索、Scaffolder、认证等多个核心模块其中最值得关注的是全仓库对React Router v6 stable 的兼容性升级、CLI 将构建转译器从 sucrase 切换为swc、新增validateEntity校验接口与MultipleAnalyticsApi多分析后端能力以及全新的playlist播放列表插件与user-settings-backend后端服务。阅读本文后你将掌握 v1.6.0 的主要破坏性变更与迁移步骤、关键新增 API 的调用方式以及升级到该版本时需要注意的配置与工程实践。本文以仓库中的 docs/releases/v1.6.0-changelog.md 为主体结合仓库内对应模块的源码实现展开说明。版本总览一次横跨前端与后端的系统性升级v1.6.0 变更涉及约 90 个包既有新插件首发backstage/plugin-playlist、backstage/plugin-user-settings-backend也有大量 Patch 级修复与依赖升级。可以概括为以下几条主线React Router v6 stable 全面兼容core-app-api、core-components、test-utils以及数十个前端插件techdocs、search、catalog、permission 等都在本版本完成或开始适配 React Router v6。CLI 工具链现代化backstage/cli升到 0.19.0转译器从 sucrase 切换为 swc新增new、repo clean、migrate react-router-deps等命令。目录服务能力增强catalog-client新增validateEntitycatalog-backend支持实体 Provider 主动刷新、允许配置未知类型 location。搜索体验升级search-react新增SearchAutocomplete自动补全组件SearchResult支持query属性并提供SearchResultList/SearchResultGroup布局组件。认证与身份演进IdentityClient被标记废弃全面转向IdentityApiDefaultIdentityClientauth-backend的 Auth0 集成改用passport-auth0并支持audience参数。新插件首发playlist软件目录收藏清单、user-settings-backend用户设置持久化到数据库。CLI 0.19.0swc 转译、新命令与测试迁移backstage/cli0.19.0是本版本中影响面最广的变更之一涉及所有使用 Backstage CLI 的开发者。从 sucrase 切换到 swcCLI 将测试与构建的转译器从sucrase切换为swc。sucrase 在 Jest mock 支持上相对宽松而 swc 更严格地遵循 Jest 标准。文档给出了两种需要修改的典型测试写法无效写法在jest.mock工厂中直接引用jest.fn()的返回值const mockCommandExists jest.fn(); jest.mock(command-exists, () mockCommandExists);这种写法会抛出引用错误对应 Jest 官方文档中calling jest.mock with the module factory parameter的例子。需要改为延迟到 mock 被调用时才执行const mockCommandExists jest.fn(); jest.mock( command-exists, () (...args: any[]) commandExists(...args), );jest.spyOn与星号导入starred imports冲突由于 import 是不可变的对import * as something from ./something再执行jest.spyOn(something, test)会报TypeError: Cannot redefine property。正确做法是对星号导入的模块整体jest.mock让其中的函数从一开始就是jest.fn()jest.mock(../../helpers, () ({ executeFrameHandlerStrategy: jest.fn(), }));此外hot(App)用法与react-hot-loader已彻底被移除取代它的是 CLI 开箱即用的React Refresh。如果你在迁移后遇到测试运行困难可以在根package.json中临时回退到旧的 sucrase 转换配置jest: { transform: { \\.(js|jsx|ts|tsx|mjs|cjs)$: backstage/cli/config/jestSucraseTransform.js, \\.(bmp|gif|jpg|jpeg|png|frag|xml|svg|eot|woff|woff2|ttf)$: backstage/cli/config/jestFileTransform.js, \\.(yaml)$: jest-transform-yaml } }从仓库结构看packages/cli/config 目录正是 CLI 内置 jest 配置与各 transform 的存放位置可在升级后对照检查。新命令new、repo clean、migrate react-router-depsCLI 在本版本引入或调整了多个命令命令说明backstage-cli new取代create-plugin与create命令。新命名使其可以作为 yarn script 使用yarn create是保留字。create-app模板默认脚本更新为new: backstage-cli new --scope internalbackstage-cli repo clean清理仓库根目录并在所有包中运行 clean 脚本。根package.json的clean脚本建议改为clean: backstage-cli repo cleanbackstage-cli migrate react-router-deps辅助迁移到 React Router v6 stableversions:bump现在即使新版本在当前范围内也会更新package.json的依赖范围同时兼容 Yarn 3plugin:diff被废弃官方建议改用 bespoke 脚本如manypkg/get-packages枚举 monorepo 中的包同时CLI 新增了对 webpack dev server自定义证书的支持221e951298skeleton.tar.gz会排序条目以优化 Docker 层缓存cc63eb8611并移除了对 Lerna 的内部依赖——使用 Backstage CLI 全部功能不再要求安装 Lerna。根 package.json 与 remove-plugin 的移除remove-plugin命令已从 CLI 中删除。已有应用需要把根package.json做如下调整- remove-plugin: backstage-cli remove-plugin new: backstage-cli new --scope internaleslint-plugin-jest 升级到^27.0.0属于大版本更新包含部分破坏性变更可能让部分测试出现新的 lint 报错大多数可以通过yarn backstage-cli repo lint --fix自动修复。React Router v6 stable路由系统的核心升级backstage/core-app-api1.1.0将路由系统升级为与 React Router v6 stable 兼容这是本版本前端侧最重要的工作。核心变更点FlatRoutes兼容 v670299c99d5路由组件适配新版本 API。RoutedTabs与TechDocsReaderPage等组件适配core-components的RoutedTabs与 techdocs 的 reader 页面见 plugins/techdocs都针对 v6 做了兼容处理。React Router 依赖调整为 peer dependenciescore-app-api、test-utils以及大量前端插件都将 react-router 相关依赖改为 peer 依赖避免多实例冲突。Route子树内的pathprop 被忽略f9ec4e46e3v6 下Route元素树内部的组件若带有pathprop 会被忽略但不再报错。权限组件的废弃PermissionedRoute→RequirePermissionbackstage/plugin-permission-react将PermissionedRoute标记为废弃因为其用法与 React Router v6 stable 不兼容取而代之的是RequirePermission组件import { RequirePermission } from backstage/plugin-permission-react; RequirePermission permission{...} {/* 受保护的内容 */} /RequirePermission测试工具链的同步调整backstage/test-utils1.2.0中测试应用渲染的元素不再包裹Routes和Route因为这与 v6 不兼容。如果你的插件测试依赖这种包裹结构升级时需要同步调整。若希望手动迁移自己的应用或插件CLI 提供的migrate react-router-deps命令正是为此设计的辅助工具。软件目录validateEntity 校验接口与 Provider 刷新catalog-client 新增validateEntitybackstage/catalog-client1.1.0新增validateEntity方法调用后端的/validate-entity端点。仓库源码 packages/catalog-client/src/CatalogClient.ts 展示了其实现方法接收entity与locationRef两个参数调用 OpenAPI 客户端后响应ok时返回{ valid: true }仅当状态码为400时解析错误列表并返回{ valid: false, errors }其他非 2xx 状态直接抛出ResponseError。对应的测试位于 packages/catalog-client/src/CatalogClient.test.ts覆盖了合法实体、非法实体与异常响应等场景。这一能力对实现导入实体前校验的前端工具如 catalog-import 场景非常有用。catalog-backend 1.4.0Provider 可主动刷新、未知类型 location 可控backstage/plugin-catalog-backend1.4.0的 Minor 变更包括refresh函数EntityProviderConnection新增refresh方法6e63bc43f2实体 Provider 可以主动调度刷新而不必等待轮询周期对应的类型定义落在 packages/catalog-node 与 plugins/catalog-backend 中9743bc788c。允许通过配置注册未知类型 locationdd395335bcLocation service 不再默认拒绝未知类型的 location可通过配置放开。搜索索引保留超长字段的 null 值651c9d6800超长字段值以 null 形式保留在索引中便于按存在性过滤。hasAnnotation权限规则支持可选值07dda0b746错误消息写入数据库/日志前会限制长度以防性能问题06e2b077a1catalog 策略失败时错误消息会包含实体引用679f7c5e95。实验性CatalogProcessingExtensionPoint支持一次接受多个 provider 与 processor62788b2ee8并新增实验性的catalogServiceRef用于在新后端系统中获取CatalogClient7d7d947352。GitHub / Microsoft Graph Provider 相关修复catalog-backend-module-github支持按topic包含或排除仓库3a62594a11可为GitHubEntityProvider配置主机以对接GitHub Enterprise287a64bf97。catalog-backend-module-msgraph修复userExpand/groupExpand配置被忽略的问题c1d32d2b76用户查询增加$select属性并从microsoftGraphOrg配置读取queryModea246d5a9b8。搜索体验升级自动补全与可组合的结果布局backstage/plugin-search-react1.1.0是本次搜索模块的升级重点引入了多个新组件。SearchAutocomplete自动补全新增SearchAutocomplete组件与SearchAutocompleteDefaultOption用于渲染带图标、主文本、副文本的选项。仓库实现位于 plugins/search-react/src/components/SearchAutocomplete/SearchAutocomplete.tsx并配有 storybook 与测试SearchAutocomplete.stories.tsx、SearchAutocomplete.test.tsx。基本用法import { SearchAutocomplete, SearchAutocompleteDefaultOption } from backstage/plugin-search-react; const SearchPage () { const [inputValue, setInputValue] useState(); const options useAsync(async () { // 获取并返回自动补全选项 }, [inputValue]); return ( SearchAutocomplete options{options} inputValue{inputValue} inputDebounceTime{100} onInputChange{handleInputChange} getOptionLabel{option option.title} renderOption{option ( SearchAutocompleteDefaultOption icon{OptionIcon /} primaryText{option.title} secondaryText{option.text} / )} / ); };techdocs 的TechDocsSearch组件也改用该组件以统一搜索体验ca8d5a6eae。SearchResult支持queryprop 与两种布局组件SearchResult现在接受可选的queryprop 直接从搜索 API 请求结果未定义时仍从 context 消费结果SearchResult query{query} {({ results }) ( List {results.map(({ document }) ( DefaultResultListItem key{document.location} result{document} / ))} /List )} /SearchResult同时新增两个布局组件SearchResultListLayout以列表渲染结果与SearchResultGroupLayout以分组渲染结果并提供了二者的带状态封装SearchResultList与SearchResultGroup。后者支持filterOptions与renderFilterField可组合出带过滤器的搜索结果分组例如按 Lifecycle / Owner 过滤软件目录结果——这在搜索并分组软件目录结果的场景中可以直接套用完整示例见 docs/releases/v1.6.0-changelog.md 中CatalogResultsGroup组件。搜索上下文去重SearchContextProvider新增inheritParentContextIfAvailablepropca8d5a6eae把原先在SearchModal、SearchBar等组件中重复的是否存在父上下文检查收敛到 context provider 中。注意开启该属性后不会在有父上下文时创建本地 context因此不能与initialState一起使用会触发类型错误。Scaffolder 1.6.0表单增强与后端任务改进前端backstage/plugin-scaffolder1.6.0与后端backstage/plugin-scaffolder-backend1.6.0都有实质更新。前端表单能力next版本支持异步校验3424a8075dcreate/next下新增审查步骤review step192d856495。可调整步骤表单布局ad036784e9。EntityTagPicker字段支持showCounts显示并排序计数并可配置helperText6522e459aa修复EntityPicker空字符串 bug9ffb75616d与复杂依赖下 uiSchema 生成问题de336de9cd。Scaffolder 页面新增可关闭的 Error Bannerf0510a20b5。后端任务与动作任务 Worker 默认数量从 1 提升到 350467bc15b执行模板的任务并发能力显著增强相关实现可参考 plugins/scaffolder-backend/src/scaffolder/tasks/TaskWorker.ts 及其测试 TaskWorker.test.ts。github:publish动作支持配置 homepageea2eee9e6agitlab:publish输出新增projectId7db9613671Azure 建仓输出新增repositoryIdd1f7ba58e3。publish:file动作被移除2df9955f4a官方建议改用模板编辑器测试模板。支持处理模板中构建时无效但目标仓库内有效的损坏符号链接096631e571模板动作 context 中注入用户信息de8ee4afe3。DatabaseTaskStore现在应通过PluginDatabaseManager创建而非直接传Knex以便正确跳过迁移选项import { DatabaseManager, getRootLogger, loadBackendConfig } from backstage/backend-common; import { DatabaseTaskStore } from backstage/plugin-scaffolder-backend; const config await loadBackendConfig({ argv: process.argv, logger: getRootLogger() }); const databaseManager DatabaseManager.fromConfig(config, { migrations: { skip: true } }); const databaseTaskStore await DatabaseTaskStore.create(databaseManager);新插件首发playlist 与 user-settings-backendplaylist软件目录收藏清单backstage/plugin-playlist、backstage/plugin-playlist-backend、backstage/plugin-playlist-common三个包以 0.1.0 版本首发d3737da337。playlist 允许用户将目录实体整理进可分享的清单后端配套了权限permission相关依赖详情可查看仓库中的 plugins/playlist 相关 README。user-settings-backend用户设置持久化backstage/plugin-user-settings-backend0.1.0新增108cdc3912将用户相关设置存入数据库。与之配套前端backstage/plugin-user-settings0.4.8新增了UserSettingsStorage—— 一个StorageApi的实现可作为WebStorage的即插即用替代品与新的后端插件配合实现用户设置的跨端持久化8448b53dd6。WebStorage可观察对象返回JsonValue项的语义也在本版本得到澄清。认证与身份IdentityApi 迁移与 Auth0 audienceIdentityClient→IdentityApi/DefaultIdentityClientbackstage/plugin-auth-node将IdentityClient标记为废弃迁移目标为IdentityApiDefaultIdentityClientDefaultIdentityClient上的authenticate函数同样废弃应改用getIdentity。create-app模板已内置该配置迁移步骤为在packages/backend/src/index.ts的makeCreateEnv中创建并返回 identityimport { DefaultIdentityClient } from backstage/plugin-auth-node; function makeCreateEnv(config: Config) { ... const identity DefaultIdentityClient.create({ discovery, }); ... return { ..., identity } }后端插件升级时在RouterOptions中加入identity: IdentityApi即可在路由处理中获取当前用户router.get(/user, async (req, res) { const user await identity.getIdentity({ request: req }); ... });auth-backend侧scaffolder 等插件已改用getIdentity获取登录用户身份2cbd533426。Auth0 集成改用 passport-auth0 并支持 audiencebackstage/plugin-auth-backend0.16.0将 auth0 集成更新为使用passport-auth0库。auth.providers.auth0.*配置下新增可选audience参数配置后可以连接到正确的 API 获取权限、访问令牌与完整 profile 信息。同时废弃的AtlassianAuthProvider类被移除请改用providers.atlassian.create(...)2fc41ebf07。RedirectInfo类型重命名为OAuthStartResponsea291688bc5。允许向 JWT 添加杂项 claims5b011fb2e6Cloudflare Access Provider 在CloudflareAccessResult中附带 JWTe1ebaeb332。后端基础设施KubernetesContainerRunner、Helmet 6 与连接池保活KubernetesContainerRunnerbackend-common0.15.1实现了KubernetesContainerRunner一个基于 Kubernetes Job 运行容器的ContainerRunner实现bf3cc134eb可用于在集群中执行构建/脚手架容器。文档给出了完整示例通过KubeConfig加载集群配置指定命名空间、Job 名称前缀与挂载基础卷再定义 Pod 模板必须包含与mountBase.volumeName同名的卷定义最后调用runContainer指定镜像与参数。这一能力在 packages/backend-common 中可直接使用。Helmet 6 默认策略变化多个后端包app-backend、graphql-backend、kubernetes-backend、vault-backend升级helmet到^6.0.0。注意以下策略不再默认生效helmet.contentSecurityPolicy不再默认设置block-all-mixed-content指令helmet.expectCt不再默认设置可显式开启并将在 Helmet 7 中移除。DatabaseManager 连接池保活与允许主机端口范围DatabaseManager新增 keep-alive 刷新循环保持连接池活跃c3c90280be并支持传入可选logger以记录连接池相关日志DatabaseManager.fromConfig(config, { logger: root })的写法也已进入 create-app 模板。允许主机allowed hosts配置现在支持端口范围e3b1993788reading: allow: - host: *.examples.org:900-1000isomorphic-git包装器新增branch命令709f468330修复读取大型 zip 归档时条目被跳过或截断的问题0c780278e0。容器化与 Dockerfile 最佳实践更新create-app的packages/backend/Dockerfile在本版本有两处关键改进208d6780c9以最小权限的node用户运行新增USER node指令并通过COPY --chownnode:node确保所有应用文件归属node用户。设置NODE_ENV production所有 Node.js 模块以生产模式运行日志格式切换为默认生产格式JSON。FROM node:16-bullseye-slim RUN apt-get update \ apt-get install -y --no-install-recommends libsqlite3-dev python3 build-essential \ rm -rf /var/lib/apt/lists/* \ yarn config set python /usr/bin/python3 USER node WORKDIR /app ENV NODE_ENV production COPY --chownnode:node yarn.lock package.json packages/backend/dist/skeleton.tar.gz ./ RUN tar xzf skeleton.tar.gz rm skeleton.tar.gz RUN yarn install --frozen-lockfile --production --network-timeout 300000 rm -rf $(yarn cache dir) COPY --chownnode:node packages/backend/dist/bundle.tar.gz app-config*.yaml ./ RUN tar xzf bundle.tar.gz rm bundle.tar.gz CMD [node, packages/backend, --config, app-config.yaml, --config, app-config.production.yaml]日志格式变化示例从2022-08-10T11:36:05.478Z catalog info Performing database migration typeplugin变为{level:info,message:Performing database migration,plugin:catalog,service:backstage,type:plugin}若希望保留原有格式可在packages/backend/src/index.ts中显式设置彩色格式的 root loggergetRootLogger, setRootLogger, createRootLogger, coloredFormat, useHotMemoize, ... async function main() { setRootLogger(createRootLogger({ format: coloredFormat })); const config await loadBackendConfig({其他值得关注的插件更新TechDocsGCP Cloud Storage 发布器新增projectId配置项可覆盖凭据包中的隐式项目 IDaa524a5377见 plugins/techdocs-nodeS3/GCS 发布器修复未携带bucketRootPath的问题。Tech Insights允许在单个 scorecard 上展示不同类型的检查结果但包含三个BREAKING变更移除getScorecardsDefinition方法改由getCheckResultRenderers返回渲染组件、CheckResultRenderer类型改为暴露component工厂方法、EntityTechInsightsScorecardContent/EntityTechInsightsScorecardCard的title参数变为必填自定义渲染通过TechInsightsClient构造函数的renderers参数注入。Azure DevOps新增EntityAzureReadmeCard6c1c59b96e安装两步走先yarn add --cwd packages/app backstage/plugin-azure-devops再在实体页面中通过EntitySwitch.Case if{isAzureDevOpsAvailable}包裹卡片maxHeight属性可控制最大显示高度默认 100%。Dynatrace表格视觉改进、支持查看近期 Synthetics 结果并增加实例外链e44c0b3811。Stack Overflow后端 collator 支持分页拉取全部问题默认最大页数 100可用maxPage配置79040f73f7。Azure DevOps BackendcreateRouter现在需要额外的reader: UrlReader参数Azure 配置既可以放在azureDevOps下host/token/organization也可以放在integrations.azure下。Kubernetes Backend新增skipMetricsLookup配置项a57d29d572并导出KubernetesClientProvider与 auth-translator 相关模块。集成层GitHub App token 缓存从 10 分钟提升到 50 分钟同时缓存 app installations配置多个 GitHub App 时建议添加allowedInstallationOwners以最大化性能收益f76f22c649。Bitbucket Server 集成修复了 token 优先级问题42918e085c。升级建议与注意事项结合整个变更列表升级到 v1.6.0 时建议重点关注测试兼容性swc 转译对 mock 写法更严格运行yarn backstage-cli repo lint --fix修复 eslint-plugin-jest 新规则并参照上文改写不规范的 jest.mock / jest.spyOn。React Router v6 迁移使用backstage-cli migrate react-router-deps检查依赖注意PermissionedRoute已被RequirePermission取代。身份 API 迁移将IdentityClient/authenticate替换为IdentityApigetIdentity。数据库与容器DatabaseTaskStore/DatabaseDocumentStore改用PluginDatabaseManager创建确认 Dockerfile 的USER node与NODE_ENV production带来的日志格式变化是否符合预期。Helmet 6如依赖block-all-mixed-content或expectCt需要显式配置。被移除的能力publish:fileaction、remove-plugin命令、plugin:diff命令均已移除或废弃请改用官方推荐方案。完整的逐包变更明细可查阅仓库中的 docs/releases/v1.6.0-changelog.md。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考