铁科经纬（西安）信息科技有限公司

语言

开发者门户

开发者门户是面向开发者提供的一站式云端平台，即开即用，随时随地在云端交付软件全生命周期，覆盖从代码创建、流水线、部署、API管理、到运行监控全方位的开发支撑，提供软件研发流程的端到端支持，全面支撑落地应用开发。使企业中的所有软件以及谁拥有该软件都可被发现，不再有孤儿软件隐藏在软件生态系统的黑暗角落。

主要功能

主要功能

在一个位置管理组织内所有软件

统一概述，每个团队都可以查看他们所拥有的服务和相关资源

可发现，不在有印在在技术堆栈中的孤儿软件

文档

技术文档管理，支撑从模板创建，直接对接应用组件

使用开发者门户软件模板时，项目会自动获得技术文档站点

代码和文档位于同一位置，可以在更新代码时直接更新文档

标准

一键式部署，存储库在git中自动配置，并且流水线已自动配置

根据标准构建，使用组织内最佳实践技术栈直接创建

可发现，不在有隐藏在技术堆栈中的孤儿软件

管理服务

对接kubernetes，围绕服务所有者提供服务

在统一视图中获取所有服务部署，无需再梳理服务列表

多个K8，一个UI，从本地测试迁移到生产环境，无需切换仪表板

概述

注册与登录

1641371892624

用户输入注册好的用户名和密码，登录持续交付平台。开发测试平台使用单点登录模式，您登录任一平台即可操作。若您没有开发测试平台账号，点击【注册】按钮完成账号注册。

服务目录

使用开发者门户管理的对象（软件、文档、类库等等）都可以在服务目录中查询。服务目录展示当前平台所有使用者管理的服务对象。进入系统，可以看到当前平台中的所有组件列表、包括微服务、微前端、API、文档和工具等。

可在左侧导航栏中按类型筛选服务实体。默认情况下，软件目录显示已登录用户团队拥有的组件，但是，也可以切换到【全部】，以查看企业内的所有组件，支持基本的搜索和筛选，方便用户查找目标组件。

1641539501382

YAML配置

开发者门户通过yaml配置服务实体进行定义和管

1641540197706

部分字段释义

所有类型（kind）通用字段：metadata

​ 例：visits-tracking-service，CircleciBuildsDumpV2_avro_gcs

kind：component

component描述软件组件。它通常与构成组件的源代码密切相关，并且应该是开发人员可能认为的"软件单元"，通常具有独特的可部署或可链接的工件。软件研发工作的核心便是component，例如一个微服务，一个前端网站。component的部分字段如下。

kind：Template

component描述软件组件。它通常与构成组件的源代码密切相关，并且应该是开发人员可能认为的"软件单元"，通常具有独特的可部署或可链接的工件。软件研发工作的核心便是component，例如一个微服务，一个前端网站。component的部分字段如下。

kind：API

项目

若您同时使用了项目协作平台，这里的项目便是项目协作平台的项目，也是项目协作平台与开发者门户工作对接的桥梁。 如需添加项目，请从项目协作平台中添加。

一个项目有一个或多个产品，一个产品有一个或多个应用，一个应用由一个或多个组件组成。在【项目】中，可以看到使用当前平台的项目，通过项目可以进入到项目包含的组件中。

1641550802069

组件

什么是组件

component中的每一种类型实体都是一个组件，常用的组件有以下四种：website、service、documentation、API，您可以自定义组件类型。每一个组件都可以在服务目录中查询到。

1641551063123

组件的添加

组件有两种添加方式：基于模板从无到有创建、通过注册将已有组件纳入开发者门户。

一：通过模板添加

1641551191464

二：注册现有组件

1641551244686

注册组件需要您在组件源代码根目录中添加catalog-info.yaml配置，通过该配置，开发者门户将解析当前组件数据完成纳管，并对您之后的操作进行同步更新。

模板

模板可以帮助您统一企业技术架构，将推广和复用的技术栈在开发者门户中作为模板，将代码框架，以及某些 变量中的模板，发布到指定位置。帮助开发人员快速创建组件，或是页面，包括单独发布的HTML页面（以markdown文档发布）。

模板以yaml的形式存储在代码仓库中，存储位置联系管理员获取。使用描述模板及其元数据的小定义创建模板。一个简单的模板例子：

1641557870060

模板配置参考YAML配置中的kind：Template。

Website/Service全生命周期管理

创建

通过模板添加

1641551191464

【创建中】找到对应的模板，点击选择，进入创建流程，可以创建的组件类型有：前端工程、后端服务、后端微服务、文档、API、库（前端组件、工具等）。创建页面对于每个模板可能看起来不同，以spring boot gRPC为例

1641558041222

输入组件名称、对应的镜像包名称、填写描述以便平台用户可以了解此服务功能、选择组件所有者，可以是团队、组织或个人。填写完成点击【下一步】进入代码仓库配置。此处页面中的字段即使yaml配置中的spec.parameters字段值。此处的步骤，即spec.steps配置。

1641558202250

下拉选择存储库主机URL；输入需要创建的存储库所有者：可以输入的字段为gitlab中group名称（将会创建在此group下创建）、gitlab用户名（将会在此用户命名空间下创建）；输入存储库名称，对应代码仓的repo，输入完成点击【下一步】进行CI配置。

1641558253445

与CI配置相同，选择使用的模板，并基于模板修改CD配置。点击【下一步】预览信息，可以返回修改，如确定不需要再修改信息，点击创建完成。

1641558275899

创建过程日志在界面中输出，可查看不同阶段输出日志，当创建完成，点击【repo】跳转到代码仓。

1641558287458

上述模板对应的配置为：

apiVersion: backstage.io/v1beta2
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: 提供一些简单的信息
      required:
        - component_id
        - owner
        - java_package_name
      properties:
        component_id:
          title: 名称
          type: string
          description: 组件的唯一名称
        java_package_name:
          title: java包的名称
          type: string
          description: java包的名称。eg (io.backstage.blah)
        description:
          title: 描述
          type: string
          description: 帮助其他人了解此网站的用途。
        owner:
          title: 所有者
          type: string
          description: 组件的所有者
          ui:field: OwnerPicker
          ui:options:
            allowedKinds: 
              - Group
    - title: 选择存储库  
      required:
        - repoUrl
      properties: 
        repoUrl:
          title: 存储库位置
          type: string
          ui:field: RepoUrlPicker
          ui:options:
            allowedHosts:
              - gitlab.dev.rdev.tech
    - title: 选择流水线模板
      required:
        - fileID
      properties:
        fileID:
          title: 模板
          type: string
          description: 选择流水线模板
          ui:field: CICDPicker
          ui:options:
            rows: 5

  steps:
    - id: template
      name: 生成应用
      action: fetch:template
      input:
        url: ./skeleton
        # copyWithoutRender:
        #   - .github/workflows/*
        cookiecutterCompat: true
        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: '{{ parseRepoUrl parameters.repoUrl }}'
          http_port: 8080

    - id: publish
      name: 推送
      action: publish:gitlab
      input:
        allowedHosts: ['gitlab.dev.rdev.tech']
        description: '这是 {{ parameters.component_id }}'
        repoUrl: '{{ parameters.repoUrl }}'

    - id: register
      name: 注册应用
      action: catalog:register
      input:
        repoContentsUrl: '{{ steps.publish.output.repoContentsUrl }}'
        catalogInfoPath: '/catalog-info.yaml'

    - id: create
      name: 配置流水线
      action: configuration:pipeline
      input:
        name: '{{ parameters.name }}'
        description: '{{ parameters.description }}'
        owner: '{{ parameters.owner }}'
        repoUrl: '{{ parameters.repoUrl }}'
        fileID: '{{ parameters.fileID }}'
        component: '{{ parameters.component_id }}'
        
  output:
    remoteUrl: '{{ steps.publish.output.remoteUrl }}'
    entityRef: '{{ steps.register.output.entityRef }}'

注册已有组件

在首页点击【创建服务】进入跟踪微服务，此功能是将已经存在的一个业务实体（微服务、微前端、组件等）注册进微服务平台。

1641558462489

前置条件：

组件实体所在存储库的根目录中包含以下内容的文件：catalog-info.yaml

1641558506952

在【注册现有组件】页面，输入组件的URL，此URL为改组件代码仓中catalog.ymal文件地址。如：https://gitlab.dev.rdev.tech/micro-service/bktest90/-/blob/master/catalog-info.yaml

1641558576151

输入完成后点击【分析】进入下一步，预览文件，确认信息无误后点击【导入】完成注册。

1641558602386

代码管理

进入一个前端组件或后端组件（类型为website或service），可以获取到此应用的生命周期数据。

点击MERGE REQUEST可以查看该组件代码提交情况。

1641558704236

自动构建（CI）

代码扫描

对代码进行自动化静态扫描，若不通过则终止构建，扫描结果如下；若无代码扫描结果并提示缺少注释，在缺定您希望开启代码扫描后按照提示在组件的catalog-info.yaml文件中添加相应注释即可开启

1641558809151

除静态扫描外，还可以检测出代码中的TODO代码段.

1641558835242

自动打包镜像

在CI/CD页面显示此组件的流水线记录

1641558902003

镜像仓库

​ 构建完成，镜像被推倒镜像仓库中，可以在HARBOR页面看到镜像信息

1641558925697

自动部署（CD）

流水线构建完成，触发自动部署，部署情况显示在ARGOCD页面。

1641558983261

运行监控

镜像成功部署后将会自动启动，对应的pod信息可以在kubernetes页面看到。这是 是一个面向服务所有者，而不是集群管理员的需求。无论这些服务以何种方式或位置部署，无论是在本地主机还是生产环境，开发人员都可以轻松检查其服务的运行状况。

1641559024184

API管理

API通常来自于组件，在微服务架构中，大型服务都被拆分成了独立的微服务，每个微服务通常会以RESTFUL API的形式对外提供服务。通过API，我们可以清楚的知道企业内已经提供的接口服务，一方面减少重复开发的工作，另一方面可以了解到不同的微服务可以提供哪些服务，以及在api网关管理中了解api的使用情况及链路追踪。

可以在【APIs】中看到平台所有后端服务对外提供的接口。

1641559057320

注册API需要按照API的要求格式编写yaml配置文件。其中，definition字段选填，内容是此API的接口详情，通过definition字段的描述，开发者门户可以解析此接口的类型及输入输出，并可以做简单接口测试。

基础配置：

1641559082648

接口配置：

1641559100788

​ API与服务的关系需要在服务的catalog-info.yaml中配置。如下例中名为petstore的service提供3个api，通过providersApis描述此服务提供的接口，在服务详情中，可以看到提供的API列表，同时，在API的详情中可以看到提供此接口的服务是petstore 。

1641559362307

通过创建组件入口进入注册页面，在注册页面中的URL字段中输入API对应的ymal地址，如图,底图为某接口配置文件，小窗为微服务平台注册组件页面。

一个yaml地址示例：https://gitlab.dev.rdev.tech/micro-service/micro-service-templates/-/blob/master/apis/petstore-api.yaml

1641559421525

通过注册API，可以在【APIs】中看到该接口。也可直接在此处查看平台已有的接口。进入查看某一接口，可以获取此接口描述、代码地址（若有权限可以查看其代码仓中源代码）、提供此接口的服务，以及订阅此接口的消费实体。

1641559469215

若在API中定义了definition字段，则可以在API详情中的【定义】中看到该接口的描述。

点击【try it out】可以查询该接口返回值

1641559491256

技术文档

技术文档是类似文档的代码解决方案，开发人员将技术文档编写在markdown文件中，这些文件与他们的代码一起存在。

特征

•与软件环境无关，无论软件环境如何设置，都可以部署技术文档

•从服务页面中可以查找服务的的技术文档

•只需编写markdown文档即可创建用于任何目的的纯文档站点

•搜索和查找文档

创建基本文档设置

技术文档建立在代码方法等文档上，即，文档应该靠近代码。我们强烈建议您将文档添加在代码目录中。

开发者门户中应用默认添加了一组软件模板，所有这些软件模板都包含启动和运行技术文档站点并开始文档别写所需的一切

文档示例——服务文档

1641559691179

文档示例——单站点文档

1641559721652

为现有文档实体启用文档

先决条件：

为文档实体所在存储库的根目录中创建一个包含以下内容的文件：mkdocs.yml

1641559785488

通过以下行添加到组件存储库根目录中来更新组件的实体描述：catalog-info.yaml

1641559820721

文档使用backstage.io/techdocs-ref注释来下载文档源文件，以生成实体的 TechDocs 站点。

在存储库的根目录中创建一个文件夹，其中至少包含一个文件。（如果添加更多 markdown 文件，请确保更新 mkdocs.yml 文件中的导航，以便为文档获取正确的导航。/docsindex.md

提交更改，打开拉取请求合并，将获得更新的文档。

例如，某单文档站点在代码仓库中的目录如下：

1641561919716

1.在左侧导航栏中点击【创建】——【注册现有组件】进入注册页面

1641562012368

2.在注册页面中填写第一步URL，此地址为该文档实体的catalog-info.yaml文件地址。如https://gitlab.dev.rdev.tech/dev_platform/backstage_mkdocs/-/blob/master/catalog-info.yaml

1641562044250

3.在输入URL之后点击【分析】开发者门户将会解析该文件，识别当前文档实体并回显相关信息

1641562065602

4.点击【导入】即可将该实体添加到服务目录中

1641562085033

使用模板创建

当您仅需要发布一个文档而非代码的技术文档是，例如：入门教程。可以通过文档模板创建，该模板仅报含文档配置和牧人标记文件的组件。点击【创建】中的documentation类型的模板卡片中的【选择】，完成从模板创建文档

1641562126389

在创建流程中，输入相关的信息，这里的字段与service是一致的

1641562157677

在最后一步预览信息，确认信息输入正确，点击【创建】即可完成文档创建，在服务目录中可以查看到创建的文档。

1641562184966

APISIX

什么是APISIX

APISIX 是一个云原生、高性能、可扩展的微服务 API 网关。

它是基于 Nginx 和 etcd 来实现，和传统 API 网关相比，APISIX 具备动态路由和插件热加载，特别适合微服务体系下的 API 管理。

为什么选择APISIX

APISIX 是基于云原生的微服务 API 网关，它是所有业务流量的入口，可以处理传统的南北向流量，也可以处理服务间的东西向流量，也可以当做 k8s ingress controller 来使用。

APISIX 通过插件机制，提供动态负载平衡、身份验证、限流限速等功能，并且支持你自己开发的插件。

APISIX可以为您做什么

可以把 Apache APISIX 当做流量入口，来处理所有的业务数据，包括动态路由、动态上游、动态证书、

A/B 测试、金丝雀发布(灰度发布)、蓝绿部署、限流限速、抵御恶意攻击、监控报警、服务可观测性、服务治理等。

路由

工作原理

创建一个 路由（Route ）并与上游服务（通常也被称为Upstream或后端服务）绑定，当一个 请求（Request） 到达 Apache APISIX 时，Apache APISIX 就会明白这个请求应该转发到哪个上游服务中。

因为我们为 Route Apache APISIX Route

1641562336724

这条路由配置意味着，当它们满足下述的 所有 规则时，所有匹配的入站请求都将被转发到 httpbin.org:80 这个上游服务：

•请求的 HTTP 方法为 GET。

•请求头包含 host 字段，且它的值为 example.com。

•请求路径匹配 /services/users/， 意味着任意的子路径，例如 /services/users/getAll?limit=10。

当这条路由创建后，我们可以使用 APISIX 对外暴露的地址去访问上游服务。

路由Route ，通过定义一些规则来匹配客户端的请求，然后根据匹配结果加载并执行相应的 插件，并把请求转发给到指定 Upstream。

Route 中主要包含三部分内容：匹配规则(比如 uri、host、remote_addr 等)，插件配置(限流限速等)和上游信息。 请看下图示例，是一些 Route 规则的实例，当某些属性值相同时，图中用相同颜色标识。

1641562366288

创建

进入APISIX——路由，点击【创建】按钮

1641562412155

第一步：设置路由信息

1641562437987

第二步，设置上游服务

1641562462670

第三步，插件配置

1641562477163

上游服务

工作原理

上游服务Upstream 是虚拟主机抽象，对给定的多个服务节点按照配置规则进行负载均衡。Upstream 的地址信息可以直接配置到 Route（或 Service) 上，当 Upstream 有重复时，就需要用“引用”方式避免重复了。

1641562510640

如图所示，通过创建 Upstream 对象，在 Route 用 ID 方式引用，就可以确保只维护一个对象的值了。

Upstream 的配置可以被直接绑定在指定 Route 中，也可以被绑定在 Service 中，不过 Route 中的配置 优先级更高。

•上游对象创建后，均可以被具体 Route 或 Service 引用

•为了方便使用，也可以直接把上游地址直接绑到某个 Route 或 Service

创建

进入APISIX——上游服务，点击【创建】按钮

1641562552309

输入相关基础信息，点击下一步预览，确认输入无误后点击【提交】完成创建

1641562569453

服务service

工作原理

服务Service 是某类 API 的抽象（也可以理解为一组 Route 的抽象）。它通常与上游服务抽象是一一对应的，Route 与 Service 之间，通常是 N:1 的关系，参看下图。

1641562593733

•不同 Route 规则同时绑定到一个 Service 上，这些 Route 将具有相同的上游和插件配置，减少冗余配置。

•也可以为 Route 指定不同的插件参数或上游

•注意：当 Route 和 Service 都开启同一个插件时，Route 参数的优先级是高于 Service 的。

创建

进入APISIX——服务列表，点击【创建】按钮

1641562622418

输入基本信息，选择插件并配置，预览确认无误后点击【提交】即可创建

1641562659583

消费者Consumer

工作原理

对于 API 网关通常可以用请求域名、客户端 IP 地址等字段识别到某类请求方， 然后进行插件过滤并转发请求到指定上游，但有时候这个深度不够。知道 API Consumer（消费方）具体是谁，这样就可以对不同 API Consumer 配置不同规则。

1641562682866

Consumer 是某类服务的消费者，需与用户认证体系配合才能使用。 比如不同的 Consumer 请求同一个 API，网关服务根据当前请求用户信息，对应不同的 Plugin 或 Upstream 配置。

识别消费者的过程：

1641562704037

1.授权认证：比如有 key-auth、JWT 等。

2.获取 consumer_name：通过授权认证，即可自然获取到对应的 Consumer name，它是 Consumer 对象的唯一识别标识。

3.获取 Consumer 上绑定的 Plugin 或 Upstream 信息：完成对不同 Consumer 做不同配置的效果。

创建

进入APISIX——消费者，点击【创建】按钮

1641562766685

在创建页面输入基础信息并配置插件，预览之后确认便可成功创建

1641562791521

星空体育·(中国)官方网站 | mk体育（中国）官方网站 | 开云体云APP官网入口 | 安博官网 | 安博平台 | 安博手机网页版登录入口 | 开云在线登录 | 安博在线 | 开云线上平台（集团）官方网站 |