Backstage 目录自动化发现Azure Blob Storage Entity Provider 实战指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本指南基于 Backstage 仓库中 Azure Blob Storage Discovery 文档系统讲解如何通过AzureBlobStorageEntityProvider自动发现存储容器中的 catalog 实体文件。你将掌握该 Provider 的配置方式、安装接入步骤、底层实现原理与测试验证方法从而用定时爬取 Blob 容器的方式替代手工维护静态 location让软件目录随存储内容自动更新。为什么需要 Blob Storage 发现能力Backstage 的软件目录Software Catalog默认通过静态 location 或手动注册的方式引入实体。当你的组织把catalog-info.yaml等实体描述文件集中存放在 Azure Blob Storage 容器中时逐个手动添加不仅繁琐而且容易遗漏。Azure Blob Storage 集成为此提供了专门的实体 ProviderThe provider will crawl your Blob Storage account container and register entities matching the configured path. This can be useful as an alternative to static locations or manually adding things to the catalog.该 Provider 会爬取指定存储账户的容器将容器中所有符合路径规则的实体文件自动注册进目录可作为静态 location 的替代方案适合大规模、动态变化的实体文件托管场景。前置条件配置 Azure Blob Storage 账户集成使用实体 Provider 之前必须先完成账户级集成配置详见 locations.md集成必须提供accountName并任选以下三种认证方式之一aadCredentialAzure Active Directory 凭据sasToken存储账户共享访问签名accountKey存储账户访问密钥方式一Azure AD 凭据# app-config.yaml 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}方式二SAS Token# app-config.yaml integrations: azureBlobStorage: - accountName: ${ACCOUNT_NAME} # required endpoint: ${CUSTOM_ENDPOINT} # custom endpoint will require either aadCredentials or sasToken sasToken: ${SAS_TOKEN}方式三账户访问密钥# app-config.yaml integrations: azureBlobStorage: - accountName: ${ACCOUNT_NAME} # required endpoint: ${CUSTOM_ENDPOINT} # custom endpoint will require either aadCredentials or sasToken accountKey: ${ACCOUNT_KEY}需要注意的约束文档原文明确标注accountName为必填项使用自定义endpoint时认证方式只能是aadCredential或sasTokenaccountKey走默认的公共终结点生产部署时建议通过附加到实例的托管身份permissions attached to your instance来管理这些凭据避免在配置中明文存放密钥。配置实体发现 Provider在app-config.yaml的catalog.providers.azureBlob下为每个容器文档原文为 per bucket添加一段 Provider 配置# app-config.yaml catalog: providers: azureBlob: providerId: accountName: ${ACCOUNT_NAME} containerName: ${CONTAINER_NAME} schedule: # same options as in TaskScheduleDefinition # supports cron, ISO duration, human duration as used in code frequency: { minutes: 30 } # supports ISO duration, human duration as used in code timeout: { minutes: 3 }简化配置省略 Provider ID对于简单场景可以省略 Provider ID效果等同于使用default作为 ID# app-config.yaml catalog: providers: azureBlob: accountName: ${ACCOUNT_NAME} containerName: ${CONTAINER_NAME} schedule: # same options as in TaskScheduleDefinition # supports cron, ISO duration, human duration as used in code frequency: { minutes: 30 } # supports ISO duration, human duration as used in code timeout: { minutes: 3 }这种简写形式在源码中有明确实现readAzureBlobStorageConfigs会先检测配置节点下是否直接存在containerName键若存在则按default作为 provider id 解析为单个配置见 config.tsif (providerConfigs.has(containerName)) { // simple/single config variant configs.push( readAzureBlobStorageConfig(DEFAULT_PROVIDER_ID, providerConfigs), ); return configs; }反之若配置节点下的每个键都是子对象则会遍历所有 key为每个容器生成一个独立 Provider 实例从而实现多容器并行发现对应测试用例见 config.test.ts。schedule 调度参数详解schedule遵循 Backstage 的TaskScheduleDefinition语义frequency刷新频率。支持 cron 表达式如0 * * * *、ISO 8601 时长如PT30M、以及代码中使用的 human duration 对象写法如{ minutes: 30 }。上例为每 30 分钟刷新一次。timeout单次任务超时时间。支持 ISO duration 和对象写法如{ minutes: 3 }。上例为单次刷新最多 3 分钟。配置中的 schedule 由readSchedulerServiceTaskScheduleDefinitionFromConfig统一解析见 config.ts与后端调度服务的标准任务定义保持一致。安装插件并接入后端由于该 Provider 不属于默认内置 Provider需要先安装 Azure catalog 插件yarn --cwd packages/backend add backstage/plugin-catalog-backend-module-azure随后在 backend 入口注册该模块。使用新版后端系统时在 packages/backend/src/index.ts 中加入backend.add(import(backstage/plugin-catalog-backend)); /* highlight-add-start */ backend.add(import(backstage/plugin-catalog-backend-module-azure)); /* highlight-add-end */接入后后端模块catalogModuleAzureEntityProvider会在初始化时检查配置中是否存在catalog.providers.azureBlob若存在则通过catalog.addEntityProvider(...)将AzureBlobStorageEntityProvider.fromConfig(...)创建的实例注册到 catalog 处理扩展点见 catalogModuleAzureDevOpsEntityProvider.tsif (config.has(catalog.providers.azureBlob)) { catalog.addEntityProvider( AzureBlobStorageEntityProvider.fromConfig(config, { logger, scheduler, }), ); }源码原理Provider 是如何工作的核心实现位于 AzureBlobStorageEntityProvider.ts其工作链路可分为四个阶段。1. 配置装配fromConfigfromConfig依次完成读取catalog.providers.azureBlob下的全部 Provider 配置通过ScmIntegrations.fromConfig(configRoot)与DefaultAzureCredentialsManager构建凭据管理器校验调度必填代码注入的schedule与配置中的schedule至少提供其一否则抛出No schedule provided neither via code nor config for AzureBlobStorageEntityProvider:id.错误校验账户集成存在按accountName在integrations.azureBlobStorage中匹配集成配置找不到时抛出明确错误提示需在integrations.azureBlobStorage下补充配置见 AzureBlobStorageEntityProvider.ts。对应的失败场景在测试中有覆盖见 AzureBlobStorageEntityProvider.test.tsexpect(() AzureBlobStorageEntityProvider.fromConfig(config, { logger }), ).toThrow(Either schedule or scheduler must be provided);2. 建立连接与凭据解析connectconnect阶段根据集成配置选择凭据若配置了accountKey使用StorageSharedKeyCredential该类仅允许在 Node.js 运行时使用浏览器端不可用否则通过DefaultAzureCredentialsManager.getCredentials(accountName)获取凭据覆盖 AAD、SAS 等场景。Blob 服务客户端 URL 的构造逻辑为若配置了自定义endpoint且带有sasToken则拼接为${endpoint}?${sasToken}否则走公共终结点https://${accountName}.${host}见 AzureBlobStorageEntityProvider.ts。3. 定时刷新与全量变更refreshrefresh是每次调度任务执行的正文调用listAllBlobKeys()通过ContainerClient.listBlobsFlat()扁平列出容器内的全部 Blob 名称安全过滤hasDotPathSegment会剔除路径段为.或..的 Blob防止路径穿越类问题被跳过的数量会记录 warning 日志见 AzureBlobStorageEntityProvider.ts将每个 Blob key 转换为LocationSpectype: url、presence: requiredtarget 为去掉查询串与 hash 的 Blob 对象 URL通过connection.applyMutation({ type: full, entities: [...] })提交全量变更每个实体都带有locationKey格式为azureBlobStorage-provider:providerId和backstage.io/managed-by-location注解。测试对全量提交行为做了精确断言见 AzureBlobStorageEntityProvider.test.ts可确认每个发现的 Blob 会生成一个kind: Location、spec.target指向该 Blob URL 的目录实体。4. Provider 命名与调度任务getProviderName()返回azureBlobStorage-provider:providerId调度任务 ID 为${getProviderName()}:refresh任务内部使用randomUUID()生成每次执行的实例 ID 用于日志追踪单次任务失败不会中断后续调度错误会记录为refresh failed日志见 AzureBlobStorageEntityProvider.ts。配置字段速查来自 config schema仓库内 config.d.ts 对catalog.providers.azureBlob做了类型约束字段清单如下字段必填说明accountName是Azure 存储账户名称containerName是要爬取的 Azure Blob Storage 容器名称schedule否刷新任务的TaskScheduleDefinitionfrequency/timeout注意与 Azure DevOps Provider 不同Blob Storage Provider 的配置不支持prefix、path等过滤字段——当前实现是爬取容器内的全部 Blob 并全部注册为 Location测试中出现的prefix字段实际并未被读取见 config.ts 仅读取containerName、accountName、schedule三项。运维建议与注意事项生产凭据管理优先使用托管身份/托管权限而非在配置中硬编码密钥这与文档建议一致。调度必配Provider 必须通过配置或代码提供 schedule否则启动即报错这是防止意外全量爬取的设计约束。发现范围当前实现会注册容器内所有 Blob若容器中存在非 catalog 文件它们也会被注册为 Location 并尝试解析建议为 catalog 文件使用独立容器。全量变更语义每次刷新为full类型 mutation删除容器中的 Blob 后下次刷新对应实体即会从目录移除无需手工清理。路径安全含字面量./..路径段的 Blob 会被跳过并记录 warning这是防御路径穿越的关键保障对应测试见 AzureBlobStorageEntityProvider.test.ts。至此你已经掌握了从账户集成、Provider 配置、插件安装到源码原理的完整链路可以基于 Azure Blob Storage 容器实现软件目录的自动化发现与持续同步。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考