关于后端:平台工程-用Backstage构建开发者门户-1

本文介绍了如何应用开源 Backstage 构建本人的开发者门户，并基于此实际平台工程。本系列共两篇文章，这是第一篇。原文: Platform Engineering: Building Your Developer Portal with Backstage — Part 1

在上一篇文章 (平台工程与平安) 中，咱们介绍了什么是平台工程，为何如此重要，和 DevOps 做了比拟，以及介绍了平台工程如何帮忙进步安全性。

明天咱们来入手从头开始构建一个开发者门户。

因为平台工程都是自助服务的，外部开发者门户在新范式中至关重要，在该范式中实现了所有自助服务性能和集成。

思考到开发者门户的重要性，在构建之前，须要弄清楚咱们对它的冀望到底是什么。通常，为了最大限度利用平台工程，开发者门户将蕴含一些要害性能，例如:

服务目录: 让开发人员能够鸟瞰所有我的项目、服务、部署状态、文档、所有权，甚至是值班打算和事件等;
某种资源库脚手架 / 我的项目生成工具: 例如 Cookiecutter 这样的工具，能让开发人员从门户网站间接启动新服务;
定制: 兴许你心愿将应用的任何工具链集成到开发者门户中，使其成为真正对立的一站式体验，可能的集成包含 Kubernetes、CI/CD 状态、值班打算、事件管理系统、secrets 管理器等。

此时，门户网站能够解决所有事务，如获取服务信息、待命打算、触发事件、部署工作以及处理事件治理。有了这些性能，开发人员就能取得真正对立的体验，在一个中央创立服务，随后跟踪和操作 / 保护这些服务，最大限度的施展开发者门户的后劲。

既然晓得了开发者门户网站的真正需要，那就来构建吧。

因为它将具备多种性能，设计 / 编码局部自身就是一个宏大的我的项目，不是所有团队都能承当得起。因而须要一个工具来疾速构建门户网站，侥幸的是，咱们曾经有了这样的工具 –Backstage。

Backstage 是用于构建开发者门户网站的开放平台。Backstage 自身并不是开发者门户，而是用于构建开发者门户的工具。想想 ”create-react-app” 和用它创立的理论 react 利用的区别就晓得了。开箱即用的 Backstage 包含:

软件目录: 用于治理所有软件，如微服务、库、数据管道、网站和 ML 模型；
软件模板: 用于疾速启动新我的项目，并依据组织的最佳实际对工具进行标准化；
文档: 采纳 ” 像编写代码一样编写文档 ” 的办法，轻松创立、保护、查找和应用技术文档；
一直倒退的开源插件生态系统，进一步扩大了 Backstage 的可定制性和性能。

Backstage 的架构非常灵活: 前端应用 React/TypeScript 编写，后端应用 Node.js，还能够通过增加插件来扩大性能。

更重要的是，Backstage(由 Spotify 创立)当初由云原生计算基金会 (CNCF) 作为孵化级我的项目托管，这意味着咱们能够取得想要的所有社区反对。它还设有办公时间，能够在每周四加入互动，精确理解开源平台如何进步开发人员的效率和体验。

说得够多了。明天咱们将从头开始，本人构建一个开发者门户。实现本教程后，能够应用带有内置平安 CI 工作流的模板来疏导一个新服务，查看 CI 状态，并在同一个中央查看该服务的文档。

废话少说，开始吧。

3.1. 前提条件

不多，可能所有 DevOps 工程师都曾经具备:

基于 Unix 的操作系统。例如，能够在 macOS、Linux 或 Windows Subsystem for Linux (WSL) 上运行。
curl、git、Docker
Node.js, yarn

3.2. 创立门户网站

运行：

npx @backstage/create-app@0.5.2-next.3

作者注：

咱们之所以应用 backstage/create-app@0.5.2-next.3 而不是 backstage/create-app@latest，是因为咱们须要这项性能在 GitHub 中创立 secrets，以便在 GitHub Actions 工作流中应用。该性能曾经开发实现，但截至目前(2023 年 6 月 18 日)，尚未集成到最新版本的 backstage/create-app 中。

如果稍后浏览本文时，最新版本已指向 2023 年 6 月 (或更晚) 公布的版本，就能够平安的运行 npx @backstage/create-app@latest 而无需指定奇怪的版本。

该命令提供互动模式，只须要输出名称，例如 “my-portal”，回车，而后期待应用程序实现。

进入目录并运行:

yarn dev

当初应该曾经建设并运行了门户网站！就这么简略！当初能够浏览一下，感受一下软件目录、模板、文档和其余货色:

不过目前还没什么用。咱们持续配置。

因为开发者门户将负责疏导新仓库，因而须要 GitHub 的操作权限，这也是咱们须要进行 GitHub 认证和集成的起因。

4.1. 用于集成的集体拜访令牌

尽管应用 GitHub 应用程序可能是设置集成的最佳形式，因为它的权限设置十分精密，但在本教程中，咱们将应用集体拜访令牌，以便更快开始应用:

关上 GitHub 令牌创立页面，创立集体拜访令牌。
应用一个名称来标识此令牌，并将其写入备注栏，抉择过期天数。
如果很难抉择特定数字，倡议抉择 7 天，这是一个侥幸数字:)。(咱们将只在本地进行测试，不会在生产环境中运行）。
在本教程中，咱们先将范畴设置为最大，这样就不会因为纠结于 GitHub 权限而影响体验。不过请留神，千万不要在生产环境中这样做！

而后，将令牌作为环境变量导出:

export GITHUB_TOKEN=xxx

在 app-config.yaml 文件中，将 integrations 局部更改为以下内容:

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN} # leave it like this, read values from env var

4.2. 创立 GitHub OAuth 应用程序

拜访 https://github.com/settings/applications/new 创立 OAuth 应用程序。主页 URL 应指向 Backstage 的前台，在本教程中是 http://localhost:3000。受权回调 URL 将指向受权后盾，很可能是 http://localhost:7007/api/auth/github/handler/frame。

而后，再次关上 app-config.yaml 文件，将 auth 局部更新为以下内容，配置身份验证:

auth:
  environment: development
  providers:
    github:
      development:
        clientId: YOUR CLIENT ID # put your values here
        clientSecret: YOUR CLIENT SECRET # put your values here

请留神，将客户端 secrets 作为硬编码 secrets 存储在配置文件中有违平安最佳实际，只能用于本地开发。对于生产应用，咱们能够依照 12 因素利用规定，从环境变量中读取。

更改配置后，必须进行 yarn dev 服务器并从新运行 yarn dev。

接下来筹备软件模板，用于疾速启动一项新服务。

模板应蕴含以下内容:

服务通用的根本源代码 / 目录构造
一些文档
测试 / 构建 / 部署服务的 CI 工作流

本教程将以我创立的模板 https://github.com/IronCore864/backstage-test-template 为例。

目录构造绝对简略，只有两个局部:

一个 skeleton 文件夹
一个 template.yaml 文件

5.1. skeleton 文件夹

skeleton文件夹蕴含应用此模板创立新服务时将出现的所有模板，变量的格局为 ${{values.varName}}。

如果你相熟 Helm、YAML 或 Go 模板(或简直所有模板工具)，你会发现这种格局很容易浏览和了解，而且没有额定开销。

惟一值得一提的是 Backstage 应用的名为 catalog-info.yaml 的文件，该文件必须存在，否则就无奈将创立的服务注册为门户中的组件。

如你所见，在模板中曾经内置了一些 GitHub Actions 工作流，其中一个将测试拉取申请并推送到主分支，另一个将应用 ggshield 扫描软件仓库中的硬编码 secrets。

这样咱们就能够将所有的 CI/CD 最佳实际放入模板中，当其他人启动新服务时，就曾经领有了所需的所有，并默认启用了平安性能。

5.2. template.yaml 文件

template.yaml 文件定义了模板在门户界面中的外观和实际操作。

文件很长，乍一看仿佛让人手足无措，但一旦仔细阅读，就会发现它十分简单明了:

语法相似于 Kubernetes 的自定义资源；
有两大部分，一部分是参数，另一部分是步骤；
参数定义了应用该模板时所需的输出及其类型；
步骤定义了执行该模板时理论产生的状况，看起来十分像 GitHub 的 Actions 工作流。

参数示例:

parameters:
  - title: Provide some simple information
    required:
      - service_name
      - owner
    properties:
      service_name:
        title: Name
        type: string
        description: Unique name of the service.
        ui:field: EntityNamePicker
      description:
        title: Description
        type: string
        description: Help others understand what this service is for; optional.
      owner:
        title: Owner
        type: string
        description: Owner of the component
        ui:field: OwnerPicker
        ui:options:
          allowedKinds:
            - Group
  ...

步骤示例:

steps:

- id: template
  name: Fetch Skeleton + Template
  action: fetch:template
  input:
  url: ./skeleton
  copyWithoutTemplating: - .github/workflows/\*
  values:
  serviceName: ${{parameters.service_name}}
  description: ${{parameters.description}}
  destination: ${{parameters.repoUrl | parseRepoUrl}}
  owner: ${{parameters.owner}}
  ...

咱们能够从上述文件中推断出它到底定义了什么:

首先须要输出两个输出参数: 服务名称 (service_name) 和所有者(owner);
须要抉择一个带有额定参数 (GITGUARDIAN_API_KEY，用于 CI 流水线) 的版本库地位;
而后，它会获取模板、渲染模板、将模板公布到 GitHub 并在咱们的门户网站上注册。

5.3. 注册模板

最初，把模板增加到门户目录中，这样其他人就能够应用这个模板了。

目录最间接的配置是申明增加指向 YAML 文件的地位，并进行动态地位配置。地位会增加到 app-config.yaml 文件的 catalog.locations 关键字下的目录中:

catalog:
  locations:
    - type: url
      target: https://github.com/IronCore864/backstage-test-template/blob/main/template.yaml
      rules:
        - allow: [Template]

上述规定容许咱们从指定的 URL 增加模板。

记得重启 yarn dev 服务器。

当初，咱们曾经筹备好了所有，是时候一睹魔法的风采了。

拜访 http://localhost:3000，点击 “Create” 按钮，抉择咱们的模板：

输出必要信息。对于 GitGuardian API 密钥，请在此处创立：https://dashboard.gitguardian.com/api/personal-access-tokens。

所有就绪后，点击 “ 下一步 ”，神奇的事件就会产生:

当初所有都应该创立好了。

咱们能够在目录中查看:

咱们还创立并提供了文档:

最初看看 CI 的状态:

流水线仿佛曾经胜利实现，咱们能够点击查看更多细节，包含具体步骤和日志。如果你更喜爱在 CI 软件 (这里是 GitHub Actions) 中查看，能够点击相应链接跳转。

上述示例残缺源码能够参考 Github 仓库。

这意味着无论团队应用什么工具链，团队成员都不用记住 10 个不同工具的 10 个不同 URL，也不用始终关上这 10 个标签页。当他们须要某些信息时，只有进入开发者门户，就能取得所有信息，这正是外部开发者门户的弱小之处。

在教程的第一局部，咱们介绍了开发者门户网站的性能，学习如何应用开源 Backstage 工具创立本人的门户网站，应用 GitHub 配置门户网站，创立软件模板，并从中启动一项服务。

如果集成越来越多，开发者门户的性能可能远不止于此。设想一下，如果你在 Kubernetes 中部署服务，应用 Argo CD 进行 GitOps 部署，应用 HashiCorp Vault 进行 secrets 治理，而所有都集成在门户中。当你须要查看部署状态时，当你想查看 K8s 中的理论资源时，不用拜访 Vault、Argo CD 和 K8s Dashboard。你甚至不用记住它们的 URL，甚至不晓得这些货色的存在，因为有一个工具能够统治它们，那就是开发者门户。

本教程仅实用于本地疾速启动，在生产中应用时有许多问题须要思考。例如，咱们当初应用的是动态配置，没有什么是长久化的，如果重新启动开发服务器，目录信息就会失落。为此，咱们须要为门户配置 Postgres。再比方，咱们应用 “yarn dev” 来启动前端和后端，对于生产利用，可能心愿将前端和后端离开，将它们作为容器部署在 K8s 中，并为它们创立 Ingress 等。

在本教程的下一部分，咱们将理解 Backstage 插件的机制，看看如何将其性能扩大到更高水平。

你好，我是俞凡，在 Motorola 做过研发，当初在 Mavenir 做技术工作，对通信、网络、后端架构、云原生、DevOps、CICD、区块链、AI 等技术始终保持着浓重的趣味，平时喜爱浏览、思考，置信继续学习、一生成长，欢送一起交流学习。为了不便大家当前能第一工夫看到文章，请敌人们关注公众号 ”DeepNoMind”，并设个星标吧，如果能一键三连(转发、点赞、在看)，则能给我带来更多的反对和能源，激励我继续写下去，和大家独特成长提高！

本文由 mdnice 多平台公布

关于后端:平台工程-用Backstage构建开发者门户-1

1. 当咱们议论开发者门户时，咱们在议论什么

2. 抉择工具：Backstage

3. 构建门户网站

3.1. 前提条件

3.2. 创立门户网站

4. GitHub 认证与集成

4.1. 用于集成的集体拜访令牌

4.2. 创立 GitHub OAuth 应用程序

5. 创立模板

5.1. skeleton 文件夹

5.2. template.yaml 文件

5.3. 注册模板

6. 把所有货色放在一起

7. 小结