Backstage CLI Actions 模块使用指南从插件源码发现、列出到执行分布式 Action【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageBackstage 的backstage/cli-module-actions是一个面向命令行场景的 CLI 模块它允许开发者在不启动完整前端的情况下直接通过终端与运行在 Backstage 实例中的插件 ActionScaffolder Action 的分布式执行能力进行交互发现插件暴露的 Action、查看其输入 schema、并以参数形式调用执行。本文以仓库中的 cli-report.md 为骨架结合该模块的源码实现packages/cli-module-actions/src完整讲解其命令树、每个子命令的用法与参数、底层认证与 HTTP 调用机制以及 JSON Schema 到命令行参数自动转换的原理。模块定位与命令树总览backstage/cli-module-actions的包描述为 CLI module for executing distributed actions角色类型为cli-module见 package.json版本号以仓库当前内容为准0.1.3。它通过createCliModule注册到 Backstage CLI 体系入口实现在 src/index.ts注册了 5 个叶子命令命令路径说明来自源码注册描述actions listList available actions from configured plugin sourcesactions executeExecute an actionactions sources addAdd a plugin source for action discoveryactions sources listList configured plugin sourcesactions sources removeRemove a plugin sourceCLI 报告cli-report.md展示了该模块的完整命令树backstage-cli-module-actions ├── -V, --version ├── -h, --help └── actions ├── execute [--instance string] [-h] action-id ├── list [--instance string] [-h] └── sources ├── add plugin-ids... ├── list └── remove plugin-ids...顶层命令只有actions和help所有实际能力都收敛在actions下形成了源码管理sources→ 列表查看list→ 执行execute的完整工作流。核心概念Action 与插件源码Plugin Source在使用命令之前需要理解两个核心概念Action由插件暴露的、可远程调用的操作其 ID 采用pluginId:actionName的格式。从 ActionsClient.ts 的extractPluginId实现可以看出actionId必须以冒号分隔前半部分是插件 IDfunction extractPluginId(actionId: string): string { const colonIndex actionId.indexOf(:); if (colonIndex -1) { throw new Error( Invalid action ID ${actionId}. Expected format pluginId:actionName., ); } return actionId.substring(0, colonIndex); }插件源码Plugin Source一个已配置的插件 ID表示从哪个插件发现 Action。插件源码以字符串数组形式持久化在 CLI 认证元数据中schema 定义为z.array(z.string()).default([])见 pluginSources.ts即默认空数组未配置时任何 Action 相关操作都无法进行。管理插件源码actions sources 子命令sources addactions sources add plugin-ids...用于添加一个或多个插件源码。命令接受多个插件 ID 作为位置参数Usage: backstage-cli-module-actions actions sources add [flags...] plugin-ids... Options: -h, --help从 sourcesAdd.ts 的实现看它的执行逻辑是通过CliAuth.create()创建 CLI 认证上下文读取现有元数据pluginSources并用 zod schema 解析逐个检查插件 ID已存在的被跳过并提示Plugin source id is already configured.新增的合并写回输出Added plugin source(s): ...。示例# 添加单个插件源码 backstage-cli-module-actions actions sources add scaffolder # 一次添加多个 backstage-cli-module-actions actions sources add catalog kubernetessources listactions sources list列出当前已配置的全部插件源码无额外参数Usage: backstage-cli-module-actions actions sources list [flags...] Options: -h, --help实现sourcesList.ts会读取元数据并逐行输出未配置任何源码时向 stderr 输出No plugin sources configured.。sources removeactions sources remove plugin-ids...删除一个或多个插件源码Usage: backstage-cli-module-actions actions sources remove [flags...] plugin-ids... Options: -h, --help实现sourcesRemove.ts与add对称未配置的 ID 被跳过并提示Plugin source id is not configured.已存在的 ID 从数组中过滤后写回输出Removed plugin source(s): ...。这三个命令通过CliAuth.getMetadata/setMetadata读写pluginSources实现配置即持久化后续的list、execute都会复用这份配置。发现可用 Actionactions listactions list用于从所有已配置的插件源码中发现可用的 ActionUsage: backstage-cli-module-actions actions list [flags...] Options: --instance string -h, --help参数说明参数类型说明--instance string可选指定要使用的 Backstage 实例名称不传时使用默认实例-h, --help可选显示帮助底层流程list.ts调用resolveAuth(instanceFlag)解析认证与配置——获取访问令牌、插件源码列表与实例基础 URL见 resolveAuth.ts若插件源码为空输出提示并退出No plugin sources configured. Run actions sources add plugin-id to add one.构造ActionsClient对每个插件源码并发调用其 Action 列表接口30 秒超时按插件分组格式化输出若所有组都为空则输出No actions found.。示例# 列出默认实例上所有已配置插件的 Action backstage-cli-module-actions actions list # 指定实例 backstage-cli-module-actions actions list --instance my-backstage执行 Actionactions executeactions execute是模块的核心命令用于实际调用某个 ActionUsage: backstage-cli-module-actions actions execute [flags...] action-id Options: --instance string -h, --help固定参数参数类型说明action-id必填形如pluginId:actionName的 Action ID--instance string可选指定 Backstage 实例名称-h, --help可选显示帮助若提供了 action-id会尝试从远端拉取该 Action 的输入 schema 并展示带参数的动态帮助动态参数JSON Schema 自动转命令行标志actions execute最强大的特性在于不需要预先记忆参数执行时它会先从远端获取该 Action 的输入 JSON Schema再通过schemaToFlagsschemaToFlags.ts把 schema 的properties动态转换为命令行 flag。转换规则如下type: string→ 字符串 flagStringtype: number或type: integer→ 数字 flagNumbertype: boolean→ 布尔 flagBooleantype: object、type: array或包含anyOf/oneOf/allOf的复杂类型 → 标记为复杂键以字符串 flag 接收运行时用JSON.parse解析为对象/数组见 execute.ts 中complexKeys的处理逻辑解析失败会抛出Invalid JSON for --key. Expected a JSON string.schema 中的description会拼进 flag 帮助文本enum取值会以[值1, 值2]形式附加到描述中required中的字段会标注(required)default会作为 flag 的默认值。执行流程execute.ts解析--instance与首个非 flag 位置参数作为action-id若请求--help有 action-id 时先尝试拉取该 Action 的 schema 渲染动态帮助失败则回退到通用帮助无 action-id 时直接显示通用帮助缺少 action-id 时抛出Action ID is required通过listForPlugin(actionId)验证 Action 是否存在不存在则抛出Action id not found. Run actions list to see available actions.将输入 schema 转为 flags 后解析命令行参数过滤掉--instance与未传值项复杂键做 JSON 解析POST 调用执行接口将返回的output以格式化 JSON 输出到 stdout。示例以scaffolder插件下某个假设的 Action 为例# 先查看该 Action 的动态帮助 backstage-cli-module-actions actions execute scaffolder:some-action --help # 执行字符串、数字、布尔与 JSON 对象参数混用 backstage-cli-module-actions actions execute scaffolder:some-action \ --name my-component \ --replicas 3 \ --dry-run \ --labels {team:platform,env:dev}底层实现认证与会话所有需要访问实例的命令list、execute都依赖resolveAuthresolveAuth.tsconst auth await CliAuth.create({ instanceName: instanceFlag }); const accessToken await auth.getAccessToken(); const pluginSources pluginSourcesSchema.parse( await auth.getMetadata(pluginSources), );它统一完成了三件事获取访问令牌通过CliAuth得到 Bearer Token用于后续请求的Authorization头读取插件源码配置与sources子命令共用同一份pluginSources元数据解析实例地址auth.getBaseUrl()决定请求发往哪个 Backstage 实例--instance标志仅在这里消费。底层实现HTTP 协议与端点约定ActionsClientActionsClient.ts封装了与插件后端的通信请求均为 JSON 形式统一携带Authorization: Bearer token并使用AbortSignal.timeout(30_000)设置 30 秒超时列出某插件的 ActionGET /api/pluginId/.backstage/actions/v1/actions响应体为{ actions: ActionDef[] }其中ActionDef含id、name、可选的title/description以及schema.input/schema.output两段 JSON Schema执行某 ActionPOST /api/pluginId/.backstage/actions/v1/actions/actionId/invoke请求体为输入参数对象默认{}响应体为{ output: unknown }。list命令对多个插件源码采用Promise.all并发拉取并按插件分组展示execute则先从目标插件的列表中查找指定actionId确认存在后才发起调用。使用前提与限制必须配置插件源码actions list与actions execute都依赖pluginSources配置首次使用请先执行actions sources add plugin-id插件后端需运行CLI 通过 HTTP 直接访问 Backstage 实例的/api/pluginId/.backstage/actions/v1/actions端点因此目标插件必须已部署且启用了 Action 暴露能力且 CLI 与实例之间网络可达Action ID 格式固定必须为pluginId:actionName缺失冒号会被ActionsClient判为非法 ID参数传递语义对象/数组类型的参数以 JSON 字符串形式传入CLI 端负责解析解析失败会直接报错认证所有请求都需要有效的访问令牌令牌通过CliAuth按实例获取多实例场景下请正确使用--instance。以上命令树、参数与端点约定均可在 cli-report.md 及其对应的 src 源码、测试用例如 execute.test.ts、sourcesAdd.test.ts中得到验证。据此你可以把 Backstage 插件的 Action 能力直接接入 CI 脚本、本地调试流程或任意自动化工具链。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Backstage CLI Actions 模块使用指南：从插件源码发现、列出到执行分布式 Action
Backstage CLI Actions 模块使用指南从插件源码发现、列出到执行分布式 Action【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageBackstage 的backstage/cli-module-actions是一个面向命令行场景的 CLI 模块它允许开发者在不启动完整前端的情况下直接通过终端与运行在 Backstage 实例中的插件 ActionScaffolder Action 的分布式执行能力进行交互发现插件暴露的 Action、查看其输入 schema、并以参数形式调用执行。本文以仓库中的 cli-report.md 为骨架结合该模块的源码实现packages/cli-module-actions/src完整讲解其命令树、每个子命令的用法与参数、底层认证与 HTTP 调用机制以及 JSON Schema 到命令行参数自动转换的原理。模块定位与命令树总览backstage/cli-module-actions的包描述为 CLI module for executing distributed actions角色类型为cli-module见 package.json版本号以仓库当前内容为准0.1.3。它通过createCliModule注册到 Backstage CLI 体系入口实现在 src/index.ts注册了 5 个叶子命令命令路径说明来自源码注册描述actions listList available actions from configured plugin sourcesactions executeExecute an actionactions sources addAdd a plugin source for action discoveryactions sources listList configured plugin sourcesactions sources removeRemove a plugin sourceCLI 报告cli-report.md展示了该模块的完整命令树backstage-cli-module-actions ├── -V, --version ├── -h, --help └── actions ├── execute [--instance string] [-h] action-id ├── list [--instance string] [-h] └── sources ├── add plugin-ids... ├── list └── remove plugin-ids...顶层命令只有actions和help所有实际能力都收敛在actions下形成了源码管理sources→ 列表查看list→ 执行execute的完整工作流。核心概念Action 与插件源码Plugin Source在使用命令之前需要理解两个核心概念Action由插件暴露的、可远程调用的操作其 ID 采用pluginId:actionName的格式。从 ActionsClient.ts 的extractPluginId实现可以看出actionId必须以冒号分隔前半部分是插件 IDfunction extractPluginId(actionId: string): string { const colonIndex actionId.indexOf(:); if (colonIndex -1) { throw new Error( Invalid action ID ${actionId}. Expected format pluginId:actionName., ); } return actionId.substring(0, colonIndex); }插件源码Plugin Source一个已配置的插件 ID表示从哪个插件发现 Action。插件源码以字符串数组形式持久化在 CLI 认证元数据中schema 定义为z.array(z.string()).default([])见 pluginSources.ts即默认空数组未配置时任何 Action 相关操作都无法进行。管理插件源码actions sources 子命令sources addactions sources add plugin-ids...用于添加一个或多个插件源码。命令接受多个插件 ID 作为位置参数Usage: backstage-cli-module-actions actions sources add [flags...] plugin-ids... Options: -h, --help从 sourcesAdd.ts 的实现看它的执行逻辑是通过CliAuth.create()创建 CLI 认证上下文读取现有元数据pluginSources并用 zod schema 解析逐个检查插件 ID已存在的被跳过并提示Plugin source id is already configured.新增的合并写回输出Added plugin source(s): ...。示例# 添加单个插件源码 backstage-cli-module-actions actions sources add scaffolder # 一次添加多个 backstage-cli-module-actions actions sources add catalog kubernetessources listactions sources list列出当前已配置的全部插件源码无额外参数Usage: backstage-cli-module-actions actions sources list [flags...] Options: -h, --help实现sourcesList.ts会读取元数据并逐行输出未配置任何源码时向 stderr 输出No plugin sources configured.。sources removeactions sources remove plugin-ids...删除一个或多个插件源码Usage: backstage-cli-module-actions actions sources remove [flags...] plugin-ids... Options: -h, --help实现sourcesRemove.ts与add对称未配置的 ID 被跳过并提示Plugin source id is not configured.已存在的 ID 从数组中过滤后写回输出Removed plugin source(s): ...。这三个命令通过CliAuth.getMetadata/setMetadata读写pluginSources实现配置即持久化后续的list、execute都会复用这份配置。发现可用 Actionactions listactions list用于从所有已配置的插件源码中发现可用的 ActionUsage: backstage-cli-module-actions actions list [flags...] Options: --instance string -h, --help参数说明参数类型说明--instance string可选指定要使用的 Backstage 实例名称不传时使用默认实例-h, --help可选显示帮助底层流程list.ts调用resolveAuth(instanceFlag)解析认证与配置——获取访问令牌、插件源码列表与实例基础 URL见 resolveAuth.ts若插件源码为空输出提示并退出No plugin sources configured. Run actions sources add plugin-id to add one.构造ActionsClient对每个插件源码并发调用其 Action 列表接口30 秒超时按插件分组格式化输出若所有组都为空则输出No actions found.。示例# 列出默认实例上所有已配置插件的 Action backstage-cli-module-actions actions list # 指定实例 backstage-cli-module-actions actions list --instance my-backstage执行 Actionactions executeactions execute是模块的核心命令用于实际调用某个 ActionUsage: backstage-cli-module-actions actions execute [flags...] action-id Options: --instance string -h, --help固定参数参数类型说明action-id必填形如pluginId:actionName的 Action ID--instance string可选指定 Backstage 实例名称-h, --help可选显示帮助若提供了 action-id会尝试从远端拉取该 Action 的输入 schema 并展示带参数的动态帮助动态参数JSON Schema 自动转命令行标志actions execute最强大的特性在于不需要预先记忆参数执行时它会先从远端获取该 Action 的输入 JSON Schema再通过schemaToFlagsschemaToFlags.ts把 schema 的properties动态转换为命令行 flag。转换规则如下type: string→ 字符串 flagStringtype: number或type: integer→ 数字 flagNumbertype: boolean→ 布尔 flagBooleantype: object、type: array或包含anyOf/oneOf/allOf的复杂类型 → 标记为复杂键以字符串 flag 接收运行时用JSON.parse解析为对象/数组见 execute.ts 中complexKeys的处理逻辑解析失败会抛出Invalid JSON for --key. Expected a JSON string.schema 中的description会拼进 flag 帮助文本enum取值会以[值1, 值2]形式附加到描述中required中的字段会标注(required)default会作为 flag 的默认值。执行流程execute.ts解析--instance与首个非 flag 位置参数作为action-id若请求--help有 action-id 时先尝试拉取该 Action 的 schema 渲染动态帮助失败则回退到通用帮助无 action-id 时直接显示通用帮助缺少 action-id 时抛出Action ID is required通过listForPlugin(actionId)验证 Action 是否存在不存在则抛出Action id not found. Run actions list to see available actions.将输入 schema 转为 flags 后解析命令行参数过滤掉--instance与未传值项复杂键做 JSON 解析POST 调用执行接口将返回的output以格式化 JSON 输出到 stdout。示例以scaffolder插件下某个假设的 Action 为例# 先查看该 Action 的动态帮助 backstage-cli-module-actions actions execute scaffolder:some-action --help # 执行字符串、数字、布尔与 JSON 对象参数混用 backstage-cli-module-actions actions execute scaffolder:some-action \ --name my-component \ --replicas 3 \ --dry-run \ --labels {team:platform,env:dev}底层实现认证与会话所有需要访问实例的命令list、execute都依赖resolveAuthresolveAuth.tsconst auth await CliAuth.create({ instanceName: instanceFlag }); const accessToken await auth.getAccessToken(); const pluginSources pluginSourcesSchema.parse( await auth.getMetadata(pluginSources), );它统一完成了三件事获取访问令牌通过CliAuth得到 Bearer Token用于后续请求的Authorization头读取插件源码配置与sources子命令共用同一份pluginSources元数据解析实例地址auth.getBaseUrl()决定请求发往哪个 Backstage 实例--instance标志仅在这里消费。底层实现HTTP 协议与端点约定ActionsClientActionsClient.ts封装了与插件后端的通信请求均为 JSON 形式统一携带Authorization: Bearer token并使用AbortSignal.timeout(30_000)设置 30 秒超时列出某插件的 ActionGET /api/pluginId/.backstage/actions/v1/actions响应体为{ actions: ActionDef[] }其中ActionDef含id、name、可选的title/description以及schema.input/schema.output两段 JSON Schema执行某 ActionPOST /api/pluginId/.backstage/actions/v1/actions/actionId/invoke请求体为输入参数对象默认{}响应体为{ output: unknown }。list命令对多个插件源码采用Promise.all并发拉取并按插件分组展示execute则先从目标插件的列表中查找指定actionId确认存在后才发起调用。使用前提与限制必须配置插件源码actions list与actions execute都依赖pluginSources配置首次使用请先执行actions sources add plugin-id插件后端需运行CLI 通过 HTTP 直接访问 Backstage 实例的/api/pluginId/.backstage/actions/v1/actions端点因此目标插件必须已部署且启用了 Action 暴露能力且 CLI 与实例之间网络可达Action ID 格式固定必须为pluginId:actionName缺失冒号会被ActionsClient判为非法 ID参数传递语义对象/数组类型的参数以 JSON 字符串形式传入CLI 端负责解析解析失败会直接报错认证所有请求都需要有效的访问令牌令牌通过CliAuth按实例获取多实例场景下请正确使用--instance。以上命令树、参数与端点约定均可在 cli-report.md 及其对应的 src 源码、测试用例如 execute.test.ts、sourcesAdd.test.ts中得到验证。据此你可以把 Backstage 插件的 Action 能力直接接入 CI 脚本、本地调试流程或任意自动化工具链。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考