Backstage Actions Service 實(shí)戰(zhàn)指南Action 的發(fā)現(xiàn)、過(guò)濾、鑒權(quán)與遠(yuǎn)程調(diào)用原理【免費(fèi)下載鏈接】backstageBackstage is an open framework for building developer portals項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ba/backstageActions Service 是 Backstage 后端系統(tǒng)Backend System中的一項(xiàng)核心服務(wù)alpha 階段它為后端插件提供了一套統(tǒng)一的接口用于**發(fā)現(xiàn)list與執(zhí)行invoke**已注冊(cè)的 Action。本文圍繞docs/backend-system/core-services/actions.md展開(kāi)結(jié)合倉(cāng)庫(kù)中 ActionsService 接口定義、DefaultActionsService 實(shí)現(xiàn) 與 actionsServiceFactory 測(cè)試講清 Action 的 ID 規(guī)范、pluginSources與 include/exclude 過(guò)濾配置、權(quán)限集成、Secrets 傳遞機(jī)制以及它在多插件、分布式場(chǎng)景下的底層遠(yuǎn)程調(diào)用鏈路。讀完你可以在自己的插件中安全、精準(zhǔn)地列出并執(zhí)行 Action并掌握如何通過(guò)配置對(duì)暴露的 Action 做細(xì)粒度治理。Actions Service 是什么Actions Service 是 Backstage 后端插件中用于發(fā)現(xiàn)與執(zhí)行已注冊(cè) Action的核心服務(wù)。它承擔(dān)的是消費(fèi)方 API角色Action 由插件通過(guò) Actions Registry Service 注冊(cè)而本服務(wù)負(fù)責(zé)把這些 Action 暴露給其他插件與調(diào)用方并且自帶身份認(rèn)證credentials與輸入校驗(yàn)?zāi)芰?。?ActionsService 接口定義 中服務(wù)只提供兩個(gè)方法list({ credentials })返回全部可用 Action 及其完整元數(shù)據(jù)ActionsServiceAction[]包括聲明的輸入/輸出/Secrets JSON Schema 與行為屬性attributesinvoke({ id, input, secrets, credentials })按 Action ID 執(zhí)行指定的 Action返回{ output }。兩者都需要傳入BackstageCredentials用于認(rèn)證與鑒權(quán)。接口定義中可以看到每個(gè) Action 的元數(shù)據(jù)結(jié)構(gòu)ActionsServiceActionexport type ActionsServiceAction { id: string; pluginId: string; name: string; title: string; description: string; schema: { input: JSONSchema7; output: JSONSchema7; secrets?: JSONSchema7; }; examples?: Array{ title: string; description?: string; input: JsonObject; output?: JsonObject; }; attributes: { readOnly: boolean; destructive: boolean; idempotent: boolean; }; };注意schema中的input/output/secrets在注冊(cè)時(shí)使用 Zod schema 描述但在經(jīng)服務(wù)對(duì)外暴露時(shí)統(tǒng)一轉(zhuǎn)換為 JSON Schemadraft-07格式這一點(diǎn)在 actionsServiceFactory.test.ts 的集成測(cè)試斷言中可以看到具體形態(tài)。Action 的 ID 規(guī)范Action 使用全局唯一的 ID 標(biāo)識(shí)格式固定為pluginId:actionName所有 Action ID 都以注冊(cè)它的插件 ID為前綴例如catalog插件注冊(cè)的fetch-user-info其完整 ID 為catalog:fetch-user-info使用actionsRegistryServiceMock測(cè)試 Mock注冊(cè)時(shí)插件前綴固定為test:這種命名約定保證了 Action 名稱在全部插件之間全局唯一同時(shí)讓每個(gè) Action 的歸屬插件一目了然。從實(shí)現(xiàn)看ID 前綴還承擔(dān)了路由定位職責(zé)DefaultActionsService.invoke()會(huì)通過(guò)pluginIdFromActionId()解析出:之前的插件 IDDefaultActionsService.ts然后只向該插件發(fā)起遠(yuǎn)程調(diào)用如果 ID 中沒(méi)有:會(huì)直接拋出Invalid action id錯(cuò)誤。配置 Actions ServiceActions Service 的默認(rèn)實(shí)現(xiàn)DefaultActionsService通過(guò)createServiceFactory裝配依賴discovery、rootConfig、logger、auth四個(gè)核心服務(wù)見(jiàn) actionsServiceFactory.ts并讀取backend.actions配置段。以下配置都在app-config.yaml的backend.actions下完成。按插件限制 Action 來(lái)源pluginSourcespluginSources配置用于限制哪些插件的 Action 會(huì)被納入發(fā)現(xiàn)范圍backend: actions: pluginSources: - catalog實(shí)現(xiàn)上list()會(huì)讀取backend.actions.pluginSources字符串?dāng)?shù)組未配置時(shí)默認(rèn)為空數(shù)組然后對(duì)每個(gè)來(lái)源插件發(fā)起 HTTP 請(qǐng)求獲取其 Action 列表DefaultActionsService.ts。某插件請(qǐng)求失敗時(shí)只會(huì)記錄warn日志并返回空數(shù)組不會(huì)讓整個(gè)list()失敗——這一優(yōu)雅降級(jí)行為在測(cè)試should list all plugins in config to find actions and handle failures gracefully中有明確覆蓋actionsServiceFactory.test.ts。用 include / exclude 過(guò)濾 Action除了插件級(jí)限制Actions Service 還支持基于include包含與exclude排除規(guī)則的細(xì)粒度過(guò)濾精確控制 Backstage 實(shí)例中暴露或可運(yùn)行的 Action。過(guò)濾維度有兩個(gè)id使用 glob 模式如catalog:*、*:fetch-*attributes按行為屬性過(guò)濾可取destructive破壞性、readOnly只讀、idempotent冪等三個(gè)布爾值。規(guī)則求值邏輯來(lái)自文檔原文并在 applyFilters 實(shí)現(xiàn)中得到印證單條規(guī)則內(nèi)部id與attributes之間是AND關(guān)系matchesRule()中id 不匹配直接返回 falseattributes 有任一不一致也返回 false同一個(gè)include或exclude數(shù)組內(nèi)的多條規(guī)則之間是OR關(guān)系exclude優(yōu)先于include且始終生效先判 exclude命中即剔除無(wú) include 規(guī)則時(shí)默認(rèn)全量放行有 include 規(guī)則時(shí)至少命中一條才保留。包含指定 Actionbackend: actions: filter: include: # Include all catalog actions that are non-destructive - id: catalog:* attributes: destructive: false # OR include all fetch actions from any plugin - id: *:fetch-*排除指定 Actionbackend: actions: filter: exclude: # Exclude all delete actions from any plugin - id: *:delete-* # OR exclude all destructive actions - attributes: destructive: true上述語(yǔ)義在 actionsServiceFactory.test.ts 中有成體系的測(cè)試覆蓋可作為理解源碼級(jí)真相的參考should filter actions based on include patterns第 118-190 行include 只保留my-plugin:*should filter actions based on exclude patterns第 192-242 行exclude*:delete-*后只保留get-entityshould have exclude take precedence over include第 244-295 行即使命中 include被 exclude 命中也會(huì)被剔除should always apply exclude rules even when action matches include第 297-363 行注釋明確寫(xiě)到 exclude is checked FIRST and always wins——destructive 的 action 即便匹配my-plugin:*也會(huì)被過(guò)濾should filter actions based on attribute constraints第 365-431 行按attributes.readOnly: true過(guò)濾should combine pattern and attribute filtering with AND logic第 433-525 行id與attributes同時(shí)滿足才保留should return all actions when no filter config is provided第 527-578 行未配置 filter 時(shí)返回全部。實(shí)現(xiàn)細(xì)節(jié)上glob 匹配使用minimatch庫(kù)規(guī)則解析見(jiàn) parseFilterRulesid編譯為Minimatch實(shí)例attributes只讀取destructive、readOnly、idempotent三個(gè)鍵。與權(quán)限框架集成Permissions注冊(cè)時(shí)帶visibilityPermission字段的 Action 會(huì)自動(dòng)接入權(quán)限框架列出時(shí)被權(quán)限策略permission policy拒絕的 Action 會(huì)從list()結(jié)果中過(guò)濾掉執(zhí)行時(shí)對(duì)被拒絕的 Action 調(diào)用invoke()返回404 Not Found錯(cuò)誤——與被刪除的 Action 表現(xiàn)一致避免暴露存在性信息。關(guān)于如何在 Action 上配置權(quán)限例如用createPermission定義my-plugin.actions.deleteEntity并賦值給visibilityPermission參見(jiàn) Actions Registry 的 Permissions 文檔。使用 Actions Service 列出 Actionlist()返回的每個(gè) Action 都帶有id、title、description、attributes以及可選的schema.input/schema.output/schema.secrets。下面是一個(gè)完整的列出示例沿用文檔原文可直接作為插件代碼參考import { ActionsService } from backstage/backend-plugin-api; export async function listAvailableActions( actionsService: ActionsService, credentials: BackstageCredentials, ) { try { const { actions } await actionsService.list({ credentials }); console.log(Found ${actions.length} available actions:); actions.forEach(action { console.log(- ${action.id}: ${action.title}); console.log( Description: ${action.description}); console.log( Attributes: ${JSON.stringify(action.attributes)}); if (action.schema.input) { console.log( Input Schema: ${JSON.stringify(action.schema.input, null, 2)}, ); } }); return actions; } catch (error) { console.error(Failed to list actions:, error); throw error; } }注意credentials參數(shù)服務(wù)內(nèi)部會(huì)用auth.getPluginRequestToken({ onBehalfOf: credentials, targetPluginId })換取調(diào)用目標(biāo)插件的服務(wù)令牌再攜帶Authorization: Bearer token請(qǐng)求遠(yuǎn)程插件DefaultActionsService.ts。因此調(diào)用方必須提供代表當(dāng)前用戶或服務(wù)的憑證不能匿名調(diào)用。執(zhí)行一個(gè) Actioninvoke()以id定位 Action并傳入input可選與secrets可選import { ActionsService } from backstage/backend-plugin-api; export async function executeAction( actionsService: ActionsService, actionId: string, input: JsonObject, credentials: BackstageCredentials, secrets?: JsonObject, ) { try { const { output } await actionsService.invoke({ id: actionId, input, secrets, credentials, }); console.log(Action ${actionId} executed successfully); console.log(Output:, JSON.stringify(output, null, 2)); return output; } catch (error) { console.error(Failed to execute action ${actionId}:, error); throw error; } } // Example usage async function fetchUserInfo( actionsService: ActionsService, credentials: BackstageCredentials, ) { const output await executeAction( actionsService, catalog:fetch-user-info, // Note: Action ID includes plugin prefix { userRef: user:default/john.doe, includeGroups: true, }, credentials, ); return output; }從實(shí)現(xiàn)看invoke()會(huì)根據(jù)目標(biāo)插件 ID 把請(qǐng)求 POST 到該插件的/.backstage/actions/v1/actions/編碼后的完整ID/invoke端點(diǎn)DefaultActionsService.ts。測(cè)試should invoke the action and return the output與集成測(cè)試/api/test-harness/invoke分別驗(yàn)證了客戶端 HTTP 調(diào)用與服務(wù)端全鏈路返回{ output: { ok: true, string: hello world } }的行為actionsServiceFactory.test.ts。錯(cuò)誤語(yǔ)義invoke()對(duì) HTTP 非 2xx 響應(yīng)會(huì)統(tǒng)一轉(zhuǎn)為ResponseError拋出測(cè)試覆蓋了兩類典型場(chǎng)景目標(biāo) Action 不存在或權(quán)限被拒 →404should throw a 404 if the action does not exist輸入校驗(yàn)失敗 →400should throw a 400 if the action returns an invalid input。攜帶 Secrets 執(zhí)行 Action部分 Action 會(huì)為外部憑證如 GitHub Token、個(gè)人訪問(wèn)令牌等不屬于 Backstage 自身認(rèn)證體系的敏感值聲明secretsschema。你可以通過(guò)list()返回元數(shù)據(jù)中的schema.secrets判斷某 Action 是否需要 Secrets需要時(shí)在調(diào)用時(shí)一并傳入const { actions } await actionsService.list({ credentials }); const action actions.find(a a.id my-plugin:create-issue); if (action?.schema.secrets) { // This action needs secrets — collect them from the user first const { output } await actionsService.invoke({ id: action.id, input: { repo: backstage/backstage, title: My issue }, secrets: { githubToken: collectedToken }, credentials, }); }兩條硬性約束違反都會(huì)得到InputError向未聲明secrets schema 的 Action 傳入 secrets → 拒絕遺漏必需的 secrets → 拒絕。實(shí)現(xiàn)層面invoke()在傳入secrets時(shí)會(huì)自動(dòng)切換到v2調(diào)用協(xié)議請(qǐng)求體為{ input, secrets }未傳 secrets 時(shí)保持v1協(xié)議請(qǐng)求體為input本身并在代碼中標(biāo)注了待所有 registry 升級(jí)后移除 v1 回退的棄用說(shuō)明DefaultActionsService.ts服務(wù)端則由 Actions Registry 在/.backstage/actions/v1/actions/:actionId/invoke舊與/.backstage/actions/v2/actions/:actionId/invoke新支持 wrapped secrets兩條路由上分別處理。關(guān)于如何在注冊(cè)端聲明 secrets schemaschema.secrets: z z.object({...})參見(jiàn) Actions Registry 的 Secrets 文檔。特別地secrets 與 input 分離的設(shè)計(jì)保證了它們永遠(yuǎn)不會(huì)出現(xiàn)在暴露為 MCP 工具的 tool definitions 或 LLM 上下文中。源碼視角一次 list/invoke 的完整鏈路把文檔描述與實(shí)現(xiàn)代碼對(duì)照可以還原 Actions Service 的完整工作鏈路注冊(cè)端插件在registerInit中注入actionsRegistryServiceRef服務(wù) ref ID 為alpha.core.actionsRegistry見(jiàn) refs.ts調(diào)用actionsRegistry.register({...})注冊(cè) Action并掛載/.backstage/actions/v1/actions與 invoke 路由見(jiàn) DefaultActionsRegistryService.ts 中的路由注冊(cè)重復(fù)注冊(cè)同一 ID 會(huì)拋出Action with id ... is already registered消費(fèi)端調(diào)用方注入actionsServiceRefref ID 為alpha.core.actions見(jiàn) refs.ts調(diào)用list()/invoke()路由與認(rèn)證DefaultActionsService通過(guò)discovery.getBaseUrl(pluginId)定位目標(biāo)插件用auth.getPluginRequestToken({ onBehalfOf: credentials, targetPluginId })換取服務(wù)令牌向{baseUrl}/.backstage/actions/v1/actionslist或/.backstage/actions/v1|v2/actions/{id}/invokeinvoke發(fā)起帶 Bearer 令牌的請(qǐng)求過(guò)濾與返回list()匯總各插件返回的 Action 后經(jīng)applyFilters()應(yīng)用 include/exclude 規(guī)則exclude 優(yōu)先、include 缺省放行最終返回過(guò)濾后的列表。這套設(shè)計(jì)使 Actions Service 成為一個(gè)分布式的、跨插件的遠(yuǎn)程調(diào)用門(mén)面Action 注冊(cè)在各自插件進(jìn)程內(nèi)但可以通過(guò)統(tǒng)一的服務(wù)接口被任意插件發(fā)現(xiàn)和調(diào)用且天然帶認(rèn)證、鑒權(quán)與輸入校驗(yàn)。最佳實(shí)踐與錯(cuò)誤處理指引Action 設(shè)計(jì)規(guī)范命名、schema 設(shè)計(jì)等最佳實(shí)踐見(jiàn) Actions Registry 的 Best Practices——Action 名應(yīng)使用 kebab-case、以動(dòng)詞開(kāi)頭如fetch、create、delete、避免在名稱中重復(fù)插件名錯(cuò)誤類型Action 內(nèi)部應(yīng)拋出backstage/errors中的錯(cuò)誤類如NotFoundError、NotAllowedError這些錯(cuò)誤能被 Actions Service 及 MCP Actions Backend 等消費(fèi)方識(shí)別并透?jìng)鹘o調(diào)用者未被識(shí)別的錯(cuò)誤類型可能退化為通用的500 Server Error。小結(jié)Actions Service 是 Backstage 后端系統(tǒng)中連接Action 注冊(cè)方與Action 消費(fèi)方的橋梁pluginSources劃定插件邊界include/exclude 過(guò)濾提供基于 IDglob與行為屬性的細(xì)粒度治理visibilityPermission打通權(quán)限框架secrets 機(jī)制安全傳遞外部憑證而底層基于 Discovery Auth 的遠(yuǎn)程調(diào)用讓 Action 可以跨插件分布式執(zhí)行。配合 Actions Registry Service 一起使用即可在 Backstage 中構(gòu)建一套可發(fā)現(xiàn)、可治理、可安全執(zhí)行的可復(fù)用 Action 生態(tài)?！久赓M(fèi)下載鏈接】backstageBackstage is an open framework for building developer portals項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ba/backstage創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考