今天介绍一款非常好用的开发者门户系统，由Spotify主导设计Backstage开放平台，目前已从CNCF孵化毕业，受到越来越多企业的欢迎

背景

对于负责开发维护的开发人员来说，其产出了越来越多的项目成果，对项目的资源依赖和信息掌握就变得越来越模糊。
此外当需要查看某个服务的信息，常常需要在github、jenkins、confluence、grafana、kubernetes。。。不同工具平台之间切换，搞得疲惫不堪。

他们需要这么一个服务于开发人员的以服务为核心，能覆盖周边所有相关资源的管理维护平台
对团队负责人或企业领导来说，如何把一些好的团队技术成果推广到其他团队是一件困难的事情。也亟需打造一个打通能力提供者和能力消费的沟通平台，让潜在的能力消费者能够搜索感兴趣的服务，并通过查看设计文档、使用文档、API、负责联系人等关键信息判断是否适合自身的需要

而backstage即是具备解决这些问题的开放平台。作为CNCF的孵化项目，Backstage是一个开箱即用的平台服务，可用于管理所有的软件(System、Component、Resource、Api、TechDocs等)，并且提供了许多的plugin，让这个平台可以无限延伸，受到越来越多的公司青睐。

Backstage

Overview

Backstage(https://backstage.io/)是用于构建开发人员门户的开放平台。Backstage由一个集中的软件目录提供支持，它可以梳理您的微服务和基础设施相互关联，并使您的产品团队能够快速交付高质量的代码，而不影响自主权。

Backstage能将所有基础设施工具、服务和文档统一起来，从而从端到端创建一个更合理的开发环境。

Backstage Demo入口: https://backstage.io/demos

架构

介绍文档: https://backstage.io/docs/overview/architecture-overview

Getting Started

本次我们着重体验Backstage的基础核心功能-Software Catalog，以及软件模板-Software Templates和技术文档-TechDocs功能。

先决条件

确保环境已安装: NodeJS、yarn、Docker、curl/wget、Git、PostgreSQL、

本地安装

本次安装环境为自用windows10系统的PC机

• 执行以下命令安装backstage,

npx @backstage/create-app

安装过程中需要输入你的backstage应用名称，如my-backstage-app

• 配置使用PostgreSQL

进入my-backstage-app的目录，编辑app-config.yaml文件，将SQLite换成Postgres

app-config.yaml

backend:
  database:
-    client: better-sqlite3
-    connection: ':memory:'
+    # config options: https://node-postgres.com/api/client
+    client: pg
+    connection:
+      host: ${POSTGRES_HOST}
+      port: ${POSTGRES_PORT}
+      user: ${POSTGRES_USER}
+      password: ${POSTGRES_PASSWORD}
+      # https://node-postgres.com/features/ssl
+      #ssl: require # see https://www.postgresql.org/docs/current/libpq-ssl.html Table 33.1. SSL Mode Descriptions (e.g. require)
+        #ca: # if you have a CA file and want to verify it you can uncomment this section
+        #$file: <file-path>/ca/server.crt

• 启动my-backstage-app

在应用目录下，执行以下命令启动backstage

yarn dev

待提示成功打开浏览器，输入:http://localhost:3000打开页面

整合github

整合使用github登录认证

• 在github创建Oauth App

提前准备一个github账号，进入账号的'setting'页面,点击'Developer settings'，选择'OAuth Apps',创建一个OAuth App，名称自拟，按下图进行配置

• 在backstage中添加你的OAuth App配置

编辑app-config.yaml文件

app-config.yaml

auth:
  # see https://backstage.io/docs/auth/ to learn about auth providers
  environment: development
  providers:
    github:
      development:
        clientId: YOUR CLIENT ID
        clientSecret: YOUR CLIENT SECRET

在backstage前端添加github的登陆支持

编辑packages/app/src/App.tsx文件，在import的最后一行添加

import { githubAuthApiRef } from '@backstage/core-plugin-api';
import { SignInPage } from '@backstage/core-components'; 

在const app = createApp({apis,的下一行添加

App.tsx

components: {
  SignInPage: props => (
    <SignInPage
      {...props}
      auto
      provider={{
        id: 'github-auth-provider',
        title: 'GitHub',
        message: 'Sign in using GitHub',
        apiRef: githubAuthApiRef,
      }}
    />
  ),
},

重新启动，访问http://localhost:3000,页面如下。点击'SIGN IN'，弹出登录github的新窗口进行认证

集成github

由于本次使用了github存储catalogEntity数据，托管代码等，我们需要设置github的集成。

• 在github生产Access Token

登录github，进入账号的'setting'页面,点击'Developer settings'，选择'Personal access tokens',生成一个token，名称自拟,设置scope,和有效期，如下图

• 在backstage中添加你的Access Token配置

编辑app-config.yaml文件

app-config.yaml

integrations:
  github:
    - host: github.com
      token: ghp_urtokendeinfewinfiwebfweb # this should be the token from GitHub

重新启动backstage，即可进行register 或create 一个component。以下是使用Catalog自带的'Example Node.js Template'创建Component的流程实例，可见其能自动为我们在github中创建相应Repo

已有服务注册到Backstage

在本章节以开源系统xxl-job为例，演示如何将已有项目注册到backstage。

准备服务相关Entity

为了统一管理我们的应用信息，我们在github中创建一个Repo,假如它名称是backstage-commons。我们先在其中创建两个yaml，来存放那些我们觉得今后应该给devops team统一管理的那些Entitt,比如是System、Group等

• 注册User、Group到CatalogEntity

global-org.yaml

---
# https://backstage.io/docs/features/software-catalog/descriptor-format#kind-user
apiVersion: backstage.io/v1alpha1
kind: User
metadata:
  name: shaliuchen123
spec:
  profile:
    displayName: shaliuchen123
    email: shaliuchen123@xxx.com.cn
    picture: https://example.com/staff/jenny-with-party-hat.jpeg
  memberOf: [DevOps-Team]
---
# https://backstage.io/docs/features/software-catalog/descriptor-format#kind-group
apiVersion: backstage.io/v1alpha1
kind: Group
metadata:
  name: Admin-Team
  description: admin team
spec:
  type: root
  children: [DevOps-Team]
---
# https://backstage.io/docs/features/software-catalog/descriptor-format#kind-group
apiVersion: backstage.io/v1alpha1
kind: Group
metadata:
  name: DevOps-Team
spec:
  type: team
  profile:
    displayName: DevOps Team
    email: devops-team@xxx.com.cn
    picture: https://example.com/groups/bu-infrastructure.jpeg
  children: [SharedService-Team]
  members: [guest]
---
# https://backstage.io/docs/features/software-catalog/descriptor-format#kind-group
apiVersion: backstage.io/v1alpha1
kind: Group
metadata:
  name: SharedService-Team
spec:
  type: team
  profile:
    displayName: DevOps Team
    email: sharedservice-team@xxx.com.cn
    picture: https://example.com/groups/bu-infrastructure.jpeg
  children: []
---
# https://backstage.io/docs/features/software-catalog/descriptor-format#kind-group
apiVersion: backstage.io/v1alpha1
kind: Group
metadata:
  name: Infrastructure-Team
spec:
  type: team
  children: []

在Backstage 注册Componet

通过的Backstage的Register an existing ...按钮，copy yaml链接导入上面定义的若干Group、User。
默认情况下，这是不允许的，我们通过编辑app-config.yaml文件中的catalog.rules.-allow添加对Group、User的支持

· 注册System、API到Catalog

global-application

---
# https://backstage.io/docs/features/software-catalog/descriptor-format#kind-system
apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: IDP
spec:
  owner: SharedService-Team
---
# https://backstage.io/docs/features/software-catalog/descriptor-format#kind-system
apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: SampleApplication
spec:
  owner: DevOps-Team
---
# https://backstage.io/docs/features/software-catalog/descriptor-format#kind-api
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: SampleApplication
spec:
  type: openapi
  lifecycle: production
  owner: DevOps-Team
  system: SampleApplication
  definition: 
     $text: http://localhost:8081/v2/api-docs

如同上一步，我们将这些System、API注册到Backstage

• 将已有服务和swagger文档注册到Backstage

我们在backstage-commons的目录中创建一个xxl-job的目录，目录内创建一个catalog-info.yaml文件

catalog-info.yaml

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: xxl-job-admin
description: xxl-job-admin
# Example for optional annotations
annotations:
github.com/project-slug: shaliuchen/xxl-job
backstage.io/techdocs-ref: dir:.
tags:
- java
links:
- url: https://github.com/shaliuchen123/xxl-job
title: sourceCode
icon: github
- url: https://shared-job-admin-uat.unilever-china.azure/xxl-job-admin/toLogin
title: portal
icon: dashboard
spec:
type: service
owner: SharedService-Team
lifecycle: production
system: XXL-JOB
consumesApis: [springboot-sample-service]

---
# https://backstage.io/docs/features/software-catalog/descriptor-format#kind-system
apiVersion: backstage.io/v1alpha1
kind: System
metadata:
name: XXL-JOB
spec:
owner: SharedService-Team

上面定义了一个xxl-job-admin的component,标注了源码位置、xxl-job的登陆页面、调用的API信息，和一个XXL-JOB的System

如同上一步，我们将这些System、API注册到Backstage,效果如下

创建TechDocs文档

TechDocs是Spotify直接内置在Backstage中的docs-like-code解决方案。开发者他们的文档编写在 Markdown 文件中，这些文件与他们的代码一起存在,仅需少量配置即可在Backstage中在线查看该文档。Backstage在markdown内容发生变化时，动态更新TechDocs站点内容。生成文档默认存储在本地，官方推荐将生成文档存储在AWS S3或Azure Blob Storage等云存储中。

安装并配置TechDocs插件

如果尚未安装TechDocs插件，使用前需要先安装。安装后，可在app-config.yarm中进行如下配置

app-config.yarm

# Reference documentation http://backstage.io/docs/features/techdocs/configuration
# Note: After experimenting with basic setup, use CI/CD to generate docs
# and an external cloud storage when deploying TechDocs for production use-case.
# https://backstage.io/docs/features/techdocs/how-to-guides#how-to-migrate-from-techdocs-basic-to-recommended-deployment-approach
techdocs:
  builder: 'local' # Alternatives - 'external'
  generator:
    runIn: 'docker' # Alternatives - 'local'
  publisher:
    type: 'local' # Alternatives - 'googleGcs' or 'awsS3'. Read documentation for using alternatives.
    local:
      # (Optional). Set this to specify where the generated documentation is stored.
      publishDirectory: 'c:/path/to/local/directory'

编写文档

默认情况下，Backstage推荐你的文档与代码存放在一起，以普通maven项目为例，其目录结构如下：

docs为你的markdown文档的存放目录，一般默认主页文档名称为index.md

发布文档

其中catalog-info.yaml为register到backstage的配置，mkdocs.yml为TechDocs的配置

catalog.info.yaml

metadata:
  annotations:
    backstage.io/techdocs-ref: dir:.

mkdocs.yml

site_name: 'example-docs'

nav:
  - Home: index.md

plugins:
  - techdocs-core

在backstage刷新等待片刻后，即可看到效果

创建模板

Backstage自带了若干个软件模板。一方面可以确保创建的Component能够自动注册到backstage，同时也能够起到scaffold的功能，快速创建一个统一规范的应用程序，并最终将所有生成内容提交到远程git仓库。

定义模板

以下是backstage提供的Spring Boot gRPC Service 模板。

template.yaml

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
name: springboot-template
title: Spring Boot gRPC Service
description: Create a simple microservice using gRPC and Spring Boot Java
tags:
- recommended
- java
- grpc
spec:
owner: service@example.com
type: service

parameters:
- title: Provide some simple information
required:
- component_id
- owner
- java_package_name
properties:
component_id:
title: Name
type: string
description: Unique name of the component
ui:field: EntityNamePicker
java_package_name:
title: Java Package Name
type: string
description: Name for the java package. eg (io.backstage.blah)
description:
title: Description
type: string
description: Help others understand what this website is for.
owner:
title: Owner
type: string
description: Owner of the component
ui:field: OwnerPicker
ui:options:
allowedKinds:
- Group
- title: Choose a location
required:
- repoUrl
properties:
repoUrl:
title: Repository Location
type: string
ui:field: RepoUrlPicker
ui:options:
allowedHosts:
- github.com

steps:
- id: template
name: Fetch Skeleton + Template
action: fetch:template
input:
url: ./skeleton
copyWithoutRender:
- .github/workflows/*
values:
component_id: ${{ parameters.component_id }}
description: ${{ parameters.description }}
artifact_id: ${{ parameters.component_id }}
java_package_name: ${{ parameters.java_package_name }}
owner: ${{ parameters.owner }}
destination: ${{ parameters.repoUrl | parseRepoUrl }}
http_port: 8080

- id: publish
name: Publish
action: publish:github
input:
allowedHosts: ["github.com"]
description: This is ${{ parameters.component_id }}
repoUrl: ${{ parameters.repoUrl }}

- id: register
name: Register
action: catalog:register
input:
repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
catalogInfoPath: "/catalog-info.yaml"

output:
links:
- title: Repository
url: ${{ steps.publish.output.remoteUrl }}
- title: Open in catalog
icon: catalog
entityRef: ${{ steps.register.output.entityRef }}

定义了使用模板的步骤以及定义一些变量，

作为scaffold的代码目录结构，基本上是一个标准的maven项目结构

添加配置

在app-confing.yaml添加并编辑以下全局配置，

app-config.yaml

app-config.yaml  
scaffolder:
  defaultAuthor:
    name: M.C. Hammer # Defaults to `Scaffolder`
    email: hammer@donthurtem.com # Defaults to `scaffolder@backstage.io`
  defaultCommitMessage: "Initial commit by backstage'

引入上面的template.yaml位置

app-config.yaml

catalog:
  locations:
    - type: url
      target: https://github.com/backstage/software-templates/blob/main/scaffolder-templates/springboot-grpc-template/template.yaml
      rules:
        - allow: [Template]
    - type: file
      target: template.yaml # Backstage will expect the file to be in packages/backend/template.yaml:

重启后可查看该Software Template

使用模板

其他实用插件功能

• CI/CD
• Kubernetes
• Monitor
• Azure Resources
• ... ...

结束语

Backstage在不影响已有代码结构的情况下，通过少量的配置文件，能够很好的组织所有的软件资源，提供良好的用户体验，与可拓展的强大能力，达到了预期要求。

当然假如需引入Backstage，作为生产可用的开放平台，还需要投入更多的精力去解决与自身公司体系融合的问题