Backstage 技术概览面向开发者门户的插件化架构与软件目录系统模型【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本指南以 Backstage 官方技术概览文档为骨架系统讲解这个由 Spotify 发起、现为 CNCF 孵化项目的开源开发者门户框架它的设计初衷与价值、核心功能集、插件化架构的三种形态以及支撑软件目录Software Catalog的实体系统模型。读完本文你将理解 Backstage 的架构分层、核心实体与描述符Descriptor文件格式并能在当前仓库中定位到对应的源码与配置佐证。设计初衷为什么需要 BackstageBackstage 是一个用于构建开发者门户Developer Portal的开源框架由 Spotify 创建旨在简化端到端的软件开发流程。其诞生背景非常具体随着 Spotify 规模扩大基础设施逐渐碎片化团队难以找到应当使用的 API、无法确认某项服务的负责人也找不到任何相关的文档。Backstage 正是为了解决这种工程资产不可发现、不可管理的问题而出现。它的核心思路可以概括为两条以集中式软件目录Software Catalog为动力核心配合一层位于所有基础设施和开发工具之上的抽象层让你在同一个地方管理所有软件、服务、工具与测试通过插件化架构定制 Backstage 应用的功能既可以直接使用丰富的现成插件也可以编写自己的插件同时内置自动化模板帮助团队以统一、符合最佳实践的方式创建新微服务并为所有软件提供创建、维护与查找文档的能力。当前仓库根目录的 README.md 与 docs/overview/technical-overview.md 对上述定位的描述保持一致后者即为本文的主体来源。四种角色的收益Backstage 的价值可以按使用者角色拆解工程管理者Engineering Managers在整个组织内维持标准与最佳实践管理从迁移到测试认证的完整技术生态。终端用户开发者以标准化方式快速、简单地构建软件组件并拥有一个集中管理所有项目与文档的入口。平台工程师Platform Engineers通过插件轻松集成新工具与服务、扩展既有功能获得可扩展性与可伸缩性。所有人获得一个一致、统一的体验将基础设施工具、资源、标准、所有者、贡献者与管理员串联在同一处。核心功能集Backstage 自带一组核心功能均在文档中列出并与仓库中的独立模块一一对应核心功能说明仓库中的对应模块认证与身份Authentication Identity登录与用户识别并使用内置认证提供者将访问权委托给第三方资源docs/auth/index.md、plugins/auth-backend 等Kubernetes允许开发者在本地或生产环境检查服务健康状况docs/features/kubernetes/index.md、plugins/kubernetes 系列通知Notifications为插件与外部服务提供向个人用户或用户组发送消息的能力docs/notifications/index.md、plugins/notifications 系列权限Permissions对用户访问特定数据、API 或界面操作的权限实施规则docs/permissions/overview.md、plugins/permission-*搜索Search在 Backstage 生态中检索信息可自定义每条搜索结果的外观也可接入自己的搜索引擎plugins/search 系列软件目录Software Catalog集中式系统保存所有软件的元数据服务、网站、库、ML 模型、数据管道等也包含运行软件所需的物理或虚拟基础设施元数据可通过 UI 查看与搜索docs/features/software-catalog/index.md、plugins/catalog、packages/catalog-model软件模板Software Templates帮助在 Backstage 内创建组件加载代码骨架、注入变量并发布到 GitHub 等位置docs/features/software-templates/index.md、plugins/scaffolder 系列TechDocs内置的像代码一样写文档方案文档以 Markdown 编写并与代码共存plugins/techdocs 系列其中软件目录本身就是服务后端插件Service Backed Plugin的典型示例当你在 UI 中查看目录时它会从 Backstage 后端服务获取一组服务即实体Entities并以表格形式渲染出来。插件架构概览插件是挂载到 Backstage UI 上的客户端应用让你把种类繁多的基础设施与软件开发工具整合进自己的 Backstage 应用。Backstage 借助插件架构在单一 UI 中为所有插件提供一致的用户体验详见 docs/overview/architecture-overview.md。插件架构支持三种形态独立插件Standalone完全运行在浏览器中不向其他服务发起 API 请求。例如 Tech Radar 插件只渲染硬编码信息。服务后端插件Service Backed向运行 Backstage 的组织生态内部的某个服务发起 API 请求。软件目录即属此类。第三方后端插件Third-party Backed与服务后端插件类似区别在于提供支撑的服务托管在托管 Backstage 的公司生态之外。此类请求通常经 Backstage 提供的代理服务转发以规避浏览器的跨域CORS限制。从仓库结构看plugins/ 目录下聚集了上百个插件包每个插件按-frontend前端、-backend后端、-common同构等角色拆分为多个包遵循 ADR-011 插件包结构 的约定这正是插件化生态得以规模化组织的基础。软件目录系统模型软件目录背后的系统模型建立在**实体Entity**概念之上见 术语表 与 系统模型文档模型分为两大类核心实体Core Entities与组织实体Organizational Entities。核心实体Core Entities组件Components可在源代码管理中跟踪的单个软件单元服务、网站、库、数据管道等可为实现供其他组件消费的 API。API由组件实现构成不同组件之间的边界分为公开public、受限restricted或私有private。资源Resources运行组件所需的物理或虚拟基础设施例如数据库、消息主题、S3 存储桶或 CDN。三者关系如官方示意图所示一个组件既提供providesAPI也消费consumesAPI并依赖depends on资源。组织实体Organizational Entities用户User自然人如员工、外包人员等。用户组Group组织实体如团队、业务单元或兴趣小组。生态建模System 与 Domain当组件、API、资源数量庞大时难以理解它们如何协同工作。生态建模Ecosystem Modeling允许把大量核心实体组织为更高层级的抽象系统System一组通过暴露一个或多个公开 API 来协作完成某项功能的资源与组件的集合。它向消费方隐藏了组件之间的资源与私有 API——作为所有者你可以演进组件与资源的实现而不被消费方察觉。一个系统通常只包含少数几个组件。例如播放列表管理系统可能封装两个后端服务与一个数据库并对外暴露 RPC API、每日快照数据集与播放列表更新事件流。领域Domain共享术语、领域模型、指标、KPI、业务目的或文档的一组系统的集合即一个限界上下文。例如支付领域下的各个系统应共享支付相关的文档与实体类型。大型组织中领域还可以进一步分层形成子领域。下图展示了领域、系统、核心实体与组织实体之间的示例关系。模型中的另外三项要素Location位置一个标记引用其他可获取目录数据的位置。Type类型没有预设含义可由用户自行定义类型并按需使用例如用于链接校验或构建自定义 UI 组件。Template模板同时描述在脚手架向导Scaffolding Wizard前端渲染的参数以及创建该组件时执行的步骤。实体在源码中的落点实体并非抽象概念而是有明确的类型定义与逐 kind 的实现。核心类型定义位于 packages/catalog-model/src/entity/Entity.ts每种 kind 都有独立的 alpha 版本模型例如 ComponentEntityV1alpha1.ts、ApiEntityV1alpha1.ts、ResourceEntityV1alpha1.ts、SystemEntityV1alpha1.ts、DomainEntityV1alpha1.ts、UserEntityV1alpha1.ts 与 GroupEntityV1alpha1.ts。这从源码层面印证了系统模型中两类实体、九种 kind的划分。实体描述符文件如何用 YAML 表达系统模型软件目录的数据来源是存放在源码仓库中的元数据 YAML 文件推荐命名为catalog-info.yamlBackstage 通过读取这些描述符文件完成收割并可视化详见 描述符格式文档。描述符文件与目录 API 中传输的 JSON 具有相同的结构与语义。以下是一个 Component 实体的描述符示例apiVersion: backstage.io/v1alpha1 kind: Component metadata: name: artist-web description: The place to be, for great artists labels: example.com/custom: custom_label_value annotations: example.com/service-discovery: artistweb circleci.com/project-slug: github/example-org/artist-website tags: - java links: - url: https://admin.example-org.com title: Admin Dashboard icon: dashboard type: admin-dashboard spec: type: website lifecycle: production owner: artist-relations-team system: public-websites顶层字段apiVersion、kind、metadata、spec构成所有 kind 共用的信封Envelopemetadata中的name、labels、annotations等字段具有保留语义与特定形态。spec.owner指向某个 Group 实体、spec.system指向某个 System 实体正是通过这些引用把目录中的实体编织成前文所述的依赖与从属关系网。描述符格式还支持三种占位符替换$text把引用文件内容作为纯文本嵌入为字符串$json把引用文件解析为 JSON 并嵌入解析后的结构$yaml把引用文件解析为 YAML 并嵌入解析后的结构。例如从 Web 服务器加载 OpenAPI 定义作为 API 实体的spec.definitionapiVersion: backstage.io/v1alpha1 kind: API metadata: name: petstore description: The Petstore API spec: type: openapi lifecycle: production owner: petstoreexample.com definition: $text: https://petstore.swagger.io/v2/swagger.json需要注意若要读取超出常规集成点如 github.com之外的地址需要在backend.reading.allow中显式放行目标主机并可进一步用路径限制范围例如backend: baseUrl: ... reading: allow: - host: example.com - host: *.examples.org - host: example.net paths: [/api/]一个端到端的示例组所有权视图系统模型的价值最终落在界面上在设置好关系、创建 Group 组织实体后你可以查看该组管理owned by的全部组件、API 与资源形成我的团队拥有什么的统一视图。下图即为官方示例中的组所有权界面。小结Backstage 的整套技术方案可以归纳为三层递进关系集中式软件目录提供统一的数据底座插件架构提供可扩展的功能接入方式实体系统模型则为目录中的一切软件资产提供统一、可机器识别的描述语言。三者共同构成一个可支撑组织级软件资产管理、可随团队规模增长的开发者门户框架。若需继续深入可以从 架构总览、软件目录系统模型 与 描述符格式 三份文档着手并在 packages/catalog-model 中查看实体的类型定义与校验实现。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Backstage 技术概览：面向开发者门户的插件化架构与软件目录系统模型
Backstage 技术概览面向开发者门户的插件化架构与软件目录系统模型【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本指南以 Backstage 官方技术概览文档为骨架系统讲解这个由 Spotify 发起、现为 CNCF 孵化项目的开源开发者门户框架它的设计初衷与价值、核心功能集、插件化架构的三种形态以及支撑软件目录Software Catalog的实体系统模型。读完本文你将理解 Backstage 的架构分层、核心实体与描述符Descriptor文件格式并能在当前仓库中定位到对应的源码与配置佐证。设计初衷为什么需要 BackstageBackstage 是一个用于构建开发者门户Developer Portal的开源框架由 Spotify 创建旨在简化端到端的软件开发流程。其诞生背景非常具体随着 Spotify 规模扩大基础设施逐渐碎片化团队难以找到应当使用的 API、无法确认某项服务的负责人也找不到任何相关的文档。Backstage 正是为了解决这种工程资产不可发现、不可管理的问题而出现。它的核心思路可以概括为两条以集中式软件目录Software Catalog为动力核心配合一层位于所有基础设施和开发工具之上的抽象层让你在同一个地方管理所有软件、服务、工具与测试通过插件化架构定制 Backstage 应用的功能既可以直接使用丰富的现成插件也可以编写自己的插件同时内置自动化模板帮助团队以统一、符合最佳实践的方式创建新微服务并为所有软件提供创建、维护与查找文档的能力。当前仓库根目录的 README.md 与 docs/overview/technical-overview.md 对上述定位的描述保持一致后者即为本文的主体来源。四种角色的收益Backstage 的价值可以按使用者角色拆解工程管理者Engineering Managers在整个组织内维持标准与最佳实践管理从迁移到测试认证的完整技术生态。终端用户开发者以标准化方式快速、简单地构建软件组件并拥有一个集中管理所有项目与文档的入口。平台工程师Platform Engineers通过插件轻松集成新工具与服务、扩展既有功能获得可扩展性与可伸缩性。所有人获得一个一致、统一的体验将基础设施工具、资源、标准、所有者、贡献者与管理员串联在同一处。核心功能集Backstage 自带一组核心功能均在文档中列出并与仓库中的独立模块一一对应核心功能说明仓库中的对应模块认证与身份Authentication Identity登录与用户识别并使用内置认证提供者将访问权委托给第三方资源docs/auth/index.md、plugins/auth-backend 等Kubernetes允许开发者在本地或生产环境检查服务健康状况docs/features/kubernetes/index.md、plugins/kubernetes 系列通知Notifications为插件与外部服务提供向个人用户或用户组发送消息的能力docs/notifications/index.md、plugins/notifications 系列权限Permissions对用户访问特定数据、API 或界面操作的权限实施规则docs/permissions/overview.md、plugins/permission-*搜索Search在 Backstage 生态中检索信息可自定义每条搜索结果的外观也可接入自己的搜索引擎plugins/search 系列软件目录Software Catalog集中式系统保存所有软件的元数据服务、网站、库、ML 模型、数据管道等也包含运行软件所需的物理或虚拟基础设施元数据可通过 UI 查看与搜索docs/features/software-catalog/index.md、plugins/catalog、packages/catalog-model软件模板Software Templates帮助在 Backstage 内创建组件加载代码骨架、注入变量并发布到 GitHub 等位置docs/features/software-templates/index.md、plugins/scaffolder 系列TechDocs内置的像代码一样写文档方案文档以 Markdown 编写并与代码共存plugins/techdocs 系列其中软件目录本身就是服务后端插件Service Backed Plugin的典型示例当你在 UI 中查看目录时它会从 Backstage 后端服务获取一组服务即实体Entities并以表格形式渲染出来。插件架构概览插件是挂载到 Backstage UI 上的客户端应用让你把种类繁多的基础设施与软件开发工具整合进自己的 Backstage 应用。Backstage 借助插件架构在单一 UI 中为所有插件提供一致的用户体验详见 docs/overview/architecture-overview.md。插件架构支持三种形态独立插件Standalone完全运行在浏览器中不向其他服务发起 API 请求。例如 Tech Radar 插件只渲染硬编码信息。服务后端插件Service Backed向运行 Backstage 的组织生态内部的某个服务发起 API 请求。软件目录即属此类。第三方后端插件Third-party Backed与服务后端插件类似区别在于提供支撑的服务托管在托管 Backstage 的公司生态之外。此类请求通常经 Backstage 提供的代理服务转发以规避浏览器的跨域CORS限制。从仓库结构看plugins/ 目录下聚集了上百个插件包每个插件按-frontend前端、-backend后端、-common同构等角色拆分为多个包遵循 ADR-011 插件包结构 的约定这正是插件化生态得以规模化组织的基础。软件目录系统模型软件目录背后的系统模型建立在**实体Entity**概念之上见 术语表 与 系统模型文档模型分为两大类核心实体Core Entities与组织实体Organizational Entities。核心实体Core Entities组件Components可在源代码管理中跟踪的单个软件单元服务、网站、库、数据管道等可为实现供其他组件消费的 API。API由组件实现构成不同组件之间的边界分为公开public、受限restricted或私有private。资源Resources运行组件所需的物理或虚拟基础设施例如数据库、消息主题、S3 存储桶或 CDN。三者关系如官方示意图所示一个组件既提供providesAPI也消费consumesAPI并依赖depends on资源。组织实体Organizational Entities用户User自然人如员工、外包人员等。用户组Group组织实体如团队、业务单元或兴趣小组。生态建模System 与 Domain当组件、API、资源数量庞大时难以理解它们如何协同工作。生态建模Ecosystem Modeling允许把大量核心实体组织为更高层级的抽象系统System一组通过暴露一个或多个公开 API 来协作完成某项功能的资源与组件的集合。它向消费方隐藏了组件之间的资源与私有 API——作为所有者你可以演进组件与资源的实现而不被消费方察觉。一个系统通常只包含少数几个组件。例如播放列表管理系统可能封装两个后端服务与一个数据库并对外暴露 RPC API、每日快照数据集与播放列表更新事件流。领域Domain共享术语、领域模型、指标、KPI、业务目的或文档的一组系统的集合即一个限界上下文。例如支付领域下的各个系统应共享支付相关的文档与实体类型。大型组织中领域还可以进一步分层形成子领域。下图展示了领域、系统、核心实体与组织实体之间的示例关系。模型中的另外三项要素Location位置一个标记引用其他可获取目录数据的位置。Type类型没有预设含义可由用户自行定义类型并按需使用例如用于链接校验或构建自定义 UI 组件。Template模板同时描述在脚手架向导Scaffolding Wizard前端渲染的参数以及创建该组件时执行的步骤。实体在源码中的落点实体并非抽象概念而是有明确的类型定义与逐 kind 的实现。核心类型定义位于 packages/catalog-model/src/entity/Entity.ts每种 kind 都有独立的 alpha 版本模型例如 ComponentEntityV1alpha1.ts、ApiEntityV1alpha1.ts、ResourceEntityV1alpha1.ts、SystemEntityV1alpha1.ts、DomainEntityV1alpha1.ts、UserEntityV1alpha1.ts 与 GroupEntityV1alpha1.ts。这从源码层面印证了系统模型中两类实体、九种 kind的划分。实体描述符文件如何用 YAML 表达系统模型软件目录的数据来源是存放在源码仓库中的元数据 YAML 文件推荐命名为catalog-info.yamlBackstage 通过读取这些描述符文件完成收割并可视化详见 描述符格式文档。描述符文件与目录 API 中传输的 JSON 具有相同的结构与语义。以下是一个 Component 实体的描述符示例apiVersion: backstage.io/v1alpha1 kind: Component metadata: name: artist-web description: The place to be, for great artists labels: example.com/custom: custom_label_value annotations: example.com/service-discovery: artistweb circleci.com/project-slug: github/example-org/artist-website tags: - java links: - url: https://admin.example-org.com title: Admin Dashboard icon: dashboard type: admin-dashboard spec: type: website lifecycle: production owner: artist-relations-team system: public-websites顶层字段apiVersion、kind、metadata、spec构成所有 kind 共用的信封Envelopemetadata中的name、labels、annotations等字段具有保留语义与特定形态。spec.owner指向某个 Group 实体、spec.system指向某个 System 实体正是通过这些引用把目录中的实体编织成前文所述的依赖与从属关系网。描述符格式还支持三种占位符替换$text把引用文件内容作为纯文本嵌入为字符串$json把引用文件解析为 JSON 并嵌入解析后的结构$yaml把引用文件解析为 YAML 并嵌入解析后的结构。例如从 Web 服务器加载 OpenAPI 定义作为 API 实体的spec.definitionapiVersion: backstage.io/v1alpha1 kind: API metadata: name: petstore description: The Petstore API spec: type: openapi lifecycle: production owner: petstoreexample.com definition: $text: https://petstore.swagger.io/v2/swagger.json需要注意若要读取超出常规集成点如 github.com之外的地址需要在backend.reading.allow中显式放行目标主机并可进一步用路径限制范围例如backend: baseUrl: ... reading: allow: - host: example.com - host: *.examples.org - host: example.net paths: [/api/]一个端到端的示例组所有权视图系统模型的价值最终落在界面上在设置好关系、创建 Group 组织实体后你可以查看该组管理owned by的全部组件、API 与资源形成我的团队拥有什么的统一视图。下图即为官方示例中的组所有权界面。小结Backstage 的整套技术方案可以归纳为三层递进关系集中式软件目录提供统一的数据底座插件架构提供可扩展的功能接入方式实体系统模型则为目录中的一切软件资产提供统一、可机器识别的描述语言。三者共同构成一个可支撑组织级软件资产管理、可随团队规模增长的开发者门户框架。若需继续深入可以从 架构总览、软件目录系统模型 与 描述符格式 三份文档着手并在 packages/catalog-model 中查看实体的类型定义与校验实现。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考