Backstage v1.40.0 版本解讀Scaffolder 2.0 遷移指南、后端限流與前端 Blueprint 生態演進【免費下載鏈接】backstageBackstage is an open framework for building developer portals項目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇文章圍繞 Backstage v1.40.0 的官方變更日志docs/releases/v1.40.0-changelog.md展開聚焦本版本最核心的三條主線plugin-scaffolder-backend邁入 2.0 大版本伴隨多組破壞性變更與 Zod Schema 遷移、backend-defaults新增可配置的請求限流中間件、以及新前端系統下EntityIconLinkBlueprint與插件info元數據機制的落地。讀完本文你將掌握如何遷移到 Scaffolder 2.0、如何在app-config.yaml中啟用全局/插件級限流、如何自定義 Catalog About 卡片圖標鏈接并了解新引入的 Kafka 事件模塊與 MCP Actions 后端等增量能力。一、版本概覽與升級路徑v1.40.0 是一個橫跨前后端、CLI 與多個插件的大版本其中值得重點關注的包有包名新版本變化級別backstage/plugin-scaffolder-backend2.0.0Major多組破壞性變更backstage/backend-defaults0.11.0Minor新增限流、Actions 服務默認實現backstage/backend-plugin-api1.4.0Minor新增實驗性 actions 服務backstage/plugin-catalog-react1.19.0Minor新增EntityIconLinkBlueprintbackstage/plugin-catalog1.31.0MinorAbout 卡片圖標鏈接擴展backstage/plugin-events-backend-module-kafka0.1.0全新模塊backstage/plugin-mcp-actions-backend0.1.0全新后端backstage/cli0.33.0Minor模塊化 CLI 入口轉正升級時建議使用官方 Upgrade Helper 工具定位到1.40.0目標版本逐項核對本文列出的破壞性變更對于自建 Backstage 應用執行backstage-cli versions:bump前請先確認packages/backend與packages/app中相關依賴的鎖定版本與變更日志中的依賴升級清單例如backstage/backend-defaults0.11.0、backstage/plugin-scaffolder-node0.9.0保持一致。二、Scaffolder Backend 2.0.0破壞性變更全解與遷移步驟backstage/plugin-scaffolder-backend在此版本發布 2.0.0包含了四組BREAKING CHANGES和一批棄用聲明是本次升級工作量最大的部分。倉庫中對應的實現位于 plugins/scaffolder-backend相關的類型與工具函數則集中在 plugins/scaffolder-node。2.1 清理長期存在的重導出re-exports第一組破壞性變更移除了從scaffolder-backend插件包中轉手導出的一批函數。它們已被分拆到各自的集成模塊中遷移映射如下原導入來源已移除遷移后的正確導入來源createPublishAzureActionbackstage/plugin-scaffolder-backend-module-azurecreatePublishBitbucketCloudActionbackstage/plugin-scaffolder-backend-module-bitbucket-cloudcreatePublishBitbucketServerAction、createPublishBitbucketServerPullRequestActionbackstage/plugin-scaffolder-backend-module-bitbucket-servercreatePublishBitbucketActionbackstage/plugin-scaffolder-backend-module-bitbucketcreatePublishGerritAction、createPublishGerritReviewActionbackstage/plugin-scaffolder-backend-module-gerritcreateGithubActionsDispatchAction、createGithubDeployKeyAction、createGithubEnvironmentAction、createGithubIssuesLabelAction、CreateGithubPullRequestActionOptions、createGithubRepoCreateAction、createGithubRepoPushAction、createGithubWebhookAction、createPublishGithubActionbackstage/plugin-scaffolder-backend-module-githubcreatePublishGitlabActionbackstage/plugin-scaffolder-backend-module-gitlabActionContext、createTemplateAction、executeShellCommand、ExecuteShellCommandOptions、fetchContents、TaskSecrets、TemplateActionbackstage/plugin-scaffolder-node此外還有兩組類型與實現需要遷移SerializedTask、SerializedTaskEvent、TaskBroker、TaskBrokerDispatchOptions、TaskBrokerDispatchResult、TaskCompletionState、TaskContext、TaskEventType、TaskStatus、TemplateFilter、TemplateGlobal應從backstage/plugin-scaffolder-node導入ScaffolderEntitiesProcessor應改為從backstage/plugin-catalog-backend-module-scaffolder-entity-model導入該處理器用于將 Scaffolder 生成的實體注冊進 Catalog相關實體模型定義見 plugins/catalog-backend-module-scaffolder-entity-model。與此同時fetch:template動作中已棄用的copyWithoutRender選項被徹底移除請統一改名為copyWithoutTemplating。2.2/alpha導出移除與舊后端系統createRouter退役第二組破壞性變更涉及兩件事backstage/plugin-scaffolder-backend/alpha不再導出插件本身請直接使用import(backstage/plugin-scaffolder-backend)舊后端系統使用的createRouter函數及其RouterOptions類型被移除。這意味著仍在用舊后端系統createRouterRouterOptions方式組裝 Scaffolder 的應用必須遷移到新后端系統createBackend 插件實例化否則升級后無法編譯。2.3createBuiltinActions移除與 Catalog 動作的依賴重構第三組破壞性變更createBuiltinActions方法被移除。它在舊后端系統中僅用于再次傳入默認動作列表而新后端系統默認會合并所有動作因此不再需要createCatalogRegisterAction與createFetchCatalogEntityAction不再依賴AuthService且參數由CatalogClient換成CatalogService。如果你是通過scaffolderActionsExtensionPoint自定義覆蓋默認動作并因此遇到類型錯誤可參考下面的遷移寫法源碼層面與此對應的擴展點聲明位于 plugins/scaffolder-node/src/alphaimport { catalogServiceRef } from backstage/plugin-catalog-node; import { scaffolderActionsExtensionPoint } from backstage/plugin-scaffolder-node/alpha; export const myModule createBackendModule({ pluginId: scaffolder, moduleId: test, register({ registerInit }) { registerInit({ deps: { scaffolder: scaffolderActionsExtensionPoint, catalog: catalogServiceRef, }, async init({ scaffolder, catalog }) { scaffolder.addActions( createCatalogRegisterAction({ catalog, }), createFetchCatalogEntityAction({ catalog, integrations, }), ); }, }); }, });無獨有偶plugin-scaffolder-backend-module-github的createGithubEnvironmentAction也做了同樣的依賴替換AuthService→CatalogService、CatalogClient→CatalogService遷移模式與此處完全一致。這一系列的改動表明Scaffolder 動作正在全面收斂到「通過CatalogService訪問目錄、通過scaffolderActionsExtensionPoint注冊動作」的新范式。2.4 一大批 Task/TaskStore 相關類型棄用v1.40.0 同時聲明了一批棄用類型包括CreateWorkerOptions、DatabaseTaskStore、DatabaseTaskStoreOptions、TaskManager、TaskStoreCreateTaskOptions、TaskStoreCreateTaskResult、TaskStoreEmitOptions、TaskStoreListEventsOptions、TaskStoreRecoverTaskOptions、TaskStoreShutDownTaskOptions。變更日志明確說明目前沒有直接的替代路徑這些類型將被移除并重新設計以在新后端系統中提供更優雅的 worker 定義方式。這意味著依賴這些內部類型做深度定制的團隊需要提前關注后續版本的替代方案。2.5 動作 Schema 遷移到 Zod 原生寫法backstage/plugin-scaffolder-node0.9.0將定義createTemplateAction輸入/輸出 Schema 的舊方式替換為原生的 Zod 方式。三階段寫法對照如下// 1) 最老的 JSON Schema 寫法已不推薦 createTemplateAction{ repoUrl: string }, { repoOutput: string }({ id: test, schema: { input: { type: object required: [repoUrl] properties: { repoUrl: { type: string, description: repository url description } } } } }); // 2) 舊的 Zod 寫法已不推薦 createTemplateAction({ id: test schema: { input: { repoUrl: z.string({ description: repository url description }) } } }) // 3) 新的 Zod 函數式寫法推薦 createTemplateAction({ id: test, schema: { input: { repoUrl: z z.string({ description: repository url description }) } } }) // 或對更復雜的聯合類型使用整體函數式寫法 createTemplateAction({ id: test, schema: { input: z z.object({ repoUrl: z.string({ description: repository url description }) }) } })新寫法把 schema 定義從值升級為函數使得 schema 可以延遲求值并復用zod的全部類型能力聯合、交叉、條件等。scaffolder-backend-module-*系列模塊azure、bitbucket、bitbucket-cloud、bitbucket-server、gerrit、gitea、gitlab、confluence-to-markdown、cookiecutter、rails、sentry、yeoman 等都在本版本統一遷移到新格式。重要附帶變更logStream已從ActionsContext中徹底移除ctx.logger現在直接是LoggerService實現。沒有官方替代方案若仍需使用 logStream官方建議自建一個寫入ctx.logger的流。相應地plugin-scaffolder-node-test-utils的createMockActionContext也移除了logStream參數。2.6 模板each步驟支持 Secrets一個很實用的新能力each步驟中可以直接引用${{ secrets.xxx }}。例如each: [ { name: Service1, token: ${{ secrets.token1 }} }, { name: Service2, token: ${{ secrets.token2 }} }, ]這意味著在軟件模板的循環步驟中按元素注入機密例如批量創建帶憑據的服務不再需要外部拼接。另外本版本為 Scaffolder 補充了更多測試e92e481可參考 plugins/scaffolder-backend 中的測試目錄了解動作行為的既有約定。三、backend-defaults 0.11.0全局與插件級請求限流backstage/backend-defaults0.11.0引入了基于express-rate-limit的限流中間件。其實現位于 packages/backend-defaults/src/lib/rateLimitMiddleware.ts并在 packages/backend-defaults/src/entrypoints/rootHttpRouter/rootHttpRouterServiceFactory.ts 的applyDefaults()中通過app.use(middleware.rateLimit())掛載到根 HTTP 路由。對應的單元測試見 packages/backend-defaults/src/lib/rateLimitMiddleware.test.ts 與 packages/backend-defaults/src/lib/RateLimitStoreFactory.test.ts。3.1 開啟全局限流在app-config.yaml中增加如下配置即可開啟backend: rateLimit: window: 6s incomingRequestLimit: 100window時間窗口支持時長字符串如6s源碼內部通過readDurationFromConfig解析并轉為毫秒incomingRequestLimit窗口內允許的最大請求數超限返回429。從源碼看該中間件還支持以下可選配置項均可寫入backend.rateLimit配置鍵作用ipAllowList放行 IP 列表默認值為[127.0.0.1, 0:0:0:0:0:0:0:1, ::1]本機地址默認放行skipSuccessfulRequests成功請求不計入限流skipFailedRequests失敗請求不計入限流passOnStoreError存儲層報錯時是否放行容錯此外限流鍵生成使用ipKeyGenerator對 IPv6 地址做規范化避免客戶端通過輪換塊內地址繞過限制validate.trustProxy被置為false在配置backend.trustProxy時需注意代理場景下的 IP 語義。3.2 插件級限流若只想限制某個插件的流量可關閉全局限流并為指定插件單獨配置backend: rateLimit: global: false # 關閉全局限流 plugin: catalog: window: 6s incomingRequestLimit: 100global: false關閉全局兜底plugin.catalog則為 catalog 插件單獨設定窗口與上限適合對高頻但易被打爆的插件接口做精細化保護。3.3 自定義configure回調的兼容提醒變更日志特別提醒如果你在 root HTTP router 服務的configure回調中自定義配置且沒有調用applyDefaults()需要把限流中間件以及其他默認中間件自行合入你的自定義配置否則升級后不會自動獲得限流能力。建議直接調用applyDefaults()并在其后追加自定義邏輯。四、實驗性 Actions 服務跨插件注冊與調用動作backstage/backend-plugin-api1.4.0在/alpha導出中新增了兩個實驗性服務actionsRegistry注冊分布式動作與actions調用動作并提供了默認實現c999c25落在backend-defaults中。典型用法import { actionsRegistryServiceRef, actionsServiceRef, } from backstage/backend-plugin-api/alpha; createBackendPlugin({ pluginId: test-plugin, register({ registerInit }) { registerInit({ deps: { actions: actionsServiceRef, actionsRegistry: actionsRegistryServiceRef, }, async init({ actions, actionsRegistry }) { actionsRegistry.register({ ..., }); await actions.invoke(...); }, }); }, });與之配套backstage/plugin-catalog-backend2.1.0已用ActionsRegistry實現了get-catalog-entity動作2e7adf0而backend-test-utils1.6.0也新增了對應的 mock 工具便于為動作編寫單元測試import { actionsRegistryServiceMock } from backstage/backend-test-utils/alpha; const mockActionsRegistry actionsRegistryServiceMock(); const mockCatalog catalogServiceMock({ entities: [ ... ], }); createGetCatalogEntityAction({ catalog: mockCatalog, actionsRegistry: mockActionsRegistry, }); await expect( mockActionsRegistry.invoke({ id: test:get-catalog-entity, input: { name: test }, }), ).resolves.toEqual(...)五、Catalog 新前端系統EntityIconLinkBlueprint 與 About 卡片自定義backstage/plugin-catalog-react1.19.0引入EntityIconLinkBlueprint用于自定義 Catalog 實體頁 About 卡片上的圖標鏈接。其 Blueprint 定義位于 plugins/catalog-react/src/alpha/blueprints/EntityIconLinkBlueprint.tsx它掛載在entity-card:catalog/about擴展點的iconLinks輸入上通過useProps數據 ref 輸出圖標鏈接屬性并支持filter按實體過濾與label/title配置覆蓋。5.1useProps返回的屬性表useProps鉤子返回以下屬性將透傳給圖標鏈接組件名稱描述類型默認值icon要顯示的圖標JSX.Element無label元素的標簽string無title元素的標題string無disabled是否禁用該元素booleanfalsehref點擊后跳轉的 URLstring無onClick點擊回調函數() void無5.2 使用示例import { EntityIconLinkBlueprint } from backstage/plugin-catalog-react/alpha; //... EntityIconLinkBlueprint.make({ name: my-icon-link, params: { useProps() { const { t } useTranslationRef(myIconLinkTranslationRef); return { label: t(myIconLink.label), icon: MyIconLinkIcon /, href: /my-plugin, }; }, }, });5.3 通過 app-config 覆蓋 label 與 title還可以在app-config.yaml中用app.extensions覆蓋默認圖標鏈接的label與titleapp: extensions: - entity-icon-link:my-plugin/my-icon-link: config: label: My Custom Icon Link label注意當沒有任何圖標鏈接擴展被啟用時About 卡片頭部會被整體隱藏適合把鏈接獨立展示在別的卡片上的場景。5.4 與 About 卡片默認鏈接的拆分backstage/plugin-catalog1.31.0中原本內置于 Catalog About 卡片鏈接的「Scaffolder 啟動模板」與「TechDocs 閱讀文檔」兩個圖標鏈接被抽取出來改由Scaffolder與TechDocs插件分別提供。這意味著未安裝 TechDocs/Scaffolder 插件時對應圖標將不再出現如果你為這兩個鏈接標題配置了非默認翻譯需要改用 Scaffolder/TechDocs 各自的 translation reference翻譯鍵保持不變aboutCard.viewTechdocs與aboutCard.launchTemplate。六、事件系統全新 Kafka 消費模塊backstage/plugin-events-backend-module-kafka0.1.0是全新的事件后端模塊位于 plugins/events-backend-module-kafka。它提供兩個核心件KafkaConsumerClient基于 KafkaJS 建立消費連接KafkaConsumingEventPublisher訂閱配置的 Kafka topic并把收到的消息發布到 Backstage 事件服務Event Service。從配置解析實現plugins/events-backend-module-kafka/src/KafkaConsumingEventPublisher/config.ts可以看出它支持多實例配置events.modules.kafka.kafkaConsumingEventPublisher下的每個鍵視為一個 publisher每個 publisher 可配置topics數組其中kafka.groupId、kafka.topics、kafka.fromBeginning為消費組與訂閱主題的核心參數kafka.sessionTimeout、kafka.rebalanceTimeout、kafka.heartbeatInterval、kafka.metadataMaxAge、kafka.maxBytesPerPartition、kafka.minBytes、kafka.maxBytes、kafka.maxWaitTime等可控制消費行為kafka.autoCommit默認true與kafka.pauseOnError默認false分別控制手動提交與出錯暫停策略。模塊測試見 plugins/events-backend-module-kafka/src/KafkaConsumingEventPublisher/module.test.ts。同時backstage/plugin-events-backend-module-google-pubsub0.1.1新增了EventConsumingGooglePubSubPublisher用于把 Backstage 事件推送回 Google Pub/Sub。七、通知系統廣播與保留期策略backstage/plugin-notifications-backend0.5.7帶來兩個值得注意的行為變化默認自動刪除一年前的通知新增的定時任務每 24 小時運行一次刪除超過 1 年的通知。可通過app-config.yaml配置保留期notifications: retention: 1y若將retention設為false則禁用自動清理。廣播通知的用戶字段通知 API 對廣播broadcast通知始終返回user: null避免誤導性地暴露發送者身份。此外通知與 Scaffolder 通知模塊plugin-scaffolder-backend-module-notifications都支持了在某個來源origin內按 topic 開關通知的用戶級能力1fb5f06。八、前端系統插件info元數據與useAppNodebackstage/frontend-plugin-api0.10.3為createFrontendPlugin增加了可選的info選項用于提供插件元數據加載器有兩種形式// 方式一加載插件自身的 package.json推薦給發布到包倉庫的插件 export default createFrontendPlugin({ pluginId: ..., info: { packageJson: () import(../package.json), }, }); // 方式二加載不透明 manifest僅限組織內使用禁止用于公開發布的插件 export default createFrontendPlugin({ pluginId: ..., info: { manifest: () import(../catalog-info.yaml), }, });packageJson指向插件包內的package.json適合任何在獨立包中定義、尤其是發布到公共包倉庫的插件manifest僅限在單一組織內部使用的插件可攜帶額外內部元數據默認 manifest 解析器能解析標準catalog-info.yaml格式及spec.owner等內置字段。配套能力包括frontend-app-api為createSpecializedApp支持了pluginInfoResolver選項并新增靜態配置鍵app.pluginOverridesbackstage/plugin-catalog等插件實例新增info.packageJson選項同時新增了useAppNode鉤子可從最近的ExtensionBoundary獲取AppNode引用。本版本大量插件catalog、techdocs、home、org、notifications、search、signals、user-settings、api-docs、devtools、kubernetes、catalog-import、catalog-graph、app-visualizer 等都同步接入了info.packageJson。九、CLI 與工具鏈更新backstage/cli0.33.0與backstage/create-app0.7.0的變化集中在開發者體驗BACKSTAGE_CLI_EXPERIMENTAL_BUILD_CACHE標志已移除改用EXPERIMENTAL_RSPACK實驗性的FORCE_REACT_DEVELOPMENT標志已移除Rspack 構建改用module-federation/enhanced/rspack的ModuleFederationPlugin僅在frontend包上啟用緩存型 Jest 模塊加載器避免破壞真實 ESM 導入backstage new生成的插件包模板默認在package.json中加入backstage.pluginId字段打開配置文檔命令增加了瀏覽器打開失敗時的回退提示d07fe35create-app在 gitignore 中補充了.cache目錄。backstage/eslint-plugin0.1.11新增backstage/no-mixed-plugin-imports規則禁止插件之間混用前后端/公共架構導入不允許前端插件導入后端插件或其他前端插件、不允許后端插件導入前端插件或其他后端插件、不允許公共插件導入前端或后端插件。當前推薦配置下該規則給出 warning未來將升級為 error建議提前調整工作區導入結構。十、其他值得關注的變更LDAP 模塊plugin-catalog-backend-module-ldap可將用戶memberOf或組members的映射設為null從而只保留單向或完全禁用成員關系規避 LDAP 中兩側屬性漂移導致的 Catalog 異常狀態示例配置見變更日志配置項落在catalog.providers.ldapOrg.default下。GitLab 模塊plugin-catalog-backend-module-gitlabUser/Group 發現默認會攝取指定根組下所有子組的用戶可通過模塊配置中的restrictUsersToGroup: true關閉同時為 GitLab API 調用增加了限流重試。Bitbucket Server 模塊plugin-catalog-backend-module-bitbucket-server新增validateLocationsExist選項避免為源倉庫中不存在的catalog-info.yaml生成 location。Bitbucket Cloud 模塊plugin-catalog-backend-module-bitbucket-cloudBitbucketCloudEntityProvider構造參數由CatalogApi換成CatalogService。GitHub 組織模塊plugin-catalog-backend-module-github處理事件時組織名匹配改為大小寫不敏感。權限規則plugin-catalog-backendHAS_LABEL權限規則現在可像HAS_ANNOTATION一樣指定可選值。TechDocs引入backstage.io/techdocs-entity-path注解可配合backstage.io/techdocs-entity深度鏈接到其他實體的 TechDocs 頁面同時改善了鍵盤可訪問性9dde3ba。Canon 組件庫backstage/canon0.5.0Button/IconButton默認尺寸改為 smallHeading/Text用asprop 取代 render propTextField基于 React Aria 重構并新增FieldLabelGrid 根組件改名為Grid.Root /并新增Switch組件。mcp-actions 后端backstage/plugin-mcp-actions-backend0.1.0MCP Actions 后端的初始實現詳見 plugins/mcp-actions-backend。auditor 服務backend-defaults錯誤處理增強將錯誤作為對象傳遞并統一了WinstonRootAuditorService與默認工廠的錯誤處理行為。catalog-backend 數據庫refresh_state_references.id更新為 bigint 類型4654a78涉及數據庫遷移的團隊需留意。search-backend-module-techdocs導出默認文檔 collator便于在搜索索引階段做文檔變換。yarn-plugin-backstage新增/更新依賴時保持backstage:^版本占位符。十一、升級建議與風險清單優先處理 Scaffolder 相關破壞性變更檢查自定義動作與后端模塊的所有導入來源對照本文 2.1 節的映射表逐一修正將動作 Schema 遷移到 Zod 函數式寫法移除對createBuiltinActions、createRouter、logStream的使用。確認是否使用了被棄用的 Task/TaskStore 類型DatabaseTaskStore等一批類型已標記棄用且暫無替代深度定制的團隊需為后續重構預留時間。限流默認關閉按需開啟限流是可選能力未配置backend.rateLimit時行為不變若自定義了 root HTTP router 的configure務必合并applyDefaults()。新前端系統下檢查 About 卡片若未安裝 TechDocs/Scaffolder 插件對應圖標鏈接會消失有自定義翻譯的需遷移到對應插件翻譯引用。關注實驗性 APIactionsRegistry/actions服務與info.packageJson/info.manifest均為/alpha或實驗性能力接口后續可能調整。升級順序建議先在測試環境按依賴圖backend-defaults→plugin-scaffolder-node→ 各scaffolder-backend-module-*→plugin-scaffolder-backend逐層驗證再通過 Upgrade Helper 對比目標版本最后執行全量versions:bump并跑通backstage-cli repo lint、tsc與測試套件。綜上v1.40.0 的核心信號是Scaffolder 徹底完成向新后端系統的收斂模塊化動作、Zod Schema、服務化 Catalog 訪問同時后端基礎設施限流、Actions 服務與前端定制體系Blueprint、插件元數據同步走向成熟是值得認真規劃的一次大版本升級。【免費下載鏈接】backstageBackstage is an open framework for building developer portals項目地址: https://gitcode.com/GitHub_Trending/ba/backstage創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 Backstage v1.40.0 版本解讀：Scaffolder 2.0 遷移指南、后端限流與前端 Blueprint 生態演進
Backstage v1.40.0 版本解讀Scaffolder 2.0 遷移指南、后端限流與前端 Blueprint 生態演進【免費下載鏈接】backstageBackstage is an open framework for building developer portals項目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇文章圍繞 Backstage v1.40.0 的官方變更日志docs/releases/v1.40.0-changelog.md展開聚焦本版本最核心的三條主線plugin-scaffolder-backend邁入 2.0 大版本伴隨多組破壞性變更與 Zod Schema 遷移、backend-defaults新增可配置的請求限流中間件、以及新前端系統下EntityIconLinkBlueprint與插件info元數據機制的落地。讀完本文你將掌握如何遷移到 Scaffolder 2.0、如何在app-config.yaml中啟用全局/插件級限流、如何自定義 Catalog About 卡片圖標鏈接并了解新引入的 Kafka 事件模塊與 MCP Actions 后端等增量能力。一、版本概覽與升級路徑v1.40.0 是一個橫跨前后端、CLI 與多個插件的大版本其中值得重點關注的包有包名新版本變化級別backstage/plugin-scaffolder-backend2.0.0Major多組破壞性變更backstage/backend-defaults0.11.0Minor新增限流、Actions 服務默認實現backstage/backend-plugin-api1.4.0Minor新增實驗性 actions 服務backstage/plugin-catalog-react1.19.0Minor新增EntityIconLinkBlueprintbackstage/plugin-catalog1.31.0MinorAbout 卡片圖標鏈接擴展backstage/plugin-events-backend-module-kafka0.1.0全新模塊backstage/plugin-mcp-actions-backend0.1.0全新后端backstage/cli0.33.0Minor模塊化 CLI 入口轉正升級時建議使用官方 Upgrade Helper 工具定位到1.40.0目標版本逐項核對本文列出的破壞性變更對于自建 Backstage 應用執行backstage-cli versions:bump前請先確認packages/backend與packages/app中相關依賴的鎖定版本與變更日志中的依賴升級清單例如backstage/backend-defaults0.11.0、backstage/plugin-scaffolder-node0.9.0保持一致。二、Scaffolder Backend 2.0.0破壞性變更全解與遷移步驟backstage/plugin-scaffolder-backend在此版本發布 2.0.0包含了四組BREAKING CHANGES和一批棄用聲明是本次升級工作量最大的部分。倉庫中對應的實現位于 plugins/scaffolder-backend相關的類型與工具函數則集中在 plugins/scaffolder-node。2.1 清理長期存在的重導出re-exports第一組破壞性變更移除了從scaffolder-backend插件包中轉手導出的一批函數。它們已被分拆到各自的集成模塊中遷移映射如下原導入來源已移除遷移后的正確導入來源createPublishAzureActionbackstage/plugin-scaffolder-backend-module-azurecreatePublishBitbucketCloudActionbackstage/plugin-scaffolder-backend-module-bitbucket-cloudcreatePublishBitbucketServerAction、createPublishBitbucketServerPullRequestActionbackstage/plugin-scaffolder-backend-module-bitbucket-servercreatePublishBitbucketActionbackstage/plugin-scaffolder-backend-module-bitbucketcreatePublishGerritAction、createPublishGerritReviewActionbackstage/plugin-scaffolder-backend-module-gerritcreateGithubActionsDispatchAction、createGithubDeployKeyAction、createGithubEnvironmentAction、createGithubIssuesLabelAction、CreateGithubPullRequestActionOptions、createGithubRepoCreateAction、createGithubRepoPushAction、createGithubWebhookAction、createPublishGithubActionbackstage/plugin-scaffolder-backend-module-githubcreatePublishGitlabActionbackstage/plugin-scaffolder-backend-module-gitlabActionContext、createTemplateAction、executeShellCommand、ExecuteShellCommandOptions、fetchContents、TaskSecrets、TemplateActionbackstage/plugin-scaffolder-node此外還有兩組類型與實現需要遷移SerializedTask、SerializedTaskEvent、TaskBroker、TaskBrokerDispatchOptions、TaskBrokerDispatchResult、TaskCompletionState、TaskContext、TaskEventType、TaskStatus、TemplateFilter、TemplateGlobal應從backstage/plugin-scaffolder-node導入ScaffolderEntitiesProcessor應改為從backstage/plugin-catalog-backend-module-scaffolder-entity-model導入該處理器用于將 Scaffolder 生成的實體注冊進 Catalog相關實體模型定義見 plugins/catalog-backend-module-scaffolder-entity-model。與此同時fetch:template動作中已棄用的copyWithoutRender選項被徹底移除請統一改名為copyWithoutTemplating。2.2/alpha導出移除與舊后端系統createRouter退役第二組破壞性變更涉及兩件事backstage/plugin-scaffolder-backend/alpha不再導出插件本身請直接使用import(backstage/plugin-scaffolder-backend)舊后端系統使用的createRouter函數及其RouterOptions類型被移除。這意味著仍在用舊后端系統createRouterRouterOptions方式組裝 Scaffolder 的應用必須遷移到新后端系統createBackend 插件實例化否則升級后無法編譯。2.3createBuiltinActions移除與 Catalog 動作的依賴重構第三組破壞性變更createBuiltinActions方法被移除。它在舊后端系統中僅用于再次傳入默認動作列表而新后端系統默認會合并所有動作因此不再需要createCatalogRegisterAction與createFetchCatalogEntityAction不再依賴AuthService且參數由CatalogClient換成CatalogService。如果你是通過scaffolderActionsExtensionPoint自定義覆蓋默認動作并因此遇到類型錯誤可參考下面的遷移寫法源碼層面與此對應的擴展點聲明位于 plugins/scaffolder-node/src/alphaimport { catalogServiceRef } from backstage/plugin-catalog-node; import { scaffolderActionsExtensionPoint } from backstage/plugin-scaffolder-node/alpha; export const myModule createBackendModule({ pluginId: scaffolder, moduleId: test, register({ registerInit }) { registerInit({ deps: { scaffolder: scaffolderActionsExtensionPoint, catalog: catalogServiceRef, }, async init({ scaffolder, catalog }) { scaffolder.addActions( createCatalogRegisterAction({ catalog, }), createFetchCatalogEntityAction({ catalog, integrations, }), ); }, }); }, });無獨有偶plugin-scaffolder-backend-module-github的createGithubEnvironmentAction也做了同樣的依賴替換AuthService→CatalogService、CatalogClient→CatalogService遷移模式與此處完全一致。這一系列的改動表明Scaffolder 動作正在全面收斂到「通過CatalogService訪問目錄、通過scaffolderActionsExtensionPoint注冊動作」的新范式。2.4 一大批 Task/TaskStore 相關類型棄用v1.40.0 同時聲明了一批棄用類型包括CreateWorkerOptions、DatabaseTaskStore、DatabaseTaskStoreOptions、TaskManager、TaskStoreCreateTaskOptions、TaskStoreCreateTaskResult、TaskStoreEmitOptions、TaskStoreListEventsOptions、TaskStoreRecoverTaskOptions、TaskStoreShutDownTaskOptions。變更日志明確說明目前沒有直接的替代路徑這些類型將被移除并重新設計以在新后端系統中提供更優雅的 worker 定義方式。這意味著依賴這些內部類型做深度定制的團隊需要提前關注后續版本的替代方案。2.5 動作 Schema 遷移到 Zod 原生寫法backstage/plugin-scaffolder-node0.9.0將定義createTemplateAction輸入/輸出 Schema 的舊方式替換為原生的 Zod 方式。三階段寫法對照如下// 1) 最老的 JSON Schema 寫法已不推薦 createTemplateAction{ repoUrl: string }, { repoOutput: string }({ id: test, schema: { input: { type: object required: [repoUrl] properties: { repoUrl: { type: string, description: repository url description } } } } }); // 2) 舊的 Zod 寫法已不推薦 createTemplateAction({ id: test schema: { input: { repoUrl: z.string({ description: repository url description }) } } }) // 3) 新的 Zod 函數式寫法推薦 createTemplateAction({ id: test, schema: { input: { repoUrl: z z.string({ description: repository url description }) } } }) // 或對更復雜的聯合類型使用整體函數式寫法 createTemplateAction({ id: test, schema: { input: z z.object({ repoUrl: z.string({ description: repository url description }) }) } })新寫法把 schema 定義從值升級為函數使得 schema 可以延遲求值并復用zod的全部類型能力聯合、交叉、條件等。scaffolder-backend-module-*系列模塊azure、bitbucket、bitbucket-cloud、bitbucket-server、gerrit、gitea、gitlab、confluence-to-markdown、cookiecutter、rails、sentry、yeoman 等都在本版本統一遷移到新格式。重要附帶變更logStream已從ActionsContext中徹底移除ctx.logger現在直接是LoggerService實現。沒有官方替代方案若仍需使用 logStream官方建議自建一個寫入ctx.logger的流。相應地plugin-scaffolder-node-test-utils的createMockActionContext也移除了logStream參數。2.6 模板each步驟支持 Secrets一個很實用的新能力each步驟中可以直接引用${{ secrets.xxx }}。例如each: [ { name: Service1, token: ${{ secrets.token1 }} }, { name: Service2, token: ${{ secrets.token2 }} }, ]這意味著在軟件模板的循環步驟中按元素注入機密例如批量創建帶憑據的服務不再需要外部拼接。另外本版本為 Scaffolder 補充了更多測試e92e481可參考 plugins/scaffolder-backend 中的測試目錄了解動作行為的既有約定。三、backend-defaults 0.11.0全局與插件級請求限流backstage/backend-defaults0.11.0引入了基于express-rate-limit的限流中間件。其實現位于 packages/backend-defaults/src/lib/rateLimitMiddleware.ts并在 packages/backend-defaults/src/entrypoints/rootHttpRouter/rootHttpRouterServiceFactory.ts 的applyDefaults()中通過app.use(middleware.rateLimit())掛載到根 HTTP 路由。對應的單元測試見 packages/backend-defaults/src/lib/rateLimitMiddleware.test.ts 與 packages/backend-defaults/src/lib/RateLimitStoreFactory.test.ts。3.1 開啟全局限流在app-config.yaml中增加如下配置即可開啟backend: rateLimit: window: 6s incomingRequestLimit: 100window時間窗口支持時長字符串如6s源碼內部通過readDurationFromConfig解析并轉為毫秒incomingRequestLimit窗口內允許的最大請求數超限返回429。從源碼看該中間件還支持以下可選配置項均可寫入backend.rateLimit配置鍵作用ipAllowList放行 IP 列表默認值為[127.0.0.1, 0:0:0:0:0:0:0:1, ::1]本機地址默認放行skipSuccessfulRequests成功請求不計入限流skipFailedRequests失敗請求不計入限流passOnStoreError存儲層報錯時是否放行容錯此外限流鍵生成使用ipKeyGenerator對 IPv6 地址做規范化避免客戶端通過輪換塊內地址繞過限制validate.trustProxy被置為false在配置backend.trustProxy時需注意代理場景下的 IP 語義。3.2 插件級限流若只想限制某個插件的流量可關閉全局限流并為指定插件單獨配置backend: rateLimit: global: false # 關閉全局限流 plugin: catalog: window: 6s incomingRequestLimit: 100global: false關閉全局兜底plugin.catalog則為 catalog 插件單獨設定窗口與上限適合對高頻但易被打爆的插件接口做精細化保護。3.3 自定義configure回調的兼容提醒變更日志特別提醒如果你在 root HTTP router 服務的configure回調中自定義配置且沒有調用applyDefaults()需要把限流中間件以及其他默認中間件自行合入你的自定義配置否則升級后不會自動獲得限流能力。建議直接調用applyDefaults()并在其后追加自定義邏輯。四、實驗性 Actions 服務跨插件注冊與調用動作backstage/backend-plugin-api1.4.0在/alpha導出中新增了兩個實驗性服務actionsRegistry注冊分布式動作與actions調用動作并提供了默認實現c999c25落在backend-defaults中。典型用法import { actionsRegistryServiceRef, actionsServiceRef, } from backstage/backend-plugin-api/alpha; createBackendPlugin({ pluginId: test-plugin, register({ registerInit }) { registerInit({ deps: { actions: actionsServiceRef, actionsRegistry: actionsRegistryServiceRef, }, async init({ actions, actionsRegistry }) { actionsRegistry.register({ ..., }); await actions.invoke(...); }, }); }, });與之配套backstage/plugin-catalog-backend2.1.0已用ActionsRegistry實現了get-catalog-entity動作2e7adf0而backend-test-utils1.6.0也新增了對應的 mock 工具便于為動作編寫單元測試import { actionsRegistryServiceMock } from backstage/backend-test-utils/alpha; const mockActionsRegistry actionsRegistryServiceMock(); const mockCatalog catalogServiceMock({ entities: [ ... ], }); createGetCatalogEntityAction({ catalog: mockCatalog, actionsRegistry: mockActionsRegistry, }); await expect( mockActionsRegistry.invoke({ id: test:get-catalog-entity, input: { name: test }, }), ).resolves.toEqual(...)五、Catalog 新前端系統EntityIconLinkBlueprint 與 About 卡片自定義backstage/plugin-catalog-react1.19.0引入EntityIconLinkBlueprint用于自定義 Catalog 實體頁 About 卡片上的圖標鏈接。其 Blueprint 定義位于 plugins/catalog-react/src/alpha/blueprints/EntityIconLinkBlueprint.tsx它掛載在entity-card:catalog/about擴展點的iconLinks輸入上通過useProps數據 ref 輸出圖標鏈接屬性并支持filter按實體過濾與label/title配置覆蓋。5.1useProps返回的屬性表useProps鉤子返回以下屬性將透傳給圖標鏈接組件名稱描述類型默認值icon要顯示的圖標JSX.Element無label元素的標簽string無title元素的標題string無disabled是否禁用該元素booleanfalsehref點擊后跳轉的 URLstring無onClick點擊回調函數() void無5.2 使用示例import { EntityIconLinkBlueprint } from backstage/plugin-catalog-react/alpha; //... EntityIconLinkBlueprint.make({ name: my-icon-link, params: { useProps() { const { t } useTranslationRef(myIconLinkTranslationRef); return { label: t(myIconLink.label), icon: MyIconLinkIcon /, href: /my-plugin, }; }, }, });5.3 通過 app-config 覆蓋 label 與 title還可以在app-config.yaml中用app.extensions覆蓋默認圖標鏈接的label與titleapp: extensions: - entity-icon-link:my-plugin/my-icon-link: config: label: My Custom Icon Link label注意當沒有任何圖標鏈接擴展被啟用時About 卡片頭部會被整體隱藏適合把鏈接獨立展示在別的卡片上的場景。5.4 與 About 卡片默認鏈接的拆分backstage/plugin-catalog1.31.0中原本內置于 Catalog About 卡片鏈接的「Scaffolder 啟動模板」與「TechDocs 閱讀文檔」兩個圖標鏈接被抽取出來改由Scaffolder與TechDocs插件分別提供。這意味著未安裝 TechDocs/Scaffolder 插件時對應圖標將不再出現如果你為這兩個鏈接標題配置了非默認翻譯需要改用 Scaffolder/TechDocs 各自的 translation reference翻譯鍵保持不變aboutCard.viewTechdocs與aboutCard.launchTemplate。六、事件系統全新 Kafka 消費模塊backstage/plugin-events-backend-module-kafka0.1.0是全新的事件后端模塊位于 plugins/events-backend-module-kafka。它提供兩個核心件KafkaConsumerClient基于 KafkaJS 建立消費連接KafkaConsumingEventPublisher訂閱配置的 Kafka topic并把收到的消息發布到 Backstage 事件服務Event Service。從配置解析實現plugins/events-backend-module-kafka/src/KafkaConsumingEventPublisher/config.ts可以看出它支持多實例配置events.modules.kafka.kafkaConsumingEventPublisher下的每個鍵視為一個 publisher每個 publisher 可配置topics數組其中kafka.groupId、kafka.topics、kafka.fromBeginning為消費組與訂閱主題的核心參數kafka.sessionTimeout、kafka.rebalanceTimeout、kafka.heartbeatInterval、kafka.metadataMaxAge、kafka.maxBytesPerPartition、kafka.minBytes、kafka.maxBytes、kafka.maxWaitTime等可控制消費行為kafka.autoCommit默認true與kafka.pauseOnError默認false分別控制手動提交與出錯暫停策略。模塊測試見 plugins/events-backend-module-kafka/src/KafkaConsumingEventPublisher/module.test.ts。同時backstage/plugin-events-backend-module-google-pubsub0.1.1新增了EventConsumingGooglePubSubPublisher用于把 Backstage 事件推送回 Google Pub/Sub。七、通知系統廣播與保留期策略backstage/plugin-notifications-backend0.5.7帶來兩個值得注意的行為變化默認自動刪除一年前的通知新增的定時任務每 24 小時運行一次刪除超過 1 年的通知。可通過app-config.yaml配置保留期notifications: retention: 1y若將retention設為false則禁用自動清理。廣播通知的用戶字段通知 API 對廣播broadcast通知始終返回user: null避免誤導性地暴露發送者身份。此外通知與 Scaffolder 通知模塊plugin-scaffolder-backend-module-notifications都支持了在某個來源origin內按 topic 開關通知的用戶級能力1fb5f06。八、前端系統插件info元數據與useAppNodebackstage/frontend-plugin-api0.10.3為createFrontendPlugin增加了可選的info選項用于提供插件元數據加載器有兩種形式// 方式一加載插件自身的 package.json推薦給發布到包倉庫的插件 export default createFrontendPlugin({ pluginId: ..., info: { packageJson: () import(../package.json), }, }); // 方式二加載不透明 manifest僅限組織內使用禁止用于公開發布的插件 export default createFrontendPlugin({ pluginId: ..., info: { manifest: () import(../catalog-info.yaml), }, });packageJson指向插件包內的package.json適合任何在獨立包中定義、尤其是發布到公共包倉庫的插件manifest僅限在單一組織內部使用的插件可攜帶額外內部元數據默認 manifest 解析器能解析標準catalog-info.yaml格式及spec.owner等內置字段。配套能力包括frontend-app-api為createSpecializedApp支持了pluginInfoResolver選項并新增靜態配置鍵app.pluginOverridesbackstage/plugin-catalog等插件實例新增info.packageJson選項同時新增了useAppNode鉤子可從最近的ExtensionBoundary獲取AppNode引用。本版本大量插件catalog、techdocs、home、org、notifications、search、signals、user-settings、api-docs、devtools、kubernetes、catalog-import、catalog-graph、app-visualizer 等都同步接入了info.packageJson。九、CLI 與工具鏈更新backstage/cli0.33.0與backstage/create-app0.7.0的變化集中在開發者體驗BACKSTAGE_CLI_EXPERIMENTAL_BUILD_CACHE標志已移除改用EXPERIMENTAL_RSPACK實驗性的FORCE_REACT_DEVELOPMENT標志已移除Rspack 構建改用module-federation/enhanced/rspack的ModuleFederationPlugin僅在frontend包上啟用緩存型 Jest 模塊加載器避免破壞真實 ESM 導入backstage new生成的插件包模板默認在package.json中加入backstage.pluginId字段打開配置文檔命令增加了瀏覽器打開失敗時的回退提示d07fe35create-app在 gitignore 中補充了.cache目錄。backstage/eslint-plugin0.1.11新增backstage/no-mixed-plugin-imports規則禁止插件之間混用前后端/公共架構導入不允許前端插件導入后端插件或其他前端插件、不允許后端插件導入前端插件或其他后端插件、不允許公共插件導入前端或后端插件。當前推薦配置下該規則給出 warning未來將升級為 error建議提前調整工作區導入結構。十、其他值得關注的變更LDAP 模塊plugin-catalog-backend-module-ldap可將用戶memberOf或組members的映射設為null從而只保留單向或完全禁用成員關系規避 LDAP 中兩側屬性漂移導致的 Catalog 異常狀態示例配置見變更日志配置項落在catalog.providers.ldapOrg.default下。GitLab 模塊plugin-catalog-backend-module-gitlabUser/Group 發現默認會攝取指定根組下所有子組的用戶可通過模塊配置中的restrictUsersToGroup: true關閉同時為 GitLab API 調用增加了限流重試。Bitbucket Server 模塊plugin-catalog-backend-module-bitbucket-server新增validateLocationsExist選項避免為源倉庫中不存在的catalog-info.yaml生成 location。Bitbucket Cloud 模塊plugin-catalog-backend-module-bitbucket-cloudBitbucketCloudEntityProvider構造參數由CatalogApi換成CatalogService。GitHub 組織模塊plugin-catalog-backend-module-github處理事件時組織名匹配改為大小寫不敏感。權限規則plugin-catalog-backendHAS_LABEL權限規則現在可像HAS_ANNOTATION一樣指定可選值。TechDocs引入backstage.io/techdocs-entity-path注解可配合backstage.io/techdocs-entity深度鏈接到其他實體的 TechDocs 頁面同時改善了鍵盤可訪問性9dde3ba。Canon 組件庫backstage/canon0.5.0Button/IconButton默認尺寸改為 smallHeading/Text用asprop 取代 render propTextField基于 React Aria 重構并新增FieldLabelGrid 根組件改名為Grid.Root /并新增Switch組件。mcp-actions 后端backstage/plugin-mcp-actions-backend0.1.0MCP Actions 后端的初始實現詳見 plugins/mcp-actions-backend。auditor 服務backend-defaults錯誤處理增強將錯誤作為對象傳遞并統一了WinstonRootAuditorService與默認工廠的錯誤處理行為。catalog-backend 數據庫refresh_state_references.id更新為 bigint 類型4654a78涉及數據庫遷移的團隊需留意。search-backend-module-techdocs導出默認文檔 collator便于在搜索索引階段做文檔變換。yarn-plugin-backstage新增/更新依賴時保持backstage:^版本占位符。十一、升級建議與風險清單優先處理 Scaffolder 相關破壞性變更檢查自定義動作與后端模塊的所有導入來源對照本文 2.1 節的映射表逐一修正將動作 Schema 遷移到 Zod 函數式寫法移除對createBuiltinActions、createRouter、logStream的使用。確認是否使用了被棄用的 Task/TaskStore 類型DatabaseTaskStore等一批類型已標記棄用且暫無替代深度定制的團隊需為后續重構預留時間。限流默認關閉按需開啟限流是可選能力未配置backend.rateLimit時行為不變若自定義了 root HTTP router 的configure務必合并applyDefaults()。新前端系統下檢查 About 卡片若未安裝 TechDocs/Scaffolder 插件對應圖標鏈接會消失有自定義翻譯的需遷移到對應插件翻譯引用。關注實驗性 APIactionsRegistry/actions服務與info.packageJson/info.manifest均為/alpha或實驗性能力接口后續可能調整。升級順序建議先在測試環境按依賴圖backend-defaults→plugin-scaffolder-node→ 各scaffolder-backend-module-*→plugin-scaffolder-backend逐層驗證再通過 Upgrade Helper 對比目標版本最后執行全量versions:bump并跑通backstage-cli repo lint、tsc與測試套件。綜上v1.40.0 的核心信號是Scaffolder 徹底完成向新后端系統的收斂模塊化動作、Zod Schema、服務化 Catalog 訪問同時后端基礎設施限流、Actions 服務與前端定制體系Blueprint、插件元數據同步走向成熟是值得認真規劃的一次大版本升級。【免費下載鏈接】backstageBackstage is an open framework for building developer portals項目地址: https://gitcode.com/GitHub_Trending/ba/backstage創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考