Skip to main content

编写Backstage配置文件

文件格式​

配置以 YAML 格式存储在app-config.yaml该配置由前端和后端共享，看起来像这样：

app:
  title: Backstage Example App
  baseUrl: http://localhost:3000

backend:
  listen: 0.0.0.0:7007
  baseUrl: http://localhost:7007

organization:
  name: CNCF

proxy:
  /my/api:
    target: https://example.com/api/
    changeOrigin: true
    pathRewrite:
      ^/proxy/my/api/: /

配置文件通常会签入并存储在包含 Backstage 应用程序其他部分的 repo 中。

每个 backstage 应用可用的特定配置取决于安装了哪些插件和软件包。 要查看自己项目的配置参考，包括哪些配置键可用以及前台是否需要，请使用以下命令：

yarn backstage-cli config:docs

环境变量覆盖​

可以使用前缀为APP_CONFIG_环境变量名称中前缀之后的所有内容都将作为配置密钥，其中包括_改为.例如，要覆盖app.baseUrl值，设置APP_CONFIG_app_baseUrl环境变量的值。

环境变量的值会被解析为 JSON 格式，但如果解析失败，它又会被解释为字符串。"false"，您需要用双引号将其括起来，例如export APP_CONFIG_example='"false"'.

虽然使用环境变量重写来提供大量配置值很有诱惑力，但我们建议尽量少用。 尽量坚持使用配置文件，只在诸如在暂存和生产环境中重复使用部署工件时才使用环境变量。

请注意，环境变量也适用于前端配置。@backstage/cli用于本地开发，并在生产构建中由提供前端服务的 nginx 容器的入口点注入。

配置文件​

可以有多个配置文件(捆绑和/或远程*)，既可支持不同的环境，也可定义特定软件包的本地配置。 要加载的配置文件使用--config <local-path|url>标记，可以加载任意数量的文件。 路径是相对于执行进程的工作目录而言的，例如package/backend这意味着在运行后端时，要选择 repo 根目录中的配置文件，需要使用--config ../../my-config.yaml配置服务器上的配置文件则使用--config https://some.domain.io/app-config.yaml

注注意：在传递 URL 的情况下，还需要在 loadBackendConfig 调用中设置远程选项。

如果没有config标记时，默认行为是加载app-config.yaml如果存在的话、app-config.local.yaml在提供的项目设置中、app-config.local.yaml是.gitignore'd，使其成为添加配置重载和本地开发Secret的好地方。

请注意，如果提供了任何配置标志，默认的app-config.yaml文件不会被加载，要包含这些文件，需要明确地用一个标志将其包含在内，例如

yarn start --config ../../app-config.yaml --config ../../app-config.staging.yaml --config https://some.domain.io/app-config.yaml

所有加载的配置文件都会按照以下规则合并在一起：

  • 配置具有不同的优先级，优先级越高，意味着可以替换优先级越低的配置中的值。 * 原始值会被完全替换，数组及其所有内容也是如此。 * 对象会被深度合并，这意味着如果包含的任何配置中包含给定路径的值，都会被找到。

配置的优先级依次由以下规则决定：

  • 如果没有提供配置标志，"app-config.local.yaml "的优先级高于 "app-config.yaml"。

包括和动态数据​

通过前缀为$要加载外部配置值，可提供一个带有特殊包含键的对象，例如$env或$file支持的包含密钥的完整列表见下文。 例如，下面将读取配置密钥backend.mySecretKey从环境变量MY_SECRET_KEY:

backend:
  mySecretKey:
    $env: MY_SECRET_KEY

通过上述配置，调用config.getString('backend.mySecretKey')将返回环境变量MY_SECRET_KEY所有包含的内容都会在启动时加载，因此更改文件或环境变量的内容不会在运行时反映出来。

下面列出了当前支持的加载包含的方法。

Env 包括​

会从环境变量中读取字符串值。 例如，以下配置会从MY_SECRET环境变量。

$env: MY_SECRET

但请注意，使用环境变量替换而不是

文件包括​

该命令从文本文件的全部内容中读取字符串值。 文件路径相对于源配置文件。 例如，下面的命令将读取my-secret.txt相对于配置文件本身：

$file: ./my-secret.txt

包括文件​

$include关键字可用于从外部文件加载配置值。 它能够从.json,.yml和.yaml也可以将 URL 片段 (#) 使用以点分隔的键列表，指向文件中给定路径上的值。

例如，以下内容如下my-secret-key从my-secrets.json:

$include: ./my-secrets.json#deployment.key

示例my-secrets.json锉刀

{
  "deployment": {
    "key": "my-secret-key"
  }
}

环境变量替换​

配置文件通过一个${MY_VAR}例如

app:
  baseUrl: https://${HOST}

请注意，所有环境变量都必须可用，否则整个配置值的值将为undefined.

可以使用$${...}将解析为${...}.

结合包含和环境变量替换​

可以将 "包含 "和 "环境变量替换 "结合起来，以读取特定环境的Secret配置。 例如

integrations:
  github:
    - host: github.com
      apps:
        - $include: secrets.${BACKSTAGE_ENVIRONMENT}.yaml

示例secrets.prod.yaml:

appId: 1
webhookUrl: https://smee.io/foo
clientId: someGithubAppClientId
clientSecret: someGithubAppClientSecret
webhookSecret: someWebhookSecret
privateKey: |
  -----BEGIN RSA PRIVATE KEY-----
  SomeRsaPrivateKey
  -----END RSA PRIVATE KEY-----