Backstage v1.41.0 升級指南catalog-backend 3.0.0 破壞性變更與 Scaffolder 任務權限模型重構【免費下載鏈接】backstageBackstage is an open framework for building developer portals項目地址: https://gitcode.com/GitHub_Trending/ba/backstageBackstage v1.41.0 是一次包含多個 Major 版本升級的重要發(fā)布其中最核心的是backstage/plugin-catalog-backend迎來 3.0.0 大版本涉及縫補stitching策略、孤兒實體處理策略、UrlReader 搜索行為等多處默認行為切換同時 Scaffolder 的任務權限從基礎權限升級為 Resource Permissionsbackstage/canon也正式更名為backstage/ui。閱讀本文后你將掌握 v1.41.0 中每項破壞性變更的具體含義、如何通過配置適配新行為以及 Scaffolder 新的任務級條件授權規(guī)則isTaskOwner的編寫與驗證方式。本文基于倉庫內官方發(fā)布說明 docs/releases/v1.41.0-changelog.md 整理并輔以對應源碼佐證幫助你快速評估升級影響面并規(guī)劃遷移動作。升級前必讀總體變更概覽v1.41.0 的變更集中在以下幾個方面關注點涉及包變更類型影響Catalog 默認策略切換backstage/plugin-catalog-backend3.0.0Major / BREAKING需檢查app-config.yaml中相關配置Scaffolder 任務權限模型plugin-scaffolder、plugin-scaffolder-backend、plugin-scaffolder-common、plugin-scaffolder-node、plugin-scaffolder-reactMinor / BREAKING (/alpha)自定義權限策略需適配UI 組件庫更名backstage/canon→backstage/uiMinor / Breaking涉及組件 API 與 CSS 類名通知與郵件處理器plugin-notifications-backend、notifications-backend-module-emailPatch新增配置項向后兼容Scaffolder 模塊plugin-scaffolder-backend-module-github等Patch新增filesToDelete能力此外backstage/core-app-api1.18.0、backstage/repo-tools0.15.0、backstage/backend-test-utils1.7.0也有少量增強例如 credentials 對象新增標準toString方法、package-docs命令會先清空輸出目錄并跳過內部包等。catalog-backend 3.0.0四項默認行為切換backstage/plugin-catalog-backend從 2.x 直接升到 3.0.0攜帶四項 Breaking 變更全部與默認行為有關。多數情況下你不需要改任何代碼但需要確認既有配置沒有依賴舊默認值。1. 默認縫補策略切換為deferred變更內容默認的catalog.stitchingStrategy由原來的{ mode: immediate }切換為{ mode: deferred }對應提交5127ebe。源碼層面stitching/types.ts 中的stitchingStrategyFromConfig已經不再接受immediate模式if (strategyMode immediate) { // 記錄一條棄用警告并回退到 deferred options?.logger?.warn( The immediate stitching strategy mode has been removed and is no longer supported. Falling back to deferred stitching. Please remove the catalog.stitchingStrategy.mode configuration key., ); }從源碼看immediate模式在 v1.41.0 中已被徹底移除配置了該值會打印警告并自動回退到deferred。deferred 模式通過后臺 worker 異步完成實體與關系數據的縫合配置項為catalog: stitchingStrategy: # mode 已不再需要顯式聲明immediate 已失效 pollingInterval: { seconds: 1 } # 默認 1 秒deferred worker 輪詢間隔 stitchTimeout: { seconds: 60 } # 默認 60 秒單次縫合超時在 DefaultStitcher.ts 中可以看到縫合器正是通過stitchingStrategyFromConfig讀取以上配置。若你此前顯式配置了mode: immediate請在升級時刪除該鍵。2. 關系兼容模式不再默認開啟變更內容d675d96關系relations兼容模式不再默認啟用同時刪除了disableRelationsCompatiblity開關需要兼容舊行為時改用新增的enableRelationsCompatibility標志重新開啟。這屬于默認值反轉型破壞性變更如果你的后端此前依賴舊的關系讀寫行為且從未配置過相關標志升級后行為會變化如需保留舊行為配置為catalog: enableRelationsCompatibility: true3. 移除實驗性開關catalog.useUrlReadersSearch變更內容2339363v1.36 引入的實驗性配置catalog.useUrlReadersSearch被移除。UrlReaderProcessor現在始終調用UrlReaders的search方法。行為變化在于職責轉移舊行為只有當解析出的 Git URL 文件名包含通配符時才調用search方法否則走readUrl新行為每個UrlReaderService實現必須在自己的search方法內部判斷傳入的是具體 URL 還是包含通配符的搜索模式并使用各自 provider 特有的邏輯處理。內置的UrlReaderService實現已隨本版本完成適配相關修改在backstage/backend-defaults0.11.1與backstage/integration1.17.1中。如果你維護自定義的UrlReaderService實現必須同步改寫其search方法以正確處理這兩類輸入否則目錄處理將出現回歸。倉庫內搜索useUrlReadersSearch已無任何命中說明該開關在源碼中已徹底移除。4. 孤兒實體處理策略默認改為刪除兩項相關變更catalog.orphanStrategy默認值切換為delete687bfc8處理引擎在發(fā)現孤兒實體其來源 location 已不再被跟蹤的實體時默認刪除catalog.orphanProviderStrategy默認值切換為delete5de7a9d對于由 Entity Provider 提供、但 provider 已不再匯報的實體同樣默認刪除。源碼佐證在 DefaultCatalogProcessingEngine.ts 中處理引擎讀取catalog.orphanStrategy未配置時回退為delete在 CatalogBuilder.ts 中start()階段會調用evictEntitiesFromOrphanedProviders清理孤兒 provider 實體——只有顯式配置catalog.orphanProviderStrategy: keep才會跳過該清理。如需保留舊行為不自動刪除請顯式配置catalog: orphanStrategy: keep # 或 delete默認 orphanProviderStrategy: keep # 或 delete默認5. 其他值得注意的 catalog 相關修復plugin-catalog在新前端系統(tǒng)中默認開啟分頁pagination并支持配置6991dab新前端系統(tǒng)的卡片擴展改用新的實體謂詞且 User/Group 頁面不再顯示 about 卡片3ab9b96plugin-catalog-react修復了 alpha 實體謂詞中$in操作符誤區(qū)分大小寫的問題a07feb7plugin-catalog-import修復了ResponseError拋出后的錯誤信息展示問題406b8b8InMemoryCatalogClient現在支持以數組形式過濾實體6fb4143。Scaffolder 任務權限升級為 Resource Permissionsv1.41.0 中 Scaffolder 系列包plugin-scaffolder、plugin-scaffolder-backend、plugin-scaffolder-common、plugin-scaffolder-node、plugin-scaffolder-react共同完成了一次/alpha級別的權限模型重構提交c1ce316對自定義權限策略的使用者有直接影響。變更一scaffolder.task.read與scaffolder.task.cancel變?yōu)?Resource Permissions此前這兩個權限是普通權限現在它們都關聯到新的資源類型scaffolder-task。在 permissions.ts 中可以看到export const RESOURCE_TYPE_SCAFFOLDER_TASK scaffolder-task; export const taskReadPermission createPermission({ name: scaffolder.task.read, attributes: { action: read }, resourceType: RESOURCE_TYPE_SCAFFOLDER_TASK, }); export const taskCancelPermission createPermission({ name: scaffolder.task.cancel, attributes: {}, resourceType: RESOURCE_TYPE_SCAFFOLDER_TASK, });scaffolder.task.create仍是普通權限無資源類型。這意味著你的權限策略PermissionPolicy在處理scaffolder.task.read/scaffolder.task.cancel時可以通過resourceRef拿到具體的SerializedTask從而按任務維度做條件授權。變更二新增條件規(guī)則isTaskOwner為配合資源化改造新增了條件規(guī)則isTaskOwner用于限制誰能讀取 / 取消某任務。規(guī)則實現在 rules.tsexport const isTaskOwner createTaskPermissionRule({ name: IS_TASK_OWNER, description: Allows tasks created by certain users to be accessible, resourceType: RESOURCE_TYPE_SCAFFOLDER_TASK, paramsSchema: z.object({ createdBy: z .array(z.string()) .describe(List of creator entity refs; only tasks created by these users will be viewable), }), apply: (resource, { createdBy }) { if (!resource.createdBy) { return false; } return createdBy.includes(resource.createdBy); }, toQuery: ({ createdBy }) { return { key: created_by, values: createdBy, }; }, });該規(guī)則參數createdBy為實體引用entity ref數組apply階段判斷任務的createdBy是否命中列表任務無創(chuàng)建者時直接拒絕同時提供toQuery將條件轉換為數據庫查詢條件created_by IN (...)使得列表查詢階段即可完成過濾無需逐條加載任務。配合測試用例 rules.test.ts 可以看到該規(guī)則的apply與toQuery行為均有覆蓋驗證。變更三重試任務所需權限變化重試retry一個任務從原先要求scaffolder.task.readscaffolder.task.cancel改為要求scaffolder.task.readscaffolder.task.create。如果你用權限策略而非 Allow-All管控 Scaffolder需要在策略中同步更新重試操作所需權限。權限策略適配示例假設你希望只有任務創(chuàng)建者本人可以查看和取消自己的任務可以基于isTaskOwner編寫條件規(guī)則import { createConditionalDecision, PermissionCriteria, } from backstage/plugin-permission-common; import { isTaskOwner } from backstage/plugin-scaffolder-backend; // 在 PermissionPolicy 的 handle 中 if (isPermission(request.permission, taskReadPermission) || isPermission(request.permission, taskCancelPermission)) { return createConditionalDecision(request.permission, { anyOf: [{ allOf: [{ rule: isTaskOwner, params: { createdBy: [userEntityRef] } }] }], }); }同時注意重試操作現在需要taskCreatePermission請確保策略中對該權限給出允許或條件判斷。其他 Scaffolder 變更Scaffolder 審計日志現在包含taskId和createdBy424610a模板表單在步驟間切換時自動滾動回頁面頂部94c11a5MultiEntityPicker會基于渲染后的選項值過濾選項289e4a1publish:github:pull-requestaction 新增filesToDelete輸入可在 PR 中刪除文件f36bcf9- action: publish:github:pull-request id: clean-up-pr input: description: This is the description filesToDelete: - outdated/changelog.md - sample-file.txt owner: owner repo: repo title: Title Goes HereUI 組件庫更名canon → Backstage UIv1.41.0 完成了組件庫的品牌與包名遷移backstage/canon棄用正式更名為backstage/uie92bb9b所有 CSS 變量前綴從--canon改為--bui組件類名從.canon-*改為.bui-*8fd6fcb所有 CSS 文件合并為單一的styles.css140f652。如果你的項目直接使用 Canon 組件或覆蓋了相關 CSS 變量/類名升級時需要同步替換前綴。涉及的新增與調整還包括新增Card、SearchField、Header、RadioGroupRadio、Skeleton組件以及Button/ButtonIcon/ButtonLink新增 tertiary 變體等。Canon 組件向 React Aria 遷移BreakingCanon/UI 的多個基礎組件底層切換到 React Aria帶來以下 API 破壞性變化組件變化Linkto屬性改為href以統(tǒng)一內部與外部路由1d64db6Select大部分 props 與事件按 React Aria 底層 API 調整83fd7f4Tabs基于 React Aria 重構并直接兼容 react-router-domcae63dfButton系列新增ButtonLink取代 render-prop 模式IconButton更名為ButtonIcon移除所有按鈕組件上的 render prop4c6d891Tooltip組件結構與 props 按 React Aria 底層結構調整2e30459通知、認證與其他基礎設施更新通知系統(tǒng)plugin-notifications-backend支持通過配置定義默認通知設置4401dfb并為已有user_settings的場景修復了addTopic遷移問題9a5a73fnotifications-backend-module-email為 SES 郵件選項新增可選配置sourceArn、fromArn、configurationSetNamef92c9fc適合通過 AWS SES 發(fā)送通知郵件的場景。認證與會話core-app-api1.18.0會話刷新失敗時如果當前不是即時彈窗模式將重新創(chuàng)建會話5ddc0fe改善登錄會話過期后的恢復體驗core-components為 OAuth 請求對話框新增可選message字段便于向用戶展示友好提示f6ffea6登錄與登出新增signIn/signOut分析事件aa3b054。后端與基礎設施backend-defaults0.11.1修復了 GitLab readURL 請求的訪問令牌處理以及 GitLab 用戶令牌與集成令牌被合并的問題e0189b8、d1e4a6dsearch-backend2.0.4不再在 API 響應中返回后端 SQL 查詢字符串錯誤只記錄日志、對用戶返回空響應69fb975避免信息泄露auth-backend將userInfo數據庫從tokenIssuer中拆出UserInfo不再存儲exp改用數據庫中的created_at/updated_ate88cb70config/config-loader放寬了合法配置鍵的要求ff23618plugin-app的AppRoutes擴展移除尾部斜杠保證嵌套路由行為正確09f5e36yarn-plugin-backstage修復了backstage:^協(xié)議安裝新依賴失敗的問題d6084b8。升級建議與檢查清單結合倉庫內的 versioning-policy 與官方升級工具指引建議按以下順序執(zhí)行升級檢查配置全文搜索app-config.yaml中catalog.stitchingStrategy刪除mode: immediate、catalog.orphanStrategy、catalog.orphanProviderStrategy、catalog.useUrlReadersSearch移除、disableRelationsCompatiblity改為enableRelationsCompatibility等鍵檢查自定義 UrlReaderService確認search方法能同時處理具體 URL 與通配符搜索模式參考backstage/backend-defaults內置實現檢查 Scaffolder 權限策略將scaffolder.task.read/scaffolder.task.cancel按 Resource Permission 處理并確認重試任務的新權限組合readcreate檢查自定義樣式若使用 Canon將--canon前綴與.canon-類名替換為--bui/.bui-并遷移受 React Aria 影響的組件 props回歸測試重點模塊Catalog 的縫補與孤兒清理、Scaffolder 任務讀取/取消/重試、通知默認設置與郵件處理器、GitLab 集成。官方發(fā)布的changesets均可在 docs/releases 目錄下對照查閱升級后建議運行backstage-cli repo fix或對應 lint/test 流程確認依賴與代碼兼容性?！久赓M下載鏈接】backstageBackstage is an open framework for building developer portals項目地址: https://gitcode.com/GitHub_Trending/ba/backstage創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考