企业官网建设流程全解析

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/plugin-app-react以 0.1.0 首次发布，承接了从@backstage/frontend-plugin-api迁移而来的 8 个 Blueprint。

二、ActionsService 动作过滤：用配置控制暴露给 MCP 等消费方的动作

@backstage/backend-defaults@0.15.0最重要的新特性是ActionsService支持基于配置的动作过滤，用于控制哪些动作会暴露给 MCP 后端等消费者，实现"动作面"的治理。

配置示例

在app-config.yaml的backend.actions下新增pluginSources与filter：

backend: 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.ts：

• list()会遍历backend.actions.pluginSources中声明的插件源，通过 discovery 服务请求各插件的/.backstage/actions/v1/actions端点聚合动作，再交给applyFilters()处理（源码 DefaultActionsService.ts#L64-L91）；
• applyFilters()中 exclude 先判断、后判断 include，且 include 为空时默认放行（DefaultActionsService.ts#L162-L197）；
• parseFilterRules()将id编译为Minimatch实例，并只识别destructive、readOnly、idempotent三个布尔属性（DefaultActionsService.ts#L199-L232），也就是说属性约束目前仅支持这三个语义字段。

对应测试覆盖在 actionsServiceFactory.test.ts，包含 include 过滤、exclude 过滤、exclude 优先于 include、属性约束、id+attributesAND 组合、无过滤配置时返回全部动作等场景，可用于验证你的过滤规则预期。

三、urlReader 安全增强：构造器私有化与重定向链白名单

@backstage/backend-defaults@0.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.com）；
• paths：可选的路径前缀列表，按路径段边界匹配，省略则允许全部路径；
• 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.0：Table 组件全新 API 与迁移指南

@backstage/ui@0.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-label="My table"> - <TableHeader>...</TableHeader> - <TableBody items={data}>...</TableBody> -</Table> -<TablePagination {...paginationProps} /> +const columns: ColumnConfig<Item>[] = [ + { 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：

注意：旧 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 handler）；
• Select、MenuAutocomplete、MenuAutocompleteListbox补齐aria-label；
• 新增ToggleButton/ToggleButtonGroup组件。

五、Kafka 事件模块：offset 消费策略可配置化

@backstage/plugin-events-backend-module-kafka@0.3.0为KafkaConsumingEventPublisher新增两个配置项：

• fromBeginning：当消费组没有已提交 offset 时，true表示从最早消息开始，false（默认）表示从最新消息开始；一旦消费组已提交 offset，则始终从该位置恢复，不受此配置影响；
• autoCommit：默认true（与 KafkaJS 默认行为保持一致，兼容旧行为）。显式设为false时进入手动提交模式：每处理一条消息成功后才提交 offset，处理失败则暂停消费且不提交。

配置示例（来源于本仓库 plugins/events-backend-module-kafka/README.md）：

events: 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.fromBeginning，autoCommit默认值为true、pauseOnError默认值为false。对应测试位于 config.test.ts 与 KafkaConsumingEventPublisher.test.ts。

六、TechDocs AWS S3：认证凭证优先级（破坏性变更）

@backstage/plugin-techdocs-node@1.14.0起，TechDocs 发布到 AWS S3 时可以使用integrations.awsS3配置中的凭证进行认证，新的优先级如下：

1. aws.accounts
2. techdocs.publisher.awsS3.credentials
3. integrations.awsS3
4. 默认凭证链

关键细节：当存在多个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.8；@backstage/plugin-techdocs-backend将region、endpoint、accountId等 AWS publisher 配置项的可见性从secret调整为backend。

七、前端系统变更：API 覆盖限制与 Blueprint 迁移

插件只能覆盖本插件内的 API

@backstage/frontend-app-api@0.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 插件覆盖与模块中使用，越界使用会产生弃用告警）：

• AppRootWrapperBlueprint
• IconBundleBlueprint
• NavContentBlueprint
• RouterBlueprint
• SignInPageBlueprint
• SwappableComponentBlueprint
• ThemeBlueprint
• TranslationBlueprint

若你在 app 插件之外的模块中使用了上述 Blueprint，请迁移到@backstage/plugin-app-react，并通过 app 插件或 app module 方式使用。同时@backstage/frontend-plugin-api/alpha新增PluginWrapperBlueprint，用于安装包装所有插件元素的组件，@backstage/plugin-app已实现对其的支持。

八、CLI 与其余值得关注的变更

backstage-cli info 增强

@backstage/cli@0.35.2为backstage-cli info新增--include与--format选项：可用 glob 模式额外包含包，并支持以 JSON 或 Text 格式输出。同版本还通过内容哈希生成 CSS Module 类名，解决多版本包共存时的类名冲突；@swc/core升级以支持ES2023/ES2024；@backstage/backend-test-utils加入后端包模板；create-app的 Dockerfile 改用 Node 24 与 Debian Trixie。

Scaffolder 相关

• github:repo:create动作新增workflowAccess选项（如organization），便于在创建仓库时配置 GitHub Actions 对 workflow 的访问级别，见 plugins/scaffolder-backend-module-github 的 CHANGELOG；
• RepoUrlPickerComponent修复仓库名自动补全问题；
• Sentry 模块（@backstage/plugin-scaffolder-backend-module-sentry@0.3.0）新增 API Base URL 配置能力。

其他补丁亮点

• @backstage/plugin-catalog-backend-module-github：GithubOrgEntityProvider成员事件处理优化——只拉取该用户的团队而非全组织用户，并使用addEntitiesOperation替代replaceEntitiesOperation避免不必要的实体删除；
• @backstage/plugin-user-settings-backend：修复用户设置 key 含斜杠时返回 404 的问题；
• @backstage/plugin-catalog-graph与@backstage/plugin-search：适配qs库更严格的数组长度限制；
• @backstage/plugin-org：Group ownership 卡片在未指定 kinds 时默认包含Resource类型；
• @backstage/plugin-notifications：新增 i18n 支持；
• @backstage/plugin-catalog：EntityLayout 头部始终显示，修复异步实体刷新导致的闪烁；
• @backstage/backend-app-api：后端停止时清理进程事件监听器，防止泄漏；
• @backstage/plugin-auth-backend：修复user_created_at迁移在 SQLite 下因非常量默认值引发的SQLiteError。

九、升级建议

1. 先读破坏性变更：重点核对reading.allow白名单是否覆盖所有重定向目标、integrations.awsS3单条目场景下的 S3 权限、前端 Blueprint 导入来源是否在 app 插件作用域内；
2. 迁移@backstage/ui表格：按上文两步迁移Table/useTable，同步替换--bui-bg-*颜色 token；
3. 活用动作过滤：如果暴露动作给 MCP 等消费方，用backend.actions.filter的 include/exclude 规则收窄动作面，并以 actionsServiceFactory.test.ts 中的场景校验规则语义；
4. 验证 Kafka 消费语义：开启autoCommit: false前，确认业务对失败消息跳过/暂停的预期，避免重复消费或消息丢失；
5. 回归测试：关注Link内部路由导航、SearchField折叠行为、表格排序指示器可见性等本次修复点，必要时补充组件级测试。

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage