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 DirectoryAAD凭据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 Tokenintegrations: azureBlobStorage: - accountName: ${ACCOUNT_NAME} # required endpoint: ${CUSTOM_ENDPOINT} # custom endpoint will require either aadCredentials or sasToken sasToken: ${SAS_TOKEN}方式三存储账户访问密钥Access Keyintegrations: azureBlobStorage: - accountName: ${ACCOUNT_NAME} # required endpoint: ${CUSTOM_ENDPOINT} # custom endpoint will require either aadCredentials or sasToken accountKey: ${ACCOUNT_KEY}在实体 Provider 的AzureBlobStorageEntityProviderplugins/catalog-backend-module-azure/src/providers/AzureBlobStorageEntityProvider.ts中azure/storage-blob的BlobServiceClient会按StorageSharedKeyCredentialaccountKey、SAS token 或 AAD TokenCredential 的顺序构建客户端访问容器。配置参数详解与校验规则除了上文三种凭据字段集成还支持以下参数见 config.ts 中的AzureBlobStorageIntegrationConfig类型定义参数类型说明accountNamestring存储账户名例如mystorageaccount必填项accountKeystring存储账户的主/辅访问密钥sasTokenstring共享访问签名SAS令牌用于受限访问connectionStringstring完整连接字符串包含账户名、密钥与端点信息endpointstring自定义端点必须是合法 URLendpointSuffixstring可选用于自定义域名或主权云sovereign clouds例如公有云core.windows.net、US Government 云core.usgovcloudapi.nethoststring目标主机例如blob.core.windows.net由解析逻辑自动推导aadCredentialobjectAAD 应用凭据含clientId/tenantId/clientSecret值得说明的是endpointSuffix与connectionString已纳入类型定义与解析逻辑config.ts适用于自定义域名、主权云或完整连接字符串的接入场景。主机名推导与默认值解析逻辑readAzureBlobStorageIntegrationConfig的处理规则若配置了endpoint则通过new URL(endpoint)解析出host作为匹配主机若未配置endpointhost默认为blob.core.windows.net常量AZURE_HOST见 config.ts如果所有显式集成中都不存在blob.core.windows.net主机readAzureBlobStorageIntegrationConfigs会自动追加一个默认集成项作为便利config.ts因此最简单的场景可以只写accountName与一种凭据。相互冲突的凭据会被拒绝配置解析会做严格的合法性校验违反以下规则会直接抛错对应测试见 config.test.tsendpoint不是合法 URL → 报错invalid azureBlobStorage integration config, endpoint ... is not a valid URLendpoint包含路径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 ProviderAzure 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通过DefaultAzureCredentialsManager.fromIntegrations从全局集成注册表构建凭据管理器并按accountName匹配integrations.azureBlobStorage中对应的集成配置若找不到匹配的集成会抛出 There is no Azure blob storage integration for account... 错误——因此必须先完成上文的基础集成配置校验调度配置代码层面或配置层面必须提供至少一个schedule否则抛错提示。生产环境部署时建议通过实例实例的托管身份与权限来管理这些访问凭据避免把密钥直接写死在配置文件中。小结Azure Blob Storage 集成让 Backstage Catalog 可以直接以 Azure Blob 容器作为实体来源。核心要点如下配置位于integrations.azureBlobStorageaccountName必填认证方式三选一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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考