共计 6010 个字符，预计需要花费 16 分钟才能阅读完成。
本文介绍了如何应用开源 Backstage 构建本人的开发者门户，并基于此实际平台工程。本系列共两篇文章，这是第一篇。原文: Platform Engineering: Building Your Developer Portal with Backstage — Part 1
在上一篇文章 (平台工程与平安) 中，咱们介绍了什么是平台工程，为何如此重要，和 DevOps 做了比拟，以及介绍了平台工程如何帮忙进步安全性。
明天咱们来入手从头开始构建一个开发者门户。
1. 当咱们议论开发者门户时，咱们在议论什么
因为平台工程都是自助服务的，外部开发者门户在新范式中至关重要，在该范式中实现了所有自助服务性能和集成。
思考到开发者门户的重要性，在构建之前，须要弄清楚咱们对它的冀望到底是什么。通常，为了最大限度利用平台工程，开发者门户将蕴含一些要害性能，例如:
- 服务目录: 让开发人员能够鸟瞰所有我的项目、服务、部署状态、文档、所有权，甚至是值班打算和事件等;
- 某种资源库脚手架 / 我的项目生成工具: 例如 Cookiecutter 这样的工具，能让开发人员从门户网站间接启动新服务;
- 定制: 兴许你心愿将应用的任何工具链集成到开发者门户中，使其成为真正对立的一站式体验，可能的集成包含 Kubernetes、CI/CD 状态、值班打算、事件管理系统、secrets 管理器等。
此时，门户网站能够解决所有事务，如获取服务信息、待命打算、触发事件、部署工作以及处理事件治理。有了这些性能，开发人员就能取得真正对立的体验，在一个中央创立服务，随后跟踪和操作 / 保护这些服务，最大限度的施展开发者门户的后劲。
2. 抉择工具：Backstage
既然晓得了开发者门户网站的真正需要，那就来构建吧。
因为它将具备多种性能，设计 / 编码局部自身就是一个宏大的我的项目，不是所有团队都能承当得起。因而须要一个工具来疾速构建门户网站，侥幸的是，咱们曾经有了这样的工具 –Backstage。
Backstage 是用于构建开发者门户网站的开放平台。Backstage 自身并不是开发者门户，而是用于构建开发者门户的工具。想想 ”create-react-app” 和用它创立的理论 react 利用的区别就晓得了。开箱即用的 Backstage 包含:
- 软件目录: 用于治理所有软件，如微服务、库、数据管道、网站和 ML 模型；
- 软件模板: 用于疾速启动新我的项目，并依据组织的最佳实际对工具进行标准化；
- 文档: 采纳 ” 像编写代码一样编写文档 ” 的办法，轻松创立、保护、查找和应用技术文档；
- 一直倒退的开源插件生态系统，进一步扩大了 Backstage 的可定制性和性能。
Backstage 的架构非常灵活: 前端应用 React/TypeScript 编写，后端应用 Node.js，还能够通过增加插件来扩大性能。
更重要的是，Backstage(由 Spotify 创立)当初由云原生计算基金会 (CNCF) 作为孵化级我的项目托管，这意味着咱们能够取得想要的所有社区反对。它还设有办公时间，能够在每周四加入互动，精确理解开源平台如何进步开发人员的效率和体验。
说得够多了。明天咱们将从头开始，本人构建一个开发者门户。实现本教程后，能够应用带有内置平安 CI 工作流的模板来疏导一个新服务，查看 CI 状态，并在同一个中央查看该服务的文档。
废话少说，开始吧。
3. 构建门户网站
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当初应该曾经建设并运行了门户网站！就这么简略！当初能够浏览一下，感受一下软件目录、模板、文档和其余货色:
不过目前还没什么用。咱们持续配置。
4. GitHub 认证与集成
因为开发者门户将负责疏导新仓库，因而须要 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 var4.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。
5. 创立模板
接下来筹备软件模板，用于疾速启动一项新服务。
模板应蕴含以下内容:
- 服务通用的根本源代码 / 目录构造
- 一些文档
- 测试 / 构建 / 部署服务的 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 服务器。
6. 把所有货色放在一起
当初，咱们曾经筹备好了所有，是时候一睹魔法的风采了。
拜访 http://localhost:3000，点击 “Create” 按钮，抉择咱们的模板：
输出必要信息。对于 GitGuardian API 密钥，请在此处创立：https://dashboard.gitguardian.com/api/personal-access-tokens。
所有就绪后，点击 “ 下一步 ”，神奇的事件就会产生:
当初所有都应该创立好了。
咱们能够在目录中查看:
咱们还创立并提供了文档:
最初看看 CI 的状态:
流水线仿佛曾经胜利实现，咱们能够点击查看更多细节，包含具体步骤和日志。如果你更喜爱在 CI 软件 (这里是 GitHub Actions) 中查看，能够点击相应链接跳转。
上述示例残缺源码能够参考 Github 仓库。
这意味着无论团队应用什么工具链，团队成员都不用记住 10 个不同工具的 10 个不同 URL，也不用始终关上这 10 个标签页。当他们须要某些信息时，只有进入开发者门户，就能取得所有信息，这正是外部开发者门户的弱小之处。
7. 小结
在教程的第一局部，咱们介绍了开发者门户网站的性能，学习如何应用开源 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 多平台公布