backstage~开始一个backstage应用

应该如何创建自己公司的backstage平台

1. 两种方式的本质区别

特性 npx @backstage/create-app 从 GitHub 下载源代码
产出物 一个完整的、可立即运行和开发的 Backstage 应用。 Backstage 项目框架本身的源代码，不是你应用的代码。
目的 创建你自己的、个性化的 Backstage 开发者门户。 这是官方推荐的、标准的启动方式。 用于贡献代码、深度研究框架内核。比如你想为 Backstage 项目本身修复Bug或开发新功能。
关系 这个命令内部会去获取 GitHub 上最新的 Backstage 框架，并为你生成一个预配置好的应用。 是 create-app 命令所依赖的“原材料”。
适合场景 99.9% 的公司部署和定制场景。 0.1% 的 Backstage 核心开发者或研究者。

2. 详细解释

关于 npx @backstage/create-app：

  • 这个命令是一键式脚手架工具。它会：
    1. 从 npm 仓库获取最新的创建工具。
    2. 为你交互式地创建一个新的项目目录（比如 my-backstage）。
    3. 在这个目录里，生成一个完整的、单体式的 Backstage 应用，这个应用已经集成了所有核心插件（软件目录、模板、文档等）。
    4. 自动安装好所有依赖。
  • 是的，这个命令创建出来的应用，就是一个完整的、需要你后续部署和定制的 Backstage 服务平台。你可以立刻在本地运行它（yarn dev），它就是一个拥有基础功能的开发者门户。你之后的所有定制化开发（添加公司Logo、配置认证、接入内部系统、编写自定义插件）都将基于这个项目进行。

关于从 GitHub 下载源码：

  • 如果你直接克隆 Backstage 的主仓库（https://github.com/backstage/backstage），你会得到一个包含 Backstage 框架本身、所有核心插件源码、以及大量示例和开发工具 的巨型代码库。
  • 这个代码库结构复杂，并不是一个可以直接运行的应用。它更像是一个“工厂”，而 create-app 是这个“工厂”生产出的“标准产品”。
  • 直接基于这个代码库开始构建你的应用，会异常困难，你需要手动处理极其复杂的项目配置、依赖管理和构建流程，这几乎是一条不归路。

结论与建议

对于希望部署自己平台的公司，正确的启动步骤是：

  1. 使用脚手架创建：在你的开发机器上，运行 npx @backstage/create-app。按照提示输入应用名称（如 company-dev-portal）。
  2. 获取专属代码库：命令完成后，你会得到一个名为 company-dev-portal 的文件夹。这就是你公司专属的 Backstage 平台的源代码。你应该立即将它推送到你公司的内部 Git 仓库（如 GitLab, Gitee, 内部GitLab）中进行版本管理。
  3. 本地运行与探索：进入该目录，运行 yarn install 和 yarn dev，即可在本地启动一个基础版的门户。通过访问 http://localhost:3000 来熟悉它。
  4. 开始定制化：基于这个生成的项目，你可以：
    • 修改 app-config.yaml 配置文件（设置后端地址、数据库、认证等）。
    • 在 /packages/app 下定制前端界面（如主题、Logo）。
    • 通过 yarn backstage-cli plugin add 添加新的社区插件。
    • 创建自己的软件模板和编写技术文档。

简单来说：npx @backstage/create-app 是“购买一套精装修房的毛坯房”，你只需要在此基础上进行个性化装修。而从 GitHub 下载源码是“买下整块地和水泥钢筋，从打地基开始自己盖楼”。 对于绝大多数团队，前者是唯一明智的选择。

源码用来开发，npx @backstage/create-app产品用来部署

你的理解完全正确！是第二种情况。这是一个非常重要的概念区分，很多新手都会在这里产生混淆。

让我来清晰地解释一下：

核心比喻

  • npx @backstage/create-app：就像是平台团队购买并搭建好一台“服务器”和“网站框架”。
  • 部署后的 Backstage 平台：就是运行在那台服务器上的公司内部网站，比如叫 dev-portal.company.com。
  • 其他开发者：是这个内部网站的“用户”，他们通过浏览器访问这个网站来使用各种服务，完全不需要自己运行 create-app。

详细分工

1. 平台团队的工作（一次性的）

  • 使用 npx @backstage/create-app 创建唯一的一个 Backstage 应用项目（例如 company-backstage）。
  • 对这个项目进行定制化配置（设置公司认证、连接内部Git仓库、配置数据库、设计主题等）。
  • 将这个项目构建、部署到公司的服务器或Kubernetes集群上，使其成为一个长期运行、可供所有人访问的Web服务。

2. 普通开发者的工作（日常的）

  • 访问平台：在浏览器中打开公司部署好的 Backstage 门户地址（如 https://internal-dev-portal.com）。
  • 注册/发现项目：在平台的“软件目录”中，为自己负责的微服务或应用注册一个实体。这通常是通过在项目的代码仓库根目录添加一个 catalog-info.yaml 文件来实现的。平台会扫描这个文件，将项目信息展示在目录中。
  • 使用模板创建新项目：当需要新建一个微服务时，不是手动复制项目，而是去 Backstage 的 “模板” 页面，选择一个预设好的模板（如“Spring Boot 微服务模板”）。点击一下，填写项目名等参数，平台就会自动在GitLab/GitHub上创建一个结构规范、配置齐全的新项目仓库。
  • 查看文档与运维信息：在平台上找到自己的服务页面，查看相关文档、CI/CD状态、Kubernetes部署情况、监控链接等。

插件

  • 插件安装 yarn workspace backend add
  • github登录 @backstage/plugin-auth-backend-module-github-provider
  • /api/signals @backstage/plugin-signals-backend

工作流程图示

平台工程师：
[执行 npx @backstage/create-app] --> [得到一个代码项目: my-company-portal] --> [定制、部署] --> [一个运行中的网站: https://portal.example.com]

应用开发者A：
[浏览器访问 https://portal.example.com] --> [使用模板创建"订单服务"] --> [平台自动生成 Git 仓库 /order-service]
应用开发者B：
[浏览器访问 https://portal.example.com] --> [在目录中搜索并查看"用户服务"] --> [查看其CI状态和文档]

总结

  • npx @backstage/create-app 是一个“构建平台”的命令，由平台团队执行一次，用于生成你们公司专属的 Backstage 门户的源代码。
  • 部署后的 Backstage 是一个“使用平台”的Web界面，由全体开发者日常访问，用于管理他们自己的业务项目（注册、创建、查看）。

所以，绝对不要要求每个开发者在开发新功能时都去运行 create-app。他们只需要使用你们已经部署好的那个统一的 Backstage 门户。

backstage产品项目目录

  • app-config.yaml：应用配置文件(docs/conf/defining.md)
  • catalog-info.yaml：组件元数据描述文件(docs/features/software-catalog/descriptor-format.md)
  • packages/app：前端应用代码
  • packages/backend：后端服务代码
posted @ 2026-04-14 09:35  张占岭  阅读(9)  评论(0)    收藏  举报