Backstage v1.47.0 升级指南ActionsService 动作过滤、ui 表格组件重构与 TechDocs AWS S3 凭证优先级变更【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于本仓库 docs/releases/v1.47.0-changelog.md 整理系统解读 Backstage v1.47.0 的核心变更后端 ActionsService 新增动作过滤能力与 urlReader 重定向白名单校验、前端backstage/ui表格组件 API 全面重构、Kafka 事件模块 offset 消费策略可配置化以及 TechDocs AWS S3 凭证解析顺序的破坏性调整。读完本文你将掌握 v1.47.0 中每个破坏性变更的迁移步骤、新配置项的完整用法以及对应源码实现与测试佐证可直接指导升级落地。一、版本总览与破坏性变更速查v1.47.0 主要涉及 4 个 Minor 版本更新与若干补丁其中必须关注的破坏性变更如下包版本变更类型影响范围backstage/backend-defaults0.15.0MinorActionsService 新增过滤配置FetchUrlReader构造器私有化urlReader 重定向链纳入reading.allow白名单backstage/frontend-app-api0.14.0Minor插件只能覆盖同插件内 API覆盖 app 核心 API 必须改用 app modulebackstage/ui0.11.0MinorTable/useTableAPI 重构颜色 token 重命名backstage/plugin-techdocs-node1.14.0MinorTechDocs AWS S3 认证凭证优先级调整backstage/plugin-events-backend-module-kafka0.3.0MinorKafka offset 管理fromBeginning/autoCommitbackstage/plugin-home0.9.0MinorWidget 配置仅在点击 Save 时写入存储新增 Cancel 按钮此外backstage/plugin-app-react以 0.1.0 首次发布承接了从backstage/frontend-plugin-api迁移而来的 8 个 Blueprint。二、ActionsService 动作过滤用配置控制暴露给 MCP 等消费方的动作backstage/backend-defaults0.15.0最重要的新特性是ActionsService支持基于配置的动作过滤用于控制哪些动作会暴露给 MCP 后端等消费者实现动作面的治理。配置示例在app-config.yaml的backend.actions下新增pluginSources与filterbackend: actions: pluginSources: - catalog - scaffolder filter: include: - id: catalog:* attributes: destructive: false - id: scaffolder:* exclude: - id: *:delete-* - attributes: readOnly: false过滤逻辑include包含规则每条规则可指定idglob 模式和/或attributes约束。动作只需匹配任意一条 include 规则即被包含若未配置任何 include 规则默认包含全部动作。exclude排除规则优先级高于 include只要命中任意一条 exclude 规则即被排除。单条规则内的组合语义id与attributes之间是 AND 关系同时指定时必须同时满足。源码实现佐证过滤逻辑实现在 packages/backend-defaults/src/alpha/entrypoints/actions/DefaultActionsService.tslist()会遍历backend.actions.pluginSources中声明的插件源通过 discovery 服务请求各插件的/.backstage/actions/v1/actions端点聚合动作再交给applyFilters()处理源码 DefaultActionsService.ts#L64-L91applyFilters()中 exclude 先判断、后判断 include且 include 为空时默认放行DefaultActionsService.ts#L162-L197parseFilterRules()将id编译为Minimatch实例并只识别destructive、readOnly、idempotent三个布尔属性DefaultActionsService.ts#L199-L232也就是说属性约束目前仅支持这三个语义字段。对应测试覆盖在 actionsServiceFactory.test.ts包含 include 过滤、exclude 过滤、exclude 优先于 include、属性约束、idattributesAND 组合、无过滤配置时返回全部动作等场景可用于验证你的过滤规则预期。三、urlReader 安全增强构造器私有化与重定向链白名单backstage/backend-defaults0.15.0同时带来两项与coreServices.urlReader相关的安全收紧FetchUrlReader 构造器私有化FetchUrlReader的构造函数改为private不再允许直接new FetchUrlReader(...)构造实例。若确需自行构造请改用静态方法FetchUrlReader.fromConfig(config)。源码中构造器已声明为私有并提供static factory与static fromConfig两个工厂入口见 FetchUrlReader.ts#L111-L140。重定向链纳入 reading.allow 白名单coreServices.urlReader现在会校验整条重定向链中的每个跳转目标都必须命中backend.reading.allow白名单。此前如果你依赖了指向未白名单 URL 的重定向升级后必须把这些目标地址也加入配置backend: reading: allow: - host: example.com - host: storage-api.example.com实现上FetchUrlReader.readUrl()使用redirect: manual手动处理重定向在循环中对当前 URL 逐一执行白名单谓词校验命中301/302/307/308且带location头时才继续跳转最多跟随MAX_REDIRECTS 5次FetchUrlReader.ts#L147-L214。白名单的匹配规则支持host完整主机名或*.example.com形式的子域名通配不支持中间通配prod.*.example.compaths可选的路径前缀列表按路径段边界匹配省略则允许全部路径host:port可指定端口或端口范围。其他相关补丁GoogleGcsReader实现了readTree能力对应backstage/integration中GoogleGcs的ScmIntegration支持见 packages/backend-defaults/src/entrypoints/urlReader/lib/AwsS3UrlReader.ts 同目录下的UrlReaders.ts注册逻辑动作逻辑改用resolveSafeChildPath包裹并增强远程/本地文件拉取时的符号链接处理同时涉及backstage/plugin-scaffolder-backend与backstage/plugin-scaffolder-node根健康服务关闭响应的拼写错误被修复zod-to-json-schema升级至最新版。四、backstage/ui 0.11.0Table 组件全新 API 与迁移指南backstage/ui0.11.0对本仓库 UI 体系的核心表格组件做了破坏性重构影响Table、TableRoot、TablePagination三个组件。变更要点原 React Aria 包装的Table组件更名为TableRoot新的高层Table组件统一处理数据展示、分页、排序与行选择useTablehook 完全重设计支持三种分页模式complete一次性全量数据、offset、cursor新增类型ColumnConfig、TableProps、TableItem、UseTableOptions、UseTableResult新特性统一的分页模式、防抖的查询变更、重载期间保留旧数据stale data preservation、行选择支持 toggle/replace 行为、自定义分页选项pageSizeOptions与onPageSizeChange/onNextPage/onPreviousPage回调、列宽配置width/defaultWidth/minWidth/maxWidth、className/style透传等。迁移步骤第 1 步更新导入并使用新useTablehook-import { Table, useTable } from backstage/ui; -const { data, paginationProps } useTable({ data: items, pagination: {...} }); import { Table, useTable, type ColumnConfig } from backstage/ui; const { tableProps } useTable({ mode: complete, getData: () items, });第 2 步定义列并用新 Table API 渲染-Table aria-labelMy table - TableHeader.../TableHeader - TableBody items{data}.../TableBody -/Table -TablePagination {...paginationProps} / const columns: ColumnConfigItem[] [ { id: name, label: Name, isRowHeader: true, cell: item CellText title{item.name} / }, { id: type, label: Type, cell: item CellText title{item.type} / }, ]; Table columnConfig{columns} {...tableProps} /分页模式与分页选项的源码细节useTable的三种分页模式分别由useCompletePagination、useOffsetPagination、useCursorPagination实现useTableProps负责把分页结果与pageSizeOptions、onPageSizeChange、onNextPage、onPreviousPage等选项组装进tableProps当pageSize不匹配任何选项时回退使用第一个选项并记录告警日志见 packages/ui/src/components/Table/hooks/useTable.ts。useTable的测试位于 useTable.test.tsx可供参考。颜色 token 迁移同样为破坏性变更中性色 token 取代旧的 tint token--bui-bg也更名为--bui-bg-surface-0旧 token新 token--bui-bg--bui-bg-surface-0--bui-bg-tint--bui-bg-neutral-on-surface-0--bui-bg-tint-hover--bui-bg-neutral-on-surface-0-hover--bui-bg-tint-pressed--bui-bg-neutral-on-surface-0-pressed--bui-bg-tint-disabled--bui-bg-neutral-on-surface-0-disabled注意旧 tint token 没有直接替代品官方建议使用 surface 0 或 surface 1 上的中性色 token 集合替代。同时新增了--bui-shadowtoken 用于 Popover、Tooltip、Menu 等浮层组件的一致阴影新增Popover组件支持自动溢出处理与完整定位。值得关注的修复Link组件对内部路由改为使用 React Router 导航不再触发整页刷新SearchField修复startCollapsed在 flex row / flex column / 普通容器各布局下的折叠行为Checkbox增加 indeterminate半选状态支持表头全选等部分选中场景Menu触发按钮修复重复点击开合问题移除与 React Aria 内置状态管理冲突的自定义 click-outside handlerSelect、MenuAutocomplete、MenuAutocompleteListbox补齐aria-label新增ToggleButton/ToggleButtonGroup组件。五、Kafka 事件模块offset 消费策略可配置化backstage/plugin-events-backend-module-kafka0.3.0为KafkaConsumingEventPublisher新增两个配置项fromBeginning当消费组没有已提交 offset 时true表示从最早消息开始false默认表示从最新消息开始一旦消费组已提交 offset则始终从该位置恢复不受此配置影响autoCommit默认true与 KafkaJS 默认行为保持一致兼容旧行为。显式设为false时进入手动提交模式每处理一条消息成功后才提交 offset处理失败则暂停消费且不提交。配置示例来源于本仓库 plugins/events-backend-module-kafka/README.mdevents: modules: kafka: kafkaConsumingEventPublisher: production: clientId: your-client-id brokers: - broker1 topics: - topic: backstage.topic kafka: topics: - topic1 groupId: your-group-id fromBeginning: false autoCommit: false pauseOnError: true与autoCommit配合的pauseOnError默认false时出错会跳过失败消息继续处理手动提交模式下失败消息的 offset 也会被提交即被跳过不再重试设为true时出错即暂停消费者且不提交失败消息的 offset便于排查后再继续。配置解析实现在 KafkaConsumingEventPublisher/config.ts其中fromBeginning被映射到 KafkaJS 的ConsumerSubscribeTopics.fromBeginningautoCommit默认值为true、pauseOnError默认值为false。对应测试位于 config.test.ts 与 KafkaConsumingEventPublisher.test.ts。六、TechDocs AWS S3认证凭证优先级破坏性变更backstage/plugin-techdocs-node1.14.0起TechDocs 发布到 AWS S3 时可以使用integrations.awsS3配置中的凭证进行认证新的优先级如下aws.accountstechdocs.publisher.awsS3.credentialsintegrations.awsS3默认凭证链关键细节当存在多个integrations.awsS3条目时如果techdocs.publisher.awsS3.credentials提供了accessKeyId则据此确定目标 integration否则使用默认凭证链。该逻辑在 plugins/techdocs-node/src/stages/publish/awsS3.ts 中实现优先读aws.accounts下的账户配置其次techdocs.publisher.awsS3.credentials的accessKeyId/secretAccessKey源码 awsS3.ts#L366-L371随后按accessKeyId在integrations.awsS3中匹配目标条目awsS3.ts#L394-L405。是否影响现有部署取决于你的配置方式配置了aws.accounts→ 无需任何操作配置了techdocs.publisher.awsS3.credentials→ 无需任何操作配置了多个integrations.awsS3→ 无需任何操作仅配置单个integrations.awsS3→ 需确保该 integration 拥有对你 TechDocs 所用 S3 bucket 的访问权限。同版本补丁defaultDockerImage更新到最新 TechDocs 容器版本 v1.2.8backstage/plugin-techdocs-backend将region、endpoint、accountId等 AWS publisher 配置项的可见性从secret调整为backend。七、前端系统变更API 覆盖限制与 Blueprint 迁移插件只能覆盖本插件内的 APIbackstage/frontend-app-api0.14.0收紧了插件覆盖 API 的能力插件不再允许覆盖app插件提供的核心 API如需覆盖必须通过 app module 完成。backstage/frontend-plugin-api同步更新了createApiRef文档明确 API ID 在标识其所属插件中的作用。backstage/plugin-app-react 首次发布0.1.0以下 8 个 Blueprint 从backstage/frontend-plugin-api迁出原位置已弃用且仅允许在 app 插件覆盖与模块中使用越界使用会产生弃用告警AppRootWrapperBlueprintIconBundleBlueprintNavContentBlueprintRouterBlueprintSignInPageBlueprintSwappableComponentBlueprintThemeBlueprintTranslationBlueprint若你在 app 插件之外的模块中使用了上述 Blueprint请迁移到backstage/plugin-app-react并通过 app 插件或 app module 方式使用。同时backstage/frontend-plugin-api/alpha新增PluginWrapperBlueprint用于安装包装所有插件元素的组件backstage/plugin-app已实现对其的支持。八、CLI 与其余值得关注的变更backstage-cli info 增强backstage/cli0.35.2为backstage-cli info新增--include与--format选项可用 glob 模式额外包含包并支持以 JSON 或 Text 格式输出。同版本还通过内容哈希生成 CSS Module 类名解决多版本包共存时的类名冲突swc/core升级以支持ES2023/ES2024backstage/backend-test-utils加入后端包模板create-app的 Dockerfile 改用 Node 24 与 Debian Trixie。Scaffolder 相关github:repo:create动作新增workflowAccess选项如organization便于在创建仓库时配置 GitHub Actions 对 workflow 的访问级别见 plugins/scaffolder-backend-module-github 的 CHANGELOGRepoUrlPickerComponent修复仓库名自动补全问题Sentry 模块backstage/plugin-scaffolder-backend-module-sentry0.3.0新增 API Base URL 配置能力。其他补丁亮点backstage/plugin-catalog-backend-module-githubGithubOrgEntityProvider成员事件处理优化——只拉取该用户的团队而非全组织用户并使用addEntitiesOperation替代replaceEntitiesOperation避免不必要的实体删除backstage/plugin-user-settings-backend修复用户设置 key 含斜杠时返回 404 的问题backstage/plugin-catalog-graph与backstage/plugin-search适配qs库更严格的数组长度限制backstage/plugin-orgGroup ownership 卡片在未指定 kinds 时默认包含Resource类型backstage/plugin-notifications新增 i18n 支持backstage/plugin-catalogEntityLayout 头部始终显示修复异步实体刷新导致的闪烁backstage/backend-app-api后端停止时清理进程事件监听器防止泄漏backstage/plugin-auth-backend修复user_created_at迁移在 SQLite 下因非常量默认值引发的SQLiteError。九、升级建议先读破坏性变更重点核对reading.allow白名单是否覆盖所有重定向目标、integrations.awsS3单条目场景下的 S3 权限、前端 Blueprint 导入来源是否在 app 插件作用域内迁移backstage/ui表格按上文两步迁移Table/useTable同步替换--bui-bg-*颜色 token活用动作过滤如果暴露动作给 MCP 等消费方用backend.actions.filter的 include/exclude 规则收窄动作面并以 actionsServiceFactory.test.ts 中的场景校验规则语义验证 Kafka 消费语义开启autoCommit: false前确认业务对失败消息跳过/暂停的预期避免重复消费或消息丢失回归测试关注Link内部路由导航、SearchField折叠行为、表格排序指示器可见性等本次修复点必要时补充组件级测试。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考