实用教程｜手把手教你使用 Backstage 构建开发者门户 — Part 1

作者｜Tiexin Guo

翻译｜平台工程技术社区

链接｜https://medium.com/4th-coffee/platform-engineering-building-your-developer-portal-with-backstage-part-1-e2f5c0588d94

今天，让我们亲身实践，从零开始构建一个开发者门户。

01 当我们谈及开发者门户时，我们要谈论些什么？

由于平台工程的核心是自助服务，因此内部开发者门户在新模式中至关重要，所有的自助服务功能和集成都在门户中实现。

鉴于开发者门户网站的重要性，在构建之前，我们需要弄清楚我们对门户网站的期望是什么。通常情况下，为了最大限度地利用平台工程，开发者门户网站将包含一些关键功能，例如：

• 服务目录：让开发人员查看所有项目、服务、部署状态、文档、所有权，甚至值班时间表和事件等；

• 某种资源库脚手架/项目生成工具：例如，像 cookiecutter 这样的工具，它能让开发人员从门户网站本身启动新的服务；

• 定制：您可能希望将您使用的任何工具链集成到您的开发者门户中，使其成为真正统一的一站式体验。可能的集成包括 Kubernetes、CI/CD
  状态、值班计划、事件管理系统、机密管理器等。

02 选择工具：Backstage

现在知道了我们真正想要的开发者门户是什么，接下来我们开始进行构建。

开发者门户将具有多种功能，设计/编码部分本身就是一个庞大的项目，并非所有团队都能负担得起。也就是说，我们需要一个工具来快速构建门户，幸运的是，我们已经有了一个工具——Backstage。

Backstage 是一个用于构建开发者门户的开放平台。Backstage 本身并不是一个开发者门户，而是一个构建开发者门户的工具。Backstage 包括：

• 软件目录：用于管理所有软件，如微服务、库、数据流水线、网站和 ML 模型；

• 软件模板：用于快速启动新项目，并将您的工具与企业的最佳实践标准化；

• 文档：采用 "文档即代码 "的方法，轻松创建、维护、查找和使用技术文档；

• 不断发展的开源插件生态系统：可进一步扩展Backstage的可定制性和功能。

Backstage 的架构非常灵活：它有一个用 React/TypeScript 编写的前端和一个用 Node.js 编写的后端，并且可以通过添加插件来扩展其功能。

此外，Backstage（由 Spotify 创建）现在由云原生计算基金会 (CNCF)作为孵化级项目托管，也就是说用户可以获得所需的所有社区支持。还设有办公时间，您可以在每周四以交互方式加入，准确了解开源平台如何提高开发人员的效率和体验。

那么今天我们将从头开始构建一个开发者门户。通过本教程后，您可以使用带有安全 CI 工作流的模板来开始一个新服务，检查 CI 状态，并在同一个地方查看该服务的文档。

03 门户网站的构建

前提条件

这部分可能所有 DevOps 工程师都已经掌握了：

• 基于 Unix 的操作系统。例如，可以在 macOS、Linux 或 Windows Subsystem for Linux (WSL)上运行。

• curl、git、Docker

• Node.js、yarn

创建门户

运行以下：

npx @backstage/[email protected]

我们之所以使用 backstage/[email protected] 而不是backstage/create-app@latest，是因为我们需要这个功能来在GitHub 中创建秘密，以便在 GitHub Actions 工作流中使用。该功能已经开发完成，但截至目前（2023年6月18日），尚未集成到最新版本的backstage/create-app中。
 

如果您稍后阅读本文时，最新版本指向2023年6月（或更晚）发布的版本，您可以安全地运行npx @backstage/create-app@latest 而无需指定奇怪的版本。

该命令提供交互模式，您需要输入名称，例如 “my-portal”，按回车键，然后等待应用程序完成。

输入目录并运行：

yarn dev

这样就建立并运行了门户网站！就是这么简单！现在，您可以先浏览一下，感受一下软件目录、模板、文档和其他东西：

目前上面暂时做不了什么，让我们继续进行配置。

04 GitHub 身份验证和集成

由于开发者门户将负责引导新的代码仓库，因此需要 GitHub 的操作权限，这也是我们需要进行 GitHub 认证和集成的原因。

用于集成的个人访问令牌

虽然使用 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

创建 GitHub OAuth 应用程序

访问 https://github.com/settings/applications/new，创建您的 OAuth 应用程序。主页URL应指向Backstage的前端。

在本教程中，它将是http://localhost:3000。授权回调 URL 将指向 Auth 后台，很可能是 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

请注意，将客户端密码作为硬编码密码存储在配置文件中有违安全最佳实践，只能用于本地开发。对于生产使用，我们可以按照 12-factor app [1] 规则，从环境变量中读取它们。

在这些配置更改之后，我们重新运行yarn dev。

05 创建模板

接下来准备一个软件模板，它可以用来立即启动新服务。模板应包含以下内容：

• 基本的源代码/您的服务所共有的目录结构

• 文档

• 用于测试/构建/部署服务的 CI 工作流

对于本教程，我们将在此处使用此模板：

https://github.com/IronCore864/backstage-test-template

目录结构相对简单，只有两个部分：

• 一个skeleton文件夹；

• 一个template.yaml文件。

skeleton 文件夹

skeleton文件夹包含使用该模板创建新服务时将要绘制的所有模板，变量的格式为${{ values.varName }}。如果您熟悉 Helm、YAML 或 Go 模板（或任何模板工具），您会发现这很容易阅读和理解，而且无需任何成本。

值得一提的是catalog-info.yaml文件，它被 Backstage 使用，因此该文件必须存在；否则，就无法在门户中将创建的服务注册为组件。在模板中，我们已经内置了一些 GitHub Actions 工作流，其中一个将测试拉取请求并推送至主分支，另一个将使用ggshield扫描版本库中的硬编码秘密。

通过这种方式，我们可以将所有 CI/CD 最佳实践放在模板中，这样当其他人推出新服务时，他们已经拥有了默认启用的安全功能所需的一切。

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，并在我们的门户中注册。

注册模板

最后，将我们的模板添加到门户的目录中，以便其他人可以使用该模板。

目录最简单的配置是以声明方式添加指向具有静态位置配置的 YAML 文件的位置。位置将添加到catalog.locations下的app-config.yaml文件中。

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

上面的规则允许我们从指定的 URL 添加模板。

最后请记住重启yarn dev服务器。

06 将所有内容整合在一起

现在我们已经准备好了一切，是时候看看效果了。

访问http://localhost:3000 ，然后单击“创建”按钮，选择我们的模板：

输入必要信息。请在此处创建 GitGuardian API 密钥：

https://dashboard.gitguardian.com/api/personal-access-tokens

当一切设置完毕后，点击“下一步”，然后一起来看看效果：

我们可以在我们的目录中查看：

我们还创建并绘制了文件：

最后，让我们检查一下 CI 状态：

看来流水线已经成功完成，我们可以点击它们查看更多细节，包括详细的步骤和日志；如果您更喜欢在 CI 软件（这里是 GitHub Actions）中查看，可以点击相应的链接跳转。为了方便您参考，此存储库是我使用上面的模板创建的。

这意味着无论团队使用什么工具链，团队成员都不必记住 10 个不同工具的 10 个不同 URL，也不必始终保持这 10 个选项卡打开。当他们需要任何信息时，只需要访问开发者门户即可，而这正是内部开发者门户的优势。

07 总结

在本文中，我们回顾了开发者门户的特点，学习了如何使用开源的 Backstage 工具创建自己的门户，通过 GitHub 配置我们的门户，创建软件模板，并从中引导一个服务。

在实际场景中，随着集成越来越多，开发者门户可能远不止这些。想象一下，如果你在 Kubernetes 中部署服务，使用 Argo CD 进行 GitOps 部署，使用 HashiCorp Vault 进行机密管理，并且所有的集成都在你的门户中，当你需要检查部署状态时，例如想查看 K8s 中的实际资源时，你不必访问 Vault、Argo CD、K8s Dashboard，你甚至不必记住它们的 URL，只需要在开发者门户上点击即可。

需要注意的是，本教程仅适用于本地快速启动；对于生产使用，还需要根据实际情况来进行考量和调整。例如，我们现在使用的是静态配置，如果重启开发服务器，目录信息就会丢失。为此，需要为门户配置 Postgres。再比如，我们使用 yarn dev 来启动前端和后端；在生产使用中，你可能希望将前端和后端分开，将它们作为容器部署在 K8s中 ，并为它们创建 Ingress 之类的东西。

在本教程的下一部分，我们将了解 Backstage 插件的机制，看看如何将其功能扩展到更高水平。