企业官网建设流程全解析

Backstage v1.18.0 版本全解析：新后端系统默认导出迁移、可声明式 Sign-in Resolver 与前端系统初亮相

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

v1.18.0 是 Backstage 演进过程中承前启后的一个版本：它既完成了"新后端系统"（New Backend System）插件默认导出的全面迁移，又在认证模块中引入了可配置的 Sign-in Resolver 体系，同时以frontend-app-api/frontend-plugin-api两个0.1.0包首次亮出了实验性的新前端系统。本文以 docs/releases/v1.18.0-changelog.md 为主线，结合仓库源码深入拆解这些变更的配置写法、迁移步骤与底层实现，帮助你判断升级路径并快速落地到自己的开发门户中。

总览：v1.18.0 的关键变更地图

v1.18.0 涉及数十个包的版本更新，核心主题可以归纳为四条主线：

1. 新后端系统全面推进：大量后端插件的导出从命名导出改为default导出，配合backend.add(import('...'))的新式加载方式；同时backend-app-api增强了特性发现（feature discovery）能力，并在启动时检测循环服务依赖。
2. 认证体系重构：@backstage/plugin-auth-node@0.3.0引入 authenticator 模式（createOAuthAuthenticator/createProxyAuthenticator），并支持通过auth.providers.<id>.signIn.resolvers配置声明式 Sign-in Resolver。
3. 实验性新前端系统初亮相：frontend-app-api与frontend-plugin-api首次发布0.1.0，配合实验性 i18n 国际化支持。
4. 平台能力增强：配置深度可见性（deep visibility）扩展、catalog.processingInterval可配置化、Azure DevOps 多组织凭据、backstage.io/techdocs-entity注解、MySQL 数据库支持铺开等。

一、配置层：readDurationFromConfig与深度可见性扩展

1.1 新增readDurationFromConfig工具函数

@backstage/config@1.1.0新增了readDurationFromConfig函数（变更号62f448edb0b5），用于从配置对象中读取"时长"（duration）类型的值。其实现位于 packages/config/src/readDurationFromConfig.ts。

该函数支持三种输入格式：

• ms风格字符串：如'1d'、'2 seconds'，由ms库解析；
• ISO 8601 时长字符串：如'P2DT6H'、'PT1M'（以P开头时自动走 ISO 解析分支）；
• 对象形式：以复数单位为键，如{ days: 2, hours: 6 }，允许的单位包括years、months、weeks、days、hours、minutes、seconds、milliseconds（见源码第 22-31 行的propsOfHumanDuration常量）。

函数签名支持可选的key参数，用于从配置对象的子键读取：

import { readDurationFromConfig } from '@backstage/config'; // 从 config 的 'catalog.processingInterval' 键读取 const interval = readDurationFromConfig(config, { key: 'catalog.processingInterval' });

从源码实现看，该函数不内置可选性：若目标键不存在，需要在调用前先用config.has(...)判断（源码注释中明确说明）。当解析失败时，会抛出带明确路径与错误原因的InputError，例如Invalid duration 'xxx' in config at 'catalog.processingInterval'。

该工具在 v1.18.0 中被backend-tasks（用于调度任务间隔）与catalog-backend（处理间隔）采纳，替代了原先分散在各处的时长解析逻辑。

1.2 Deep Visibility 扩展到未覆盖 schema 的值

@backstage/config-loader@1.5.0的一个重要行为变更（9606ba0939e6）：深度可见性（deep visibility）现在也作用于没有被配置 schema 覆盖的值。

此前，只有在配置 schema 中显式声明了/** @deepVisibility frontend */的键，其可见性才会沿配置树向下传递，且只覆盖 schema 中已声明的路径。现在，只要某个父节点声明了 deep visibility，其下的所有值（无论是否在 schema 中定义）都会继承该可见性。例如：

// plugins/a/config.schema.ts export interface Config { /** @deepVisibility frontend */ a?: unknown; } // plugins/a/config.schema.ts export interface Config { a?: { b?: string; }; }

变更后，a下的所有值对前端可见；而此前只有a和a/b两个精确路径可见。这意味着插件作者可以放心地把@deepVisibility frontend标注在配置树的根节点上，而无需为每一个子字段逐一声明。

从源码看，该继承逻辑位于 packages/config-loader/src/schema/compile.ts：第 167-170 行"如果自身没有定义 deepVisibility，则继承父级的 deepVisibility"；同时第 87-91 行注释指出设计上禁止将deepVisibility设为backend，以防止权限逃逸——可见性的合法传递方向是secret -> backend -> frontend。同文件collect.ts第 356 行也把deepVisibility列为合法 schema 标签之一。

另外，config-loader@1.5.0还修复了配置无操作更新时仍通知订阅者的问题（f9657b891b00），减少前端无谓的重渲染。

二、认证体系：Authenticator 模式与声明式 Sign-in Resolver

v1.18.0 在认证方面投入最大，@backstage/plugin-auth-node@0.3.0与@backstage/plugin-auth-backend@0.19.0构成了新的认证插件开发范式。

2.1 Authenticator 模式：将"认证集成"与"登录逻辑"解耦

变更8513cd7d00e3引入了一套新的认证提供方（auth provider）构建体系，核心思想是创建 authenticator（认证器），再基于它组合出 provider。初始提供两种类型：

• createOAuthAuthenticator+createOAuthRouteHandlers+createOAuthProviderFactory（OAuth 流程）；
• createProxyAuthenticator+createProxyAuthRouteHandlers+createProxyAuthProviderFactory（代理认证流程）。

这套模式的关键收益是：登录逻辑（sign-in logic）与认证集成逻辑分离，同一类型的 provider 可以完全复用同一套登录解析逻辑，同时天然适配新后端系统。此外，原先@backstage/plugin-auth-backend内部基于 passport 策略实现 provider 的辅助函数，也以公开 APIPassportHelpers与PassportOAuthAuthenticatorHelper的形式开放。

2.2 声明式 Sign-in Resolver：从"写代码"到"写配置"

新引入的 provider factory 支持通过配置键resolvers声明式地配置 Sign-in Resolver，按顺序取第一个成功解析出身份的 resolver：

auth: providers: google: development: clientId: ${AUTH_GOOGLE_CLIENT_ID} clientSecret: ${AUTH_GOOGLE_CLIENT_SECRET} signIn: resolvers: - resolver: emailMatchingUserEntityAnnotation - resolver: emailLocalPartMatchingUserEntityName

这些可配置 resolver 由createSignInResolverFactory工厂函数创建，其实现位于 plugins/auth-node/src/sign-in/createSignInResolverFactory.ts。从源码看，该工厂接受一个可选的optionsSchema（基于 zod 定义），这个 schema同时用于配置驱动与代码驱动的参数校验：

• 若未提供optionsSchema，工厂不接受任何选项，传入选项会抛出InputError；
• 若提供，则调用时先经optionsSchema.parse(...)校验，失败时抛出带详细校验错误的InputError。

这意味着插件作者定义的每个 resolver 既可以像上面那样在 YAML 中按名字引用，也可以带上自己的参数（例如- resolver: myResolver\n options: {...}），前后端配置体验一致。

2.3 新增的 Provider 模块与内置 Provider 管理

v1.18.0 将认证 provider 拆分为独立模块（均为0.1.0新包）：

@backstage/plugin-auth-backend@0.19.0相应地新增了authPlugin导出（面向新后端系统），该插件不再内置任何 auth provider，必须通过安装上述模块来添加，例如从@backstage/plugin-auth-backend-module-google-provider引入authModuleGoogleProvider。同时新增createRouter的disableDefaultProviderFactories选项，可禁用内置的 provider 工厂；GitLab provider 也已迁移到独立模块实现。

另一个值得注意的配置项是auth.identityTokenAlgorithm：生成 Backstage token 时使用的签名算法现在可以通过该配置自定义。

2.4 OAuth 会话过期处理与身份响应字段

@backstage/core-app-api@1.10.0修复了两个与 OAuth 会话建模相关的 bug（18619f793c94）：

• OAuth2Session类型中expiresAt与backstageIdentity现在是可选字段（因为实际场景中它们确实可能缺失）；
• 所有 OAuth provider 共用的OAuth类现在会同时考量 Backstage 身份与上游身份提供方两者的会话过期时间，任一即将过期即触发刷新。

配套地，BackstageIdentityResponse新增可选的expiresAt字段（core-plugin-api@1.6.0），auth-node的BackstageIdentityResponse则新增可选expiresInSeconds字段；prepareBackstageIdentityResponse工具函数会从 token 中读取过期时间并写入响应。这套字段的补齐，正是前文"双会话刷新"策略的底层支撑。

三、新后端系统：默认导出迁移与加载方式升级

3.1 统一的默认导出迁移（Breaking Change）

v1.18.0 中，以下后端插件/模块的新后端系统导出统一迁移为default导出（变更71114ac50e02，涉及 adr、airbrake、auth-backend、azure-devops、badges、bazaar、catalog-backend、devtools、entity-feedback、events-backend、kafka、kubernetes、lighthouse、linguist、periskop、permission-backend、proxy、scaffolder-backend、search-backend、todo、user-settings 等）：

// 迁移前（命名导出） import { examplePlugin } from '@backstage/plugin-example-backend'; backend.add(examplePlugin); // 迁移后（默认导出 + 动态 import） backend.add(import('@backstage/plugin-example-backend'));

配合@backstage/backend-app-api@0.5.3的新能力（3b30b179cb38），backend.add(import('my-plugin'))的包导入安装方式正式可用。这也意味着升级到 v1.18.0 时，所有使用新后端系统加载插件的地方都应改为默认导出形式。

3.2 Feature Discovery 与依赖检查强化

backend-app-api@0.5.3在一系列 patch 中完善了新后端系统的运行时行为：

• 特性发现增强（154632d8753b/37a20c7f14aa）：启动时可发现额外的 service factory，且支持对后端包特性发现做 include / exclude 配置，alpha 模块也纳入发现范围；
• 默认导出限定（cb7fc410ed99）：实验性的特性发现只考虑包的 default 导出，package.json中仍需"backstage"字段；
• 扩展点按 ID 跟踪（3fc64b9e2f8f）：扩展点（extension points）改为通过 ID 而非引用跟踪，以支持包重复的场景；
• 循环依赖检测（b219d097b3f4）：后端启动时若检测到循环服务依赖会直接失败，避免运行期出现难以排查的初始化死循环。

backend-plugin-api@0.6.3还从类型层面保证了 root 作用域服务不能依赖插件作用域服务（ba4506076e2d），并把 service factory 标记为可安装的 feature factory（474b792d6a43）。

3.3 后端测试工具同步升级

backend-test-utils@0.2.3引入了：

• ServiceFactoryTester（58cb5e5cea7b）：专门用于测试 service factory 的新工具；
• 模块导入安装支持（202e52c5e361）：startTestBackend({ features: [import('my-plugin')] })；
• mockService扩展（9fb3b5373c45）：为生命周期等服务提供 mock 变体（如mockServices.lifecycle.mock()），返回的 mock 实现自带factory属性，可传入部分实现覆盖特定方法。

四、前端：新前端系统与实验性 i18n

4.1frontend-app-api与frontend-plugin-api首次发布

@backstage/frontend-app-api@0.1.0与@backstage/frontend-plugin-api@0.1.0均为首次发布（628ca7e458e4）。其中frontend-plugin-api依赖core-plugin-api@1.6.0，frontend-app-api则依赖 GraphiQL 插件、core-components@0.13.5等。仓库中的example-app-next与app-next-example-plugin两个示例应用已接入这两个包，可视为新前端系统的实验样板。

graphiql插件也同步提供了/alpha下的实验性导出（cf950c3b6eab），并支持使用 FetchApi（b2fbeed5403b）。

4.2 实验性国际化（i18n）支持

core-app-api、core-plugin-api、plugin-user-settings、plugin-adr等多个包引入了实验性国际化支持（6e30769cc627）。同时test-utils@1.4.3新增/alpha导出MockTranslationApi，用于在测试中模拟翻译 API（b5fbddc15dca），并支持 React Testing Library 13+ / React 18（通过render*方法暴露legacyRoot选项，见9ceb6195275a）。如果你计划在自己的插件中接入多语言，v1.18.0 提供了最早的基础设施雏形。

五、Catalog：处理间隔可配置与 GitLab 组限定

5.1catalog.processingInterval配置项

@backstage/plugin-catalog-backend@1.13.0允许在 app-config 中配置实体处理间隔（62f448edb0b5），实现位于 plugins/catalog-backend/src/service/CatalogBuilder.ts：

catalog: processingInterval: { minutes: 3 } # 也支持 '3m' 或 'PT3M' 等 readDurationFromConfig 支持的格式

从源码第 776-794 行可以看到实际解析逻辑：读取键catalog.processingInterval，若未配置则使用默认值；若显式配置为false则禁用处理；否则调用readDurationFromConfig解析为时长对象（这正是第一节新工具函数的第一个落地场景）。

5.2 其它 Catalog 相关变更

• backstage.io/techdocs-entity注解（e44f45ac4515，同时作用于plugin-catalog与plugin-techdocs）：允许一个实体引用另一个实体的 TechDocs，例如backstage.io/techdocs-entity: system:default/example。典型场景是同一仓库中的前端与后端共享一份文档：把 TechDocs 构建在System实体下，再让成员实体通过注解引用，从而避免重复构建、避免 TechDocs 页面堆满重复内容。该注解同时影响 TechDocs 按钮与 TechDocs 选项卡。
• GitLab.com 组限定（3d73bafd85c9，Breaking）：GitlabOrgDiscoveryEntityProvider现在要求必须配置group参数，否则后端启动失败：

catalog: providers: gitlab: yourProviderId: host: gitlab.com orgEnabled: true + group: org/teams

• Scaffolder 实体模型独立成模块（d5313ede3529）：ScaffolderEntitiesProcessor被标记弃用，应改从新的@backstage/plugin-catalog-backend-module-scaffolder-entity-model导入；alpha 导出catalogModuleTemplateKind也迁移至该包并更名为catalogModuleScaffolderEntityModel。
• 处理循环改为迭代实现（1fd2109739c1）：catalog 处理循环的任务流水线从递归改为迭代，降低深层实体图的栈溢出风险；另外修复了实体查询limit参数、order参数识别、fullTextFilterFields校验等 OpenAPI/查询问题。

六、集成层：Azure DevOps 多组织凭据与 Kubernetes 认证策略

6.1 Azure DevOps：credentials取代单凭据配置

@backstage/integration@1.7.0新增AzureDevOpsCredentialsProvider（5f1a92b9f19f），支持为不同的 Azure DevOps（Server）组织配置各自的凭据，同时弃用AzureIntegrationConfig.credential与AzureIntegrationConfig.token，改为credentials：

integrations: azure: - host: dev.azure.com credentials: - organizations: - my-org - my-other-org clientId: ${AZURE_CLIENT_ID} clientSecret: ${AZURE_CLIENT_SECRET} tenantId: ${AZURE_TENANT_ID} - organizations: - yet-another-org personalAccessToken: ${PERSONAL_ACCESS_TOKEN}

plugin-scaffolder-backend、backend-common、catalog-backend-module-azure均切换到DefaultAzureDevOpsCredentialsProvider获取凭据。另外catalog-backend-module-azure在提交新 location 到 catalog 前会先去重 Azure 搜索结果（044b4f2fb1e3），并提升AzureDevOpsEntityProvider结果一致性（94f96508491d）。

6.2 Kubernetes：AuthenticationStrategy取代AuthTranslator

@backstage/plugin-kubernetes-backend@0.12.0（0ad36158d980）让集成者可以通过KubernetesBuilder的addAuthStrategy方法带入自定义认证策略。Breaking：setAuthTranslatorMap方法与整个KubernetesAuthTranslator接口被移除，替换为更聚焦的AuthenticationStrategy概念。前端plugin-kubernetes与plugin-kubernetes-common同步放宽了retrieveObjectsByServiceId请求体auth字段的类型（允许任意 JSON 对象），便于集成者编写自定义认证策略。此外还修复了caFile配置下代理端点请求失败的问题（024b2b66a332）、为集群资源补充 AWS 注解（ccf00accb408）以及修复自定义资源 kind 显示为undefined的问题（47ea122590f5）。

七、Scaffolder、Search 与 TechDocs 的实用增强

7.1 Scaffolder

• Dry Run 结果页支持 .zip 下载（0119c326394a）：模板预演（dry run）结果现在可以打包下载，方便在本地检查生成内容。
• parseEntityRef过滤器增强（b5f239b50bcf）：现在接受两个参数，可提供默认的 kind 与 namespace 值，与catalog-model中parseEntityRef的行为对齐。
• Action 示例补齐（a4989552d828/ded27b83ead2/f3c0b95e3ef1）：为publish:github、publish:gitlab、publish:bitbucket、github:actions:dispatch等 action 增加了示例定义，便于模板作者参照。
• run:yeoman支持 dry-run（4fa1c74cbadc，scaffolder-backend-module-yeoman）。
• RJSF 升级（b16c341ced45）：scaffolder 前端及 home 插件将@rjsf/*依赖统一升级到 5.13.0。

7.2 Search：默认查询参数可配置

plugin-search与plugin-search-react@1.7.0支持通过 app-config 为 SearchPage 配置首次加载/重置时的默认查询参数（b78f570f44d3）：

search: query: pageLimit: 50

pageLimit的合法取值为10、25、50、100。plugin-search-react还优化了只在配置存在时才用默认设置初始化搜索上下文（45f8a95e1068）。此外search-backend-module-pg新增indexerBatchSize选项控制批量索引的大小，并增加调试日志输出批次内实体列表（4ccf9204bc95）。

7.3 TechDocs

• Azurite 支持（5985d458ee30，作用于plugin-techdocs-backend与plugin-techdocs-node）：新增techdocs.publisher.azureBlobStorage.connectionString配置项，便于本地使用 Azurite 模拟 Azure Blob 存储；
• Publisher 类型扩展（60af8017dd84）：techdocs.publisher.type补充googleGcs、awsS3、azureBlobStorage、openStackSwift等取值；
• 默认 mkdocs 插件（10a86bd4ae12，同时作用于@techdocs/cli@1.5.0）：TechDocs CLI 与后端支持通过可选配置/CLI 选项指定默认的 mkdocs 插件；
• Lightbox 缩放图标（86c19906fe4b，plugin-techdocs-module-addons-contrib）：文档内图片在 lightbox 中可缩放查看。

八、CLI 与工程化：repo fix与sideEffects优化

@backstage/cli@0.22.13带来多项工程化改进：

• repo fix命令（3494c502aba7）：自动修复所有包中可自动修复的问题，初始能力包括修复包的导出声明，以及把所有非打包前端包标记为side-effect free。标记"sideEffects": false可以显著减小 Webpack 打包体积——这也是 v1.18.0 中大量前端包出现406b786a2a2c（"Mark package as being free of side effects"）变更的原因。create-app@0.5.5同步在根package.json中新增"fix": "backstage-cli repo fix"脚本：

"test": "backstage-cli repo test", "test:all": "backstage-cli repo test --coverage", + "fix": "backstage-cli repo fix", "lint": "backstage-cli repo lint --since origin/master",

• --inspect监听地址可配置（04eabd21bee4）：例如--inspect=0.0.0.0:9229，方便在容器/远程环境下调试；
• 实验性后端启动命令的 ESM loader（4d5eeec52d80）与前端包发现支持（f36113ca2305）；
• new命令支持创建纯后端模块（278d9326eb40），后端插件/模块支持dev/index入口（71d4368ae5cc）；
• 移除了实验性的package fix命令（cd7331587eb3），其能力由@backstage/eslint-plugin的no-undeclared-imports规则替代。

create-app@0.5.5还默认切到 TypeScript 5.2（a4c08241ad92），并修复了后端模板为使用任务调度器的插件重复创建连接池的问题——若你的后端packages/backend/src/index.ts仍在使用旧写法，需按下述方式更新：

// in packages/backend/src/index.ts - const taskScheduler = TaskScheduler.fromConfig(config); + const taskScheduler = TaskScheduler.fromConfig(config, { databaseManager });

九、其它值得关注的变化

• MySQL 支持铺开（cfc3ca6ce060）：bazaar、catalog-backend、scaffolder-backend、tech-insights-backend、code-coverage-backend、app-backend、linguist-backend 等多个后端包完成 MySQL 适配，为多数据库部署铺路；
• 自动登出组件<AutoLogout>（9b74166d11a1，core-components@0.13.5）：提供基于用户非活跃时间的可选自动登出机制，详见 docs/auth/autologout.md；
• Permissions：permissionModuleAllowAllPolicy从permission-backend移入新的@backstage/plugin-permission-backend-module-allow-all-policy@0.1.0（84ad6fccd4d5/5f7b2153526b）；
• DevTools 资源利用率展示（12e644aa4eef）：DevTools 插件及后端开始展示资源利用情况；
• Vault secrets engine 覆盖（858a18800870）：可在 catalog 实体级别通过注解vault.io/secrets-engine覆盖 Vault secret engine；
• Table 加载指示器（47782f4bfa5b）：core-components的 Table 组件新增 loading 状态；
• StructuredMetadataTablenull 值修复（0c9907645aab）：元数据含null时不再崩溃；
• 后端代理配置错误提示（02ba0a2efd2a）：代理路由未正确配置时的报错会带上路由名，便于定位；
• version:bump重复项处理（4af4defcc114）：重复包名改为记录日志而非抛错。

十、升级建议与注意事项

综合 v1.18.0 的变更，升级时建议按以下顺序排查：

1. 后端插件导出迁移：所有新后端系统用法改为backend.add(import('@backstage/plugin-xxx'))默认导出形式；这是本版本最普遍、最需要动手的 Breaking Change。
2. 认证配置：若使用auth-backend的内置 provider，评估是否迁移到disableDefaultProviderFactories+ 独立 provider 模块的组合；将signIn逻辑迁移到声明式resolvers配置，以获得可配置、可复用的登录解析能力。
3. GitLab 目录集成：使用GitlabOrgDiscoveryEntityProvider（gitlab.com）必须补上group配置，否则后端无法启动。
4. Azure DevOps：token/credential已弃用，切换为credentials多组织配置。
5. Kubernetes：若自定义过认证翻译器，需按AuthenticationStrategy重写。
6. 数据库：接入 MySQL 的插件增多，多数据库部署的兼容面扩大。
7. 构建优化：运行yarn fix（backstage-cli repo fix）让所有前端包获得sideEffects: false标记，以获得更优的 Webpack 打包结果。

新前端系统（frontend-plugin-api/frontend-app-api）与 i18n 基础设施在此版本仍属实验阶段，生产环境接入前建议关注后续版本的稳定性承诺与迁移文档。

参考路径速查

• 变更原文：docs/releases/v1.18.0-changelog.md
• readDurationFromConfig实现：packages/config/src/readDurationFromConfig.ts
• 配置 schema 深度可见性继承：packages/config-loader/src/schema/compile.ts
• Sign-in Resolver 工厂：plugins/auth-node/src/sign-in/createSignInResolverFactory.ts
• 公共 Sign-in Resolver：plugins/auth-node/src/sign-in/commonSignInResolvers.ts
• Catalog 处理间隔解析：plugins/catalog-backend/src/service/CatalogBuilder.ts
• 认证相关文档：docs/auth/index.md 与 docs/auth/add-auth-provider.md

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