Backstage CLI Actions 模块实战指南从命令行发现与执行 Backstage Actions【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本指南围绕 Backstage 官方 CLI 的 actions 模块backstage/cli-module-actions展开系统讲解如何在不打开 Backstage Web 界面的情况下通过backstage-cli命令行发现、配置并执行插件暴露的 Actions。读完本文你将掌握actions list、actions execute、actions sources三组命令的完整用法、插件源plugin sources的管理机制以及动作输入 JSON Schema 到 CLI flag 的自动映射原理并能结合仓库源码理解其底层 HTTP 调用与凭据流转方式直接用于日常开发、自动化脚本与 CI 场景。Actions 模块是什么Actions 模块backstage/cli-module-actions是 Backstage CLI 的一个官方功能模块它让你能够在命令行中直接发现discover并运行runBackstage Actions而无需进入 Backstage 的 Web 界面。所谓 Actions是 Backstage 插件向外部暴露的可编程操作能力例如 scaffolder 插件的模板执行、catalog 插件的实体注册与校验、search 插件的全文检索等。在 docs/tooling/cli/module-actions.md 的定位中该模块服务于命令行驱动的 Backstage 操作这一场景本地脚本、CI 流水线、运维自动化都可以通过yarn backstage-cli actions ...直接驱动 Backstage 后端能力。Backstage 插件可以暴露的 Actions 全量清单参见 Well-Known Actions其中涵盖了 Auth如auth.who-am-i、Catalog如catalog.get-catalog-entity、catalog.register-entity、Notifications如notifications.get-notifications、Scaffolder如scaffolder.dry-run-template、scaffolder.execute-template、Search如search.query等多个领域的动作本文示例中的scaffolder:create-component即属此列。从仓库源码看该模块的入口与命令实现位于 packages/cli-module-actions/src/commands/核心客户端与工具逻辑位于 packages/cli-module-actions/src/lib/具体结构为commands/list.tsactions list命令实现commands/execute.tsactions execute命令实现commands/sourcesAdd.ts、sourcesList.ts、sourcesRemove.tsactions sources子命令实现lib/ActionsClient.ts与 Backstage 后端 Actions HTTP 接口通信的客户端lib/schemaToFlags.ts将动作输入 JSON Schema 映射为 CLI flag 的核心逻辑lib/resolveAuth.ts解析登录凭据、实例与插件源元数据。前置条件先认证再操作使用 actions 命令之前必须先用 auth 模块登录 Backstage 实例。Auth 模块backstage/cli-module-auth通过 OAuth 2.0 with PKCE 获取访问令牌actions 命令会复用本地存储的这些凭据与后端通信具体机制见 Auth 模块文档。登录命令示例yarn backstage-cli auth login --backendUrl https://backstage.example.com --instance production登录后actions 命令默认针对当前选中的实例selected instance工作。如果你登录了多个实例可以通过--instance name指定目标实例。实例名是你在登录时为每个实例指定的短标签例如production如果不指定CLI 会从后端 URL 的主机名推导例如backstage.example.com实例名的详细规则同样参见 Instance Names。--instance是所有 actions 命令actions list、actions execute的通用可选 flag。从 resolveAuth.ts 的源码可以看到该 flag 会被传入CliAuth.create({ instanceName })随后依次取得访问令牌auth.getAccessToken()、实例基础 URLauth.getBaseUrl()以及实例元数据中的插件源列表auth.getMetadata(pluginSources)三者共同构成一次 actions 调用的完整上下文。插件源Plugin Sources管理Actions 模块必须知道从哪些后端插件发现动作这些插件被称为插件源plugin sources它们以元数据形式存储在已认证实例上。在列出或执行动作之前需要先用actions sources系列命令管理插件源。从 resolveAuth.ts 可以看到插件源通过pluginSourcesSchema定义于 pluginSources.ts即z.array(z.string()).default([])从实例元数据的pluginSources键读取本质是一个字符串数组sourcesAdd.ts 与 sourcesRemove.ts 分别通过auth.setMetadata(pluginSources, ...)写入该数组。也就是说插件源配置持久化在 CLI 的实例元数据中与动作发现共用同一条数据通道。actions sources add添加插件源添加一个或多个用于动作发现的插件源Usage: backstage-cli actions sources add plugin-ids... Add a plugin source for action discovery如果某个插件源已经配置过该命令会跳过它并输出警告。源码中的实现逻辑是读取现有列表将未包含的新插件 ID 追加写入元数据已存在的插件 ID 进入skipped列表并打印Plugin source id is already configured.见 sourcesAdd.ts。示例# 添加单个插件源 yarn backstage-cli actions sources add scaffolder # 一次添加多个插件源 yarn backstage-cli actions sources add scaffolder catalogactions sources list列出插件源列出当前实例下所有已配置的插件源Usage: backstage-cli actions sources list List configured plugin sourcesyarn backstage-cli actions sources list如果没有配置任何插件源命令会输出No plugin sources configured.见 sourcesList.ts。actions sources remove移除插件源从当前实例移除一个或多个插件源Usage: backstage-cli actions sources remove plugin-ids... Remove a plugin source如果待移除的插件源并未配置命令会跳过它并输出警告Plugin source id is not configured.。源码中通过existing.filter(s !removed.includes(s))生成新列表并写回元数据见 sourcesRemove.ts。示例# 移除单个插件源 yarn backstage-cli actions sources remove scaffolder # 一次移除多个插件源 yarn backstage-cli actions sources remove scaffolder catalogactions list列出可用动作列出所有已配置插件源可用的动作Usage: backstage-cli actions list [options] List available actions from configured plugin sources Options: --instance name Instance name to use (defaults to the selected instance)行为细节如果没有配置任何插件源命令会输出提示引导你先运行actions sources add见 list.ts如果所有插件源都没有暴露动作输出No actions found.结果按插件 ID 分组渲染每个插件源以── pluginId分隔行作为分组头其下按 action ID 列宽对齐列出有标题的动作会附加暗淡显示的标题见 format.ts。源码实现上actions list会先解析--instanceflag然后通过resolveAuth取得访问令牌与插件源列表再为每个插件源并发发起一次 HTTP 请求Promise.all请求路径为/api/pluginId/.backstage/actions/v1/actions超时 30 秒携带Authorization: Bearer token见 ActionsClient.ts。示例# 列出所有可用动作 yarn backstage-cli actions list # 列出指定实例上的动作 yarn backstage-cli actions list --instance productionactions execute执行动作执行一个动作动作 ID 的格式为pluginId:actionNameUsage: backstage-cli actions execute [options] action-id Execute an action Options: --instance name Instance name to use (defaults to the selected instance)从输入 JSON Schema 动态生成 flags除了--instanceflag 之外该命令会根据动作的输入 JSON Schema动态生成flags。每个 schema 属性都会变成一个 CLI flag并做自动类型映射详见 schemaToFlags.tsstring属性 →Stringflagnumber与integer属性 →Numberflagboolean属性 →Booleanflag复杂类型object、array以及含anyOf/oneOf/allOf的联合类型→Stringflag接受 JSON 字符串输入。此外生成的 flag 描述会附加丰富信息复杂类型标注(JSON)存在enum枚举时列出可取值[v1, v2, ...]必填属性标注(required)有默认值时以default传入 CLI 解析器见 schemaToFlags.ts。执行时若某个 flag 的 schema 类型是复杂类型且用户以字符串传入代码会尝试JSON.parse将其还原为对象/数组解析失败则抛出Invalid JSON for --key. Expected a JSON string.见 execute.ts。最终动作输出以格式化 JSONJSON.stringify(output, null, 2)打印到标准输出。用 --help 查看动作的完整 flags使用--help或-h配合动作 ID可以查看该动作的完整 flag 集合包括渲染后的描述。此时 CLI 会先从后端拉取该动作的 schema 并渲染动态帮助见 execute.ts如果动作不存在或无法获取 schema会回退显示通用帮助并在标准错误中提示Unable to retrieve action schema: ...。帮助文本通过markedmarked-terminal将动作描述中的 Markdown 渲染为终端格式见 format.ts。yarn backstage-cli actions execute my-plugin:my-action --help示例执行带 flags 的动作yarn backstage-cli actions execute my-plugin:create-resource --name my-resource --count 3以 JSON 字符串传入复杂输入yarn backstage-cli actions execute my-plugin:configure --options {timeout: 30, retries: 3}底层调用链从 ActionsClient.ts 可以看到执行动作会向后端发送一次POST请求URL 为/api/pluginId/.backstage/actions/v1/actions/actionId/invoke请求体为组装好的输入对象同样携带 Bearer 令牌并设置 30 秒超时响应中的output字段作为结果返回。动作 ID 中的冒号分隔符由extractPluginId解析出插件 ID见 ActionsClient.ts如果动作 ID 缺少冒号会报错Invalid action ID id. Expected format pluginId:actionName.。若后端找不到对应动作命令会抛出Action id not found. Run actions list to see available actions.提示你先用actions list核对 ID见 execute.ts。完整工作流示例一个典型的使用流程如下登录 → 添加插件源 → 列表 → 查看帮助 → 执行# 1. 登录 Backstage 实例 yarn backstage-cli auth login --backendUrl https://backstage.example.com # 2. 添加插件源以发现动作 yarn backstage-cli actions sources add scaffolder # 3. 列出可用动作 yarn backstage-cli actions list # 4. 查看某个动作的帮助含动态生成的 flags yarn backstage-cli actions execute scaffolder:create-component --help # 5. 执行动作 yarn backstage-cli actions execute scaffolder:create-component --name my-service --owner team-a实践要点与注意事项先认证再操作所有 actions 命令都依赖auth login存储的本地凭据未登录时resolveAuth无法取得访问令牌命令会失败。插件源是前置配置actions list与actions execute都依赖实例元数据中的pluginSources。execute会根据动作 ID 中的插件前缀自动限定到对应插件源而list会遍历全部已配置插件源。多实例场景登录多个实例后务必使用--instance name明确目标实例否则命令作用于当前选中的实例。复杂输入传 JSONobject / array / 联合类型属性在 CLI 中以字符串形式接收务必传入合法的 JSON 字符串否则会收到明确的 JSON 解析错误。动作 ID 格式严格遵守pluginId:actionName缺失冒号、拼写错误或目标插件未安装都会导致明确的报错信息。了解可用的动作面想快速了解当前 Backstage 插件生态可执行哪些动作可对照 Well-Known Actions 与仓库中 actions-registry 相关文档 查阅。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考