Backstage 开发者门户框架全解析从软件目录到插件生态的入门指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于仓库根目录的 README-fr_FR.md项目法语版官方 README为主体骨架并结合 docs/overview/what-is-backstage.md、docs/overview/technical-overview.md 以及 Software Catalog、Software Templates、TechDocs 三大核心功能的官方文档编写。文章面向希望了解 Backstage 是什么、能做什么、如何快速上手的技术读者读完即可掌握 Backstage 的核心概念、内置功能与本地启动方法并能按图索骥进入仓库对应文档深入实践。Backstage 是什么一个构建开发者门户的开源框架README-fr_FR.md 开篇即点明项目定位Backstage 是一个用于构建开发者门户developer portal的开源框架。其核心设计思想是提供一个集中化的软件目录centralized software catalog把杂乱的微服务与基础设施重新整理出秩序让产品团队能够在不牺牲自主性的前提下快速、高效地交付代码。从诞生背景看docs/overview/background.md 记载了完整的Spotify 故事随着 Spotify 规模增长基础设施日益碎片化工程师们把大量时间花在寻找正确信息而不是编写与测试代码上——那个服务我们到底该用哪个 API大家都在用哪个框架版本这个服务没人响应归谁管文档什么都找不到。频繁的上下文切换与认知过载持续拖累工程师效率。Backstage 的解法是在全部基础设施与开发工具之上构建一层抽象层把端到端的软件开发流程集中化、简单化。用官方文档的原文来说Backstage 统一了所有基础设施工具、服务与文档创造出端到端流畅的开发环境参见 docs/overview/what-is-backstage.md 与 docs/overview/technical-overview.md 的 Purpose 小节。项目治理与状态Backstage 最初由Spotify开发随后捐赠给云原生计算基金会CNCF目前处于Incubation孵化阶段README-fr_FR.md 与 docs/overview/what-is-backstage.md 均确认这一状态。仓库根目录的 LICENSE 声明项目采用 Apache License 2.0 开源协议版权归属于 Backstage 作者README 中标注的版权区间为 2020-2026。上图是官方文档README 与 docs/features/software-catalog/index.md共同使用的软件目录概念图左侧展示了podcast-api这类服务的元数据 YAML 定义含apiVersion、kind、name、type、lifecycle、owner等字段中央是目录浏览界面右侧则是通过插件挂接的外部工具生态。开箱即用的四大核心能力README-fr_FR.md 明确列出 Backstage 开箱即用Out-of-the-box包含的功能以下逐一结合仓库文档展开。1. Backstage Software Catalog集中化的软件目录软件目录是 Backstage 整个体系的基石。根据 docs/features/software-catalog/index.md它是一套集中式系统跟踪生态中所有软件的所有权与元数据服务、网站、库、数据管道、ML 模型等。目录建立在与代码同仓存储的元数据 YAML 文件概念之上这些文件被采集harvest后在 Backstage 中可视化展示。其核心价值体现在两大用例帮助团队管理并维护自己拥有的软件——团队获得所有软件服务、库、网站、ML 模型的统一视图让公司内所有软件及其负责人可被发现——不再有隐藏在软件生态角落里的孤儿软件。从系统模型看docs/overview/technical-overview.md 的 Software Catalog System Model 小节目录围绕**实体Entity**建模分为两类核心实体Component可在源码控制中跟踪、可实现供其他组件消费 API 的软件单元、API组件之间形成边界的接口可为公开、受限或私有、Resource运行组件所需的物理或虚拟基础设施组织实体User员工、承包商等个人、Group团队、业务单元等组织单元。此外还支持System一组协作实现功能的资源与组件集合与Domain共享术语、领域模型、KPI 的系统集合等生态建模以及Location指向其他目录数据位置的标记、Type自定义类型与Template脚手架参数与步骤描述等附加概念。三种向目录添加组件的方式详见 docs/features/software-catalog/index.md手动注册前往/create页面点击REGISTER EXISTING COMPONENT按钮提供源码仓库中 YAML 文件的完整 URL通过 Backstage 创建新组件所有通过 Software Templates 创建的软件会自动注册进目录集成外部来源通过外部集成external integrations接入。除手动注册外还可通过静态配置注册组件例如在 app-config.yaml 中配置catalog: locations: - type: url target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/artist-lookup-component.yaml组件元数据的更新由拥有该组件的团队通过日常 Git 工作流维护合并后 Backstage 会自动在目录中展示更新后的元数据。用户还可对常用组件执行starring星标收藏以便快速访问。仓库的 packages/catalog-model/examples 目录存放了大量 catalog-model 示例可作为编写元数据 YAML 的参考。2. Backstage Software Templates标准化的软件脚手架Software Templates 是 Backstage 中用于创建组件的工具。默认情况下它能够加载代码骨架、注入模板变量然后将模板发布到 GitHub、GitLab 等位置。所有通过模板创建的软件都会自动注册进软件目录。使用流程导入的模板位于/create本地运行则为http://localhost:3000/create选择模板每个模板可要求不同的输入变量这些变量会被传给内部模板引擎填写变量模板通常由一组步骤steps组成每步有各自的必填或可选输入例如 GitHub 仓库信息确认页运行前汇总核对已填写的输入可返回修改运行模板点击Create执行查看结果成功后跳转成功页并展示新仓库链接失败时可点击各步骤查看失败日志用于调试也可点击 Cancel 发送中止信号后续步骤将不再执行当前步骤仅在支持取消时才被取消。值得注意的一个官方实践警告来自 docs/features/software-templates/index.md自定义 Scaffolder action 的 ID 应使用 camelCase 而非 kebab-case带连字符的 action ID如fetch-component-id会导致${{ steps.fetch-component-id.output.componentId }}这类模板表达式因连字符被当作 JavaScript 减法运算符而返回NaN。另外每次模板执行都被视为一个具有唯一 ID 的任务可通过 Create 页右上角 kebab 菜单进入 Task List 查看历史执行并使用 Start Over 以相同参数重新执行参数可编辑。3. Backstage TechDocsdocs-like-code 的技术文档方案TechDocs 是 Spotify 原生开发、直接内置进 Backstage 的docs-like-code文档即代码方案工程师用 Markdown 编写与代码同仓的文档经过少量配置即可在 Backstage 中呈现美观的文档站点。TechDocs 提供的关键能力包括无论软件环境如何部署均可使用可从 Catalog 中某服务的页面直接发现其技术文档仅靠写 Markdown 即可为任何目的创建纯文档站点支持 TechDocs Addon Framework 扩展阅读体验可利用庞大的 MkDocs 插件生态 打造丰富阅读体验支持文档搜索。其源码托管提供商支持 GitHub、GitHub Enterprise、Bitbucket、Azure DevOps、Gerrit、GitLab、GitLab Enterprise、Gitea、AWS CodeCommit、Harness Code文件存储提供商支持 Backstage 应用本地文件系统、Google Cloud Storage、AWS S3、Azure Blob Storage以及社区支持的 OpenStack Swift。技术栈组成对应仓库目录组件仓库位置前端插件plugins/techdocs前端插件库plugins/techdocs-react后端插件plugins/techdocs-backendCLI本地开发与文档生成packages/techdocs-cliTechDocs 已随 Backstage v1.0 正式发布1.2 版本起引入 TechDocs Addon Framework其官方文档还记载了 5000 文档站点、日均约 10000 次访问的规模化实践数据见 docs/features/techdocs/README.md。4. 开源插件生态无限可扩展README-fr_FR.md 指出除三大内置功能外还有不断增长的开源插件生态进一步扩展 Backstage 的定制化能力与功能。从插件架构看docs/overview/technical-overview.md 的 Plugin Architecture Overview 小节插件是挂载在 Backstage UI 上的客户端应用架构支持三种类型独立插件Standalone完全运行在浏览器中不向其他服务发起 API 请求服务支撑插件Service backed向运行 Backstage 的组织生态内的服务发起 API 请求第三方支撑插件Third-party backed与前者类似但支撑服务托管在运行 Backstage 的公司生态之外。许多核心功能本身就是插件——例如软件目录就是一个服务支撑插件查看目录时它会从 Backstage 后端服务获取实体列表并在 UI 中渲染成表格。仓库根目录的 plugins 目录存放着全部官方插件源码docs/plugins/index.md 则指导如何自行开发插件。快速开始本地安装并运行 BackstageREADME-fr_FR.md 将快速开始指引指向 Getting Started 文档其完整实操步骤记录在 docs/getting-started/index.md 中核心要点如下。环境前提Unix 系操作系统Linux、macOS 或 WSLLinux 版本需支持所需的 Node.js 版本Node.js Active LTS 版本官方推荐 Node 22 或 24可用nvm install 22或nvm install 24安装Yarn仓库当前使用 Yarn 4.4.1执行corepack enable后运行yarn set version 4.4.1Docker、git、curl或wget至少20 GB 磁盘空间与6 GB 内存随插件增多磁盘需求会上升若系统无法直接通过网络访问需开放3000与7007端口。创建应用npx backstage/create-applatest首次安装会询问是否继续安装backstage/create-app包随后要求输入应用名称将作为子目录创建示例名为my-backstage-app向导会自动完成文件生成、yarn install与yarn tsc类型检查。生成的应用目录结构如下app ├── app-config.yaml ├── catalog-info.yaml ├── package.json └── packages ├── app └── backend其中app-config.yaml是应用的主配置文件catalog-info.yaml是目录实体描述文件packages/app是可直接运行的前端应用packages/backend为认证、软件目录、软件模板、TechDocs 等功能提供后端支撑。启动应用cd my-backstage-app yarn startyarn start会在同一窗口分别启动前端与后端两个进程标记为[0]和[1]配置从app-config.yaml加载。启动日志会展示app、proxy、scaffolder、techdocs、auth、catalog、permission、search、kubernetes、notifications、signals等插件的初始化过程。看到Rspack compiled successfully后即可直接访问http://localhost:3000浏览应用使用内置的 SQLite 内存数据库与演示数据注意这并非生产就绪的安装也未包含组织专属信息需自行接入数据源集成。学习路径与文档导航README-fr_FR.md 列出了完整的官方文档体系对应到本仓库的路径如下主文档docs/index.md仓库根目录的 README.md 亦可作为总览起点软件目录docs/features/software-catalog/index.md架构docs/overview/architecture-overview.md架构决策记录见 docs/architecture-decisions/index.md如adr011-plugin-package-structure、adr009-entity-references等均可参考 docs/architecture-decisions/adr001-add-adr-log.md 的 ADR 约定为 Backstage 做设计docs/dls/design.mdDesign Language SystemDLSFAQdocs/faq/index.md配置文档docs/conf/index.md。社区与贡献README-fr_FR.md 详细列出了参与社区的方式对应仓库内的文件包括贡献指南CONTRIBUTING.md行为准则CODE_OF_CONDUCT.md采用者名单ADOPTERS.md列出已在生产环境使用 Backstage 的企业RFC 机制通过仓库 Issues 上的rfc标签参与技术方向讨论详见 LABELS.md 中的标签约定此外还有社区月度会议Backstage Community Sessions、官方博客与 Newsletter 等渠道。许可证与安全许可证Backstage 采用Apache License 2.0见 LICENSELinux 基金会持有相关商标并规范商标使用安全敏感安全漏洞建议通过安全披露流程报告而非直接公开完整的安全发布流程 详见仓库根目录的 SECURITY.md。小结以 README-fr_FR.md 为主线本文完整梳理了 Backstage 的定位、起源与治理现状逐项展开了软件目录、软件模板、TechDocs 与插件生态四大核心能力的原理与使用方式并给出了基于 docs/getting-started/index.md 的本地安装运行全流程。对于希望深入了解的读者仓库中的 docs/overview/architecture-overview.md 提供了系统级架构视图docs/overview/roadmap.md 记录了项目路线图beps 目录下的 Backstage Enhancement Proposals如 0001-notifications-system、0002-dynamic-frontend-plugins则展示了核心特性的演进设计可作为进阶研读资料。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考