Backstage Azure Blob Storage 集成：Locations 配置与 Catalog 实体加载指南

Backstage Azure Blob Storage 集成：Locations 配置与 Catalog 实体加载指南

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage

本文是 Backstage 中 Azure Blob Storage（存储账户）集成的配置指南，核心场景是把 Azure Blob 容器中的catalog-info.yaml等实体文件作为 Catalog 数据源接入软件目录。读完本文，你将掌握integrations.azureBlobStorage三种认证方式的完整配置、底层配置解析与校验规则、以及如何通过静态 Catalog 配置、catalog-import 插件和 Azure 实体 Provider 三种途径使用该集成。

Azure Blob Storage 集成能做什么

Backstage 的 Azure Blob Storage 集成（azureBlobStorage）支持从一个存储账户（storage account）的容器（container）中加载 Catalog 实体。实体可以有两种接入方式：

• 通过静态 Catalog 配置手动添加到catalog.locations；
• 通过 catalog-import 插件在界面上注册。

此外，该集成还配套了一个专门的实体 Provider（见下文"进阶：自动发现容器中的实体"），可定时爬取容器并自动注册匹配路径的实体，作为静态 Location 的替代方案。

从源码结构看，该集成由@backstage/integration包中的AzureBlobStorageIntegration类实现（packages/integration/src/azureBlobStorage/AzureBlobStorageIntegration.ts），它实现了通用的ScmIntegration接口，通过工厂函数读取integrations.azureBlobStorage配置并注册到全局集成注册表ScmIntegrations中（packages/integration/src/ScmIntegrations.ts）。

基础配置：在 app-config.yaml 中声明集成

要使用该集成，需要在app-config.yaml中添加配置。集成配置位于integrations.azureBlobStorage下，是一个数组，每个元素对应一个存储账户。仓库的集成包通过 readAzureBlobStorageIntegrationConfigs 读取config.getOptionalConfigArray('integrations.azureBlobStorage')，因此支持同时配置多个存储账户。

方式一：Azure Active Directory（AAD）凭据

integrations: azureBlobStorage: - accountName: ${ACCOUNT_NAME} # required endpoint: ${CUSTOM_ENDPOINT} # custom endpoint will require either aadCredentials or sasToken aadCredential: clientId: ${CLIENT_ID} tenantId: ${TENANT_ID} clientSecret: ${CLIENT_SECRET}

aadCredential下需要完整提供clientId、tenantId、clientSecret三个字段，缺一不可。在 DefaultAzureCredentialsManager.createCredential 中可以看到，当且仅当这三个字段都存在时，才会构造ClientSecretCredential（来自@azure/identity）；否则回退到DefaultAzureCredential（利用环境变量、托管身份等链式获取凭据）。

方式二：SAS Token

integrations: azureBlobStorage: - accountName: ${ACCOUNT_NAME} # required endpoint: ${CUSTOM_ENDPOINT} # custom endpoint will require either aadCredentials or sasToken sasToken: ${SAS_TOKEN}

方式三：存储账户访问密钥（Access Key）

integrations: azureBlobStorage: - accountName: ${ACCOUNT_NAME} # required endpoint: ${CUSTOM_ENDPOINT} # custom endpoint will require either aadCredentials or sasToken accountKey: ${ACCOUNT_KEY}

在实体 Provider 的AzureBlobStorageEntityProvider（plugins/catalog-backend-module-azure/src/providers/AzureBlobStorageEntityProvider.ts）中，@azure/storage-blob的BlobServiceClient会按StorageSharedKeyCredential（accountKey）、SAS token 或 AAD TokenCredential 的顺序构建客户端访问容器。

配置参数详解与校验规则

除了上文三种凭据字段，集成还支持以下参数（见 config.ts 中的AzureBlobStorageIntegrationConfig类型定义）：

参数	类型	说明
accountName	string	存储账户名，例如mystorageaccount，必填项
accountKey	string	存储账户的主/辅访问密钥
sasToken	string	共享访问签名（SAS）令牌，用于受限访问
connectionString	string	完整连接字符串，包含账户名、密钥与端点信息
endpoint	string	自定义端点，必须是合法 URL
endpointSuffix	string	可选，用于自定义域名或主权云（sovereign clouds），例如公有云core.windows.net、US Government 云core.usgovcloudapi.net
host	string	目标主机，例如blob.core.windows.net，由解析逻辑自动推导
aadCredential	object	AAD 应用凭据，含clientId/tenantId/clientSecret

值得说明的是，endpointSuffix与connectionString已纳入类型定义与解析逻辑（config.ts），适用于自定义域名、主权云或完整连接字符串的接入场景。

主机名推导与默认值

解析逻辑（readAzureBlobStorageIntegrationConfig）的处理规则：

• 若配置了endpoint，则通过new URL(endpoint)解析出host作为匹配主机；
• 若未配置endpoint，host默认为blob.core.windows.net（常量AZURE_HOST，见 config.ts）；
• 如果所有显式集成中都不存在blob.core.windows.net主机，readAzureBlobStorageIntegrationConfigs会自动追加一个默认集成项作为便利（config.ts），因此最简单的场景可以只写accountName与一种凭据。

相互冲突的凭据会被拒绝

配置解析会做严格的合法性校验，违反以下规则会直接抛错（对应测试见 config.test.ts）：

• endpoint不是合法 URL → 报错invalid azureBlobStorage integration config, endpoint '...' is not a valid URL；
• endpoint包含路径（pathname 非/）→ 报错endpoints cannot contain path；
• 同时配置accountKey与sasToken→ 报错 "Both account key and SAS token cannot be used simultaneously."；
• 同时配置aadCredential与accountKey/sasToken→ 报错 "Cannot use both Azure AD credentials and account keys/SAS tokens for the same account."。

也就是说，同一个账户下三种认证方式互斥，必须三选一。

使用集成加载 Catalog 实体

配置好integrations.azureBlobStorage后，即可通过以下途径把容器中的实体文件接入 Catalog。

途径一：静态 Catalog 配置

在catalog.locations中直接声明 Azure Blob 位置的实体文件，示例（完整字段说明见静态 Catalog 配置文档）：

catalog: locations: - type: url target: https://<accountName>.blob.core.windows.net/<containerName>/catalog-info.yaml rules: - allow: [Component, System, API, Group, User, Resource, Location]

途径二：catalog-import 插件注册

也可以在前端通过 catalog-import 插件（"Register an existing component" 流程）手动注册指向 Blob 中实体文件的 URL，由集成负责解析并读取实体内容。

途径三：自动发现容器中的实体（Entity Provider）

Azure Blob Storage 集成还提供了专门的实体 Provider，用于自动发现存储账户容器中的 Catalog 实体。适用于容器内存在多个 Catalog 文件、希望按配置路径自动爬取注册的场景，可作为静态 Location 或手动添加的替代方案。完整说明见 Azure Blob Storage Discovery。

使用前需要先安装 Azure Catalog 插件：

# 在 Backstage 根目录下执行 yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-azure

然后在后端入口注册该模块：

// packages/backend/src/index.ts backend.add(import('@backstage/plugin-catalog-backend')); backend.add(import('@backstage/plugin-catalog-backend-module-azure'));

Provider 配置按容器逐一声明：

# app-config.yaml catalog: providers: azureBlob: providerId: accountName: ${ACCOUNT_NAME} containerName: ${CONTAINER_NAME} schedule: # 同 TaskScheduleDefinition 的选项 # 支持 cron、ISO 时长、代码中使用的"人类可读时长" frequency: { minutes: 30 } # 支持 ISO 时长、"人类可读时长" timeout: { minutes: 3 }

简单场景下可以省略 provider ID，效果等同于使用default：

# app-config.yaml catalog: providers: azureBlob: accountName: ${ACCOUNT_NAME} containerName: ${CONTAINER_NAME} schedule: frequency: { minutes: 30 } timeout: { minutes: 3 }

在 providers/config.ts 的readAzureBlobStorageConfigs中可以看到：当配置项直接包含containerName时按"单配置变体"处理并使用默认 provider IDdefault；否则遍历所有 provider ID 逐个读取。每个 provider 要求accountName与containerName为必填，schedule可选。

AzureBlobStorageEntityProvider.fromConfig在实例化时会做两件事（AzureBlobStorageEntityProvider.ts）：

1. 通过DefaultAzureCredentialsManager.fromIntegrations从全局集成注册表构建凭据管理器，并按accountName匹配integrations.azureBlobStorage中对应的集成配置；若找不到匹配的集成，会抛出 "There is no Azure blob storage integration for account..." 错误——因此必须先完成上文的基础集成配置；
2. 校验调度配置：代码层面或配置层面必须提供至少一个schedule，否则抛错提示。

生产环境部署时，建议通过实例（实例的托管身份与权限）来管理这些访问凭据，避免把密钥直接写死在配置文件中。

小结

Azure Blob Storage 集成让 Backstage Catalog 可以直接以 Azure Blob 容器作为实体来源。核心要点如下：

• 配置位于integrations.azureBlobStorage，accountName必填，认证方式三选一：AAD 凭据、SAS token 或账户访问密钥；
• 三种认证方式互斥，endpoint必须是无路径的合法 URL，冲突配置会在启动解析阶段直接报错（见 config.test.ts 中的测试用例）；
• 未显式配置时默认主机为blob.core.windows.net，并支持多账户、自定义端点与主权云（endpointSuffix）；
• 使用方式包括静态 Catalog 配置、catalog-import 插件注册，以及 AzureBlobStorageEntityProvider 的定时自动发现。

更完整的实体发现配置，可继续阅读 Azure Blob Storage Discovery。

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage