企业官网建设流程全解析

Backstage v1.7.0-next.2 变更深度解析：权限规则 ZodSchema 重构、目录位置分析器与 Scaffolder 动作升级指南

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

本文基于仓库内 docs/releases/v1.7.0-next.2-changelog.md 编写，围绕该预发布版本中若干Breaking Changes与新增能力展开：权限规则 API 引入 ZodSchema 参数校验、catalog 后端新增addLocationAnalyzers、catalog-import 的仓库 URL 探测逻辑迁移到后端、bazaar-backend 强制注入 identity，以及 Scaffolder 的github:publish/publish:gitlab:merge-request动作增强。读完本文，你将能对照版本差异完成已有 Backstage 应用（后端插件、权限规则、catalog 导入流程）的平滑升级，并理解这些改动背后的源码设计意图。

一、版本概览：这是一份预发布（next）变更日志

v1.7.0-next.2是 Backstage 主版本线中的一个next 预发布快照，同一批变更会被逐步合入稳定版。该 changelog 按 npm 包粒度组织，每个包分Minor Changes（新增/破坏性变更）与Patch Changes（缺陷修复与依赖升级）两类，并列出其依赖包的同步版本。涉及的核心包包括：

其中权限规则 API 的改动是整个版本影响面最广的破坏性变更——它同时牵动了plugin-permission-common、plugin-permission-node、plugin-catalog-backend与plugin-playlist-backend四个包的 API 形状。

二、重点变更一：权限规则 API 强制 ZodSchema 参数校验（BREAKING）

2.1 变更动机

changelog 明确指出（commit46b4a72cee）：在定义权限规则时，现在必须提供一个描述该规则期望参数的 ZodSchema。引入它的目的有两个：

1. 在 metadata 端点的响应中更好地描述规则参数（供前端以结构化方式渲染条件编辑表单）；
2. 在规则真正执行之前对参数进行校验，避免非法参数进入apply/toQuery逻辑。

2.2 API 形状变化：从分离参数到单一对象

改动前的createPermissionRule中，apply与toQuery的签名把参数作为独立的多个参数传入：

createPermissionRule({ apply: (resource, foo, bar) => true, toQuery: (foo, bar) => {}, });

改动后，参数被收敛为单个对象，并新增必填的paramSchema字段：

createPermissionRule({ paramSchema: z.object({ foo: z.string().describe('Foo value to match'), bar: z.string().describe('Bar value to match'), }), apply: (resource, { foo, bar }) => true, toQuery: ({ foo, bar }) => {}, });

2.3 源码印证：参数类型被限制为原始类型

这一“参数必须是对象 + 值只允许原始类型”的设计，在当前仓库源码中有直接体现。plugins/permission-common/src/types/api.ts 中定义了：

export type PermissionRuleParam = undefined | JsonPrimitive | JsonPrimitive[]; export type PermissionRuleParams = | undefined | Record<string, PermissionRuleParam>;

JsonPrimitive即 string / number / boolean / null 这类基础 JSON 值。因此 changelog 中“将参数的可能值限制为原始类型以及原始类型的数组”的约束，正是由上述类型定义强制保证的——对象、嵌套结构等复杂类型无法通过编译期类型检查。

在权限节点侧，plugins/permission-node/src/integration/createPermissionRule.ts 中可以看到实现通过import { z } from 'zod/v3'引用 Zod，并调用assertPermissionRuleParamsSchema（同目录permissionRuleParams.ts）来校验参数 schema 的合法性。从源码结构可以推断：规则注册时会持久化paramSchema，并在条件决策执行前对入参做运行时校验，从而保证 metadata 端点输出的参数描述与真实执行的参数一致。

2.4 联动影响：catalog 与 playlist 的权限条件 API

由于PermissionRule类型发生破坏性变更，所有基于它导出的权限规则都必须同步调整：

• @backstage/plugin-catalog-backend（commiteb25f7e12d）：导出的权限规则与createCatalogConditionalDecision的 API 随PermissionRule类型变更而改变，涉及的类型全部从@backstage/plugin-catalog-backend/alpha导出。实现位于 plugins/catalog-backend/src/permissions/conditionExports.ts。
• @backstage/plugin-playlist-backend（commiteb25f7e12d）：以playlistConditions.isOwner为例，调用方式从分离参数变为对象传参：

// 旧写法 playlistConditions.isOwner(['user:default/me', 'group:default/owner']); // 新写法 playlistConditions.isOwner({ owners: ['user:default/me', 'group:default/owner'], });

2.5 升级动作清单

如果你在自己的 Backstage 应用或插件中定义了自定义权限规则，请按以下步骤迁移：

1. 为每条规则补充paramSchema，使用z.object({ ... })描述字段，建议用.describe()提供可读说明（会出现在 metadata 响应中）；
2. 将apply/toQuery的参数由分散形参改为从单一对象中解构；
3. 检查参数取值是否仅包含原始类型或原始类型数组，复杂对象需拆分为多个参数；
4. 若使用 catalog 的条件决策 API，改为从@backstage/plugin-catalog-backend/alpha导入相关类型。

三、重点变更二：Catalog 后端新增 Location Analyzer（位置分析器）

3.1 新增addLocationAnalyzers方法

commitb2e6cb6acf为CatalogBuilder增加了新方法addLocationAnalyzers。通过它可以向 catalog 注册若干location analyzer，这些分析器会被/analyze-location端点用来判断：用户提供的仓库 URL 中是否已经包含 catalog-info.yaml 文件，从而决定在 catalog-import 页面中是引导用户注册已有实体，还是帮用户生成新的 catalog-info.yaml。

该方法在仓库中的实现位于 plugins/catalog-backend/src/service/CatalogBuilder.ts，签名支持传入一个或多个ScmLocationAnalyzer（或其数组），并返回CatalogBuilder以支持链式调用：

addLocationAnalyzers( ...analyzers: Array<ScmLocationAnalyzer | Array<ScmLocationAnalyzer>> ): CatalogBuilder

同时在 plugins/catalog-backend/src/service/CatalogPlugin.ts 中可以看到，默认的 SCM 分析器通过builder.addLocationAnalyzers(...scmLocationAnalyzers)注入，说明分析器机制已成为 catalog 后端初始化流程的一等公民。

3.2 catalog-import 的仓库探测逻辑迁移到后端（BREAKING）

与上一项配套的是@backstage/plugin-catalog-import@0.9.0-next.2的破坏性变更：对 catalog-info.yaml 的代码搜索从前端迁移到了后端。这意味着搜索过程将使用已配置的 GitHub 集成凭据（而非用户浏览器会话的凭据），避免仓库中已有 catalog-info.yaml 却因前端无权限而探测失败的问题。

要恢复“通过仓库 URL 导入（repo URL ingestion）”功能，你需要在 catalog.ts 中注册 GitHub 分析器：

// catalog.ts import { GitHubLocationAnalyzer } from '@backstage/plugin-catalog-backend-module-github'; ... builder.addLocationAnalyzers( new GitHubLocationAnalyzer({ discovery: env.discovery, config: env.config, }), ); ...

配套地，@backstage/plugin-catalog-backend-module-github@0.1.8-next.2新增了GitHubLocationAnalyzer（commit7022aebf35），并补充了GitHubEntityProvider缺失的 config schema（commit7edb5909e8）。结合 changelog 中RepoLocationAnalyzer的表述可以推断：addLocationAnalyzers注册的分析器会被RepoLocationAnalyzer汇总使用，共同决定某 URL 是否已包含 catalog-info.yaml。

3.3 配套的类型迁移

与位置分析相关的 5 个类型从@backstage/plugin-catalog-backend迁移到了@backstage/plugin-catalog-common（plugin-catalog-common@1.0.7-next.2，commit823acaa88b）：

• AnalyzeLocationResponse
• AnalyzeLocationRequest
• AnalyzeLocationExistingEntity
• AnalyzeLocationGenerateEntity
• AnalyzeLocationEntityField

升级时需要同步更新这些类型的 import 来源。另外，@backstage/plugin-catalog-node@1.2.0-next.2将LocationSpec类型标记为Deprecated，并从该包迁移到了@backstage/plugin-catalog-common（commit404366c853），import 路径同样需要更新。

四、重点变更三：bazaar-backend 强制注入 identity（BREAKING）

@backstage/plugin-bazaar-backend@0.2.0-next.2中，createRouter现在要求必须传入identityApi（commit8554533546）。改动目的：members 表新增了用户实体 ref 列，该值通过identityApi从请求用户身份中提取。

对packages/backend/src/plugins/bazaar.ts的适配示例如下：

import { PluginEnvironment } from '../types'; import { createRouter } from '@backstage/plugin-bazaar-backend'; import { Router } from 'express'; export default async function createPlugin( env: PluginEnvironment, ): Promise<Router> { return await createRouter({ logger: env.logger, config: env.config, database: env.database, + identity: env.identity, }); }

同步地，前端@backstage/plugin-bazaar@0.1.25-next.2也做了配套增强：新增Overview Card（展示最新或随机项目）、ProjectPreview.tsx增加gridSize与useTablePagination属性（commitf7c2855d76），并把成员链接到对应的用户 catalog 实体（commitc0352bbc69）。后端 router 也新增了getLatestProjects端点，可按传入的 limit 返回最新项目列表。

五、重点变更四：Scaffolder 动作增强与修复

5.1github:publish支持 PR 同步要求

@backstage/plugin-scaffolder-backend@1.7.0-next.2（commit17ff77154c）为github:publish动作新增选项：控制合并前 PR 是否需要与默认分支保持最新（up to date）。在配置模板时，你可以把该开关接入参数表单，例如在 software template 的 properties 中暴露一个布尔字段，并在 action 参数中传递给github:publish，用于强制要求 PR 必须基于最新默认分支才能合并。

5.2publish:gitlab:merge-request新增sourcePath

commita8e9848479为 GitLab 合并请求发布动作新增可选的sourcePath参数；同时targetPath变为可选，未指定时回退到当前 workspace 路径。这让同一个模板可以更灵活地控制 MR 的源目录与目标目录。

5.3 其他修复

• commit4880d43e25：修复 Bitbucket Server 默认分支设置问题；
• @backstage/plugin-scaffolder@1.7.0-next.2：RepoUrlPicker的allowed*值在渲染时被重置的 bug 修复（commit98ae18b68f）；/next路由的 Scaffolder 与旧版TaskPage视图打通（commit92e490d6b4）；NextRouter升级到react-jsonschema-form@v5-beta（alpha 导出，commit1047baa926）。

六、其他值得关注的变更

6.1 techdocs-backend 新增可选catalogClient

@backstage/plugin-techdocs-backend@1.4.0-next.2为createRoute参数新增可选的catalogClient参数（commit7ced1b4076），用于在 TechDocs 构建/读取流程中访问 catalog 数据，属于向后兼容的增量能力。

6.2 backend-tasks 新增配置读取函数

@backstage/backend-tasks@0.3.6-next.2新增readTaskScheduleDefinitionFromConfig（commitd4fea86ea3），用于从Config中读取TaskScheduleDefinition（即任务调度计划）。这意味着像 Bitbucket Cloud 发现类 provider 的调度配置可以迁移到app-config.yaml中声明，而不是硬编码在代码里——本版本中@backstage/plugin-catalog-backend-module-bitbucket-cloud@0.1.4-next.2正是这样做的（commitf66e696e7b，可通过配置文件配置 schedule）。

6.3 Bitbucket 模块拆分与弃用

@backstage/plugin-catalog-backend-module-bitbucket@0.2.4-next.2被弃用（commit23f9199a0f），官方建议迁移到：

• @backstage/plugin-catalog-backend-module-bitbucket-cloud（该模块还新增了基于新 backend-plugin-api 的bitbucketCloudCatalogModule，commita9b91d39bb）；
• @backstage/plugin-catalog-backend-module-bitbucket-server。

同时@backstage/backend-common@0.15.2-next.2修复了 Bitbucket Server 集成问题（commitc44cf412de）。

6.4 安全性与代码规范类改动

多个后端包统一执行了“用response.json替代response.send”（commit2d3a5f09ab，依据SECURITY.md），涉及plugin-catalog-backend、backend-common、cli、plugin-airbrake-backend、plugin-badges-backend、plugin-graphql-backend、plugin-periskop-backend、plugin-permission-backend、plugin-rollbar-backend、plugin-search-backend、plugin-tech-insights-backend、plugin-user-settings-backend等；plugin-user-settings-backend还改用Response.status而非.send(number)（commitf3463b176b）。这类改动属于响应序列化的一致性收口，升级时无需业务改动。

6.5 构建与脚手架

@backstage/create-app@0.4.32-next.2在 Dockerfile 的yarn install与apt-get阶段启用cache mounts，加速重复构建（commit01dff06be4）；@backstage/plugin-github-issues@0.1.2-next.2为 GraphQL 查询增加了过滤与排序能力（commitdf226e124c）。

七、升级检查清单

综合以上变更，从v1.7.0-next.1或更早版本升级到本快照时，建议按此顺序逐项排查：

1. 权限系统：更新所有createPermissionRule调用，补充paramSchema（ZodSchema）；将apply/toQuery参数改为单一对象；确认参数值为原始类型或其数组；catalog/playlist 的权限条件调用改为对象传参。
2. 类型导入：将AnalyzeLocation*5 个类型与LocationSpec的 import 源更新为@backstage/plugin-catalog-common。
3. catalog 后端：如需保留“按仓库 URL 导入”能力，在CatalogBuilder上调用addLocationAnalyzers注册GitHubLocationAnalyzer（传入discovery与config）。
4. bazaar 插件：向createRouter注入identity: env.identity。
5. Scaffolder 模板：按需使用github:publish的 PR 同步开关与publish:gitlab:merge-request的sourcePath；检查targetPath省略时的默认行为。
6. Bitbucket 模块：将catalog-backend-module-bitbucket迁移到 cloud/server 拆分模块，并将 provider 调度配置尽量下沉到app-config.yaml。
7. 依赖锁定：参照 changelog 中各包的Updated dependencies列表（如@backstage/backend-common@0.15.2-next.2、@backstage/plugin-catalog-node@1.2.0-next.2等）同步升级，避免子依赖版本不一致导致运行时行为漂移。

需要说明的是：本文所有 API 签名与类型定义均以当前仓库源码（plugins/permission-common/src/types/api.ts、plugins/permission-node/src/integration/createPermissionRule.ts、plugins/catalog-backend/src/service/CatalogBuilder.ts）与 docs/releases/v1.7.0-next.2-changelog.md 为准；v1.7.0-next.2为预发布快照，正式升级前请留意后续稳定版 changelog 是否对 API 有进一步调整。

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