拓冰网站定制 
Backstage 软件目录审计事件Audit Events完全指南事件类型、meta 结构与配置详解【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage导读本文围绕 Backstage 软件目录Software Catalog后端发出的**审计事件Audit Events**展开。审计事件是 Backstage 新后端系统中 Auditor 核心服务AuditorService的产物用于追踪对软件目录中实体Entity与位置Location的每一次访问与修改。读完本文你将掌握目录审计事件的分组方式eventIdsubEventId/meta、每个事件对应的 REST 端点与queryType/actionType过滤维度、如何通过backend.auditor.severityLogLevelMappings配置控制低严重度事件的日志输出以及 Auditor 服务在底层是如何把事件写入日志的。一、审计事件目录访问的安全足迹Backstage 的软件目录后端catalog-backend在各类操作发生时都会发出审计事件。这些事件按eventId进行逻辑分组组内再通过subEventId实际实现中以meta.queryType、meta.actionType等字段体现进一步区分具体操作。这一命名规范在 Auditor 服务的官方约定中得到了明确eventId表示一类相关操作的逻辑分组而meta中的queryType/actionType等字段则精确刻画组内的具体动作见 Auditor 服务文档。从源码层面看目录后端的所有审计事件都在路由器 plugins/catalog-backend/src/service/createRouter.ts 中创建典型模式如下以POST /refresh为例源码位置const auditorEvent await auditor.createEvent({ eventId: entity-mutate, severityLevel: medium, meta: { queryType: refresh, entityRef: restBody.entityRef, }, request: req, }); try { // ... 执行业务逻辑 await auditorEvent?.success(); res.status(200).end(); } catch (err) { await auditorEvent?.fail({ error: err }); throw err; }每个路由处理器都遵循先创建事件 → 业务成功后调用success()→ 异常时调用fail({ error })的三段式结构从而保证审计日志能如实反映请求的成败。二、实体事件Entity Events实体事件围绕目录实体的查询fetch、变更mutate、校验validate与 facets 统计展开。2.1entity-fetch实体检索entity-fetch覆盖所有读取实体的操作通过meta.queryType区分具体查询方式。需要特别注意的是默认情况下entity-fetch这类 low 严重度的审计事件不会被记录因为 low 严重度默认映射到 debug 日志级别而 Backstage 默认日志级别是 info。若想看到这些事件需在app-config.yaml中设置backend: auditor: severityLogLevelMappings: low: info各queryType对应的端点如下queryType含义对应端点all获取全部实体GET/entitiesby-id按 UID 获取单个实体GET/entities/by-uid/:uidby-name按 kind、namespace、name 获取单个实体GET/entities/by-name/:kind/:namespace/:nameby-query用过滤查询获取多个实体GET/POST/entities/by-queryby-refs按 entity refs 批量获取实体POST/entities/by-refsancestry获取实体的血统祖先链GET/entities/by-name/:kind/:namespace/:name/ancestry源码佐证createRouter.tsGET /entities处理器在创建事件时将queryType: all和原始req.query一并写入meta在流式返回实体后调用success()。GET /entities/by-uid/:uid源码则在meta中同时记录uid成功时还会把返回的实体以 entity ref 字符串列表形式写入success({ meta })。ancestry事件源码在成功回调中记录了rootEntityRef与完整的祖先链映射。实现细节提示在POST /entities/by-query的成功回调中代码特意注释Lets not log out the entities since this can make the log very big源码仅记录totalItems与分页游标。这说明审计日志设计上会刻意避免记录完整实体内容防止日志体量失控。2.2entity-mutate实体变更entity-mutate覆盖修改实体的操作通过meta.actionType区分动作类型actionType含义对应端点delete删除单个实体。注意这不是永久删除若父 location 仍存在于目录中实体将被恢复DELETE/entities/by-uid/:uidrefresh调度一次实体刷新POST/entities/refresh这两个写操作都带有severityLevel: medium见 refresh 源码 与 delete 源码符合 Auditor 服务对严重度级别的约定——medium表示访问写端点这类需要一定关注度的事件。2.3entity-validate实体校验entity-validate用于校验一个实体POST/entities/validate。该事件在 createRouter.ts 第 877 行附近 创建事件本身不携带queryType/actionType属于独立的校验操作事件。2.4entity-facets实体 facets 检索entity-facets覆盖实体 facets维度统计的获取同时支持 GET 与 POST 两种方式GET 源码、POST 源码GET/entity-facetsPOST/entity-facets三、位置事件Location Events位置Location代表实体清单如url:https://example.com/catalog-info.yaml其审计事件同样分为检索与变更两大类。3.1location-fetch位置检索queryType含义对应端点all获取全部位置GET/locationsby-id按 ID 获取单个位置GET/locations/:idby-entity获取与某 entity ref 关联的位置GET/locations/by-entity在 createRouter.ts 中GET /locations将queryType: all写入 metaGET /locations/:id记录queryType: by-id与id并在成功回调中输出完整位置对象。另外源码中还有一个POST /locations/by-query源码以queryType: by-query记录分页查询位置的操作该端点未出现在文档的表格中属于文档之外、源码可证的补充细节。3.2location-mutate位置变更actionType含义对应端点create创建新位置POST/locationsdelete删除位置及其关联实体DELETE/locations/:idPOST /locations的实现源码展示了更精细的严重度设计dry-run 模式下事件严重度为low真实创建时为medium并在meta中记录location与isDryRun标志。另外源码中还有一个actionType: update的变体PUT /locations/:id源码成功时在 meta 中输出更新后的 location 对象。3.3location-analyze位置分析location-analyze覆盖位置分析操作POST/locations/analyze事件创建于 createRouter.ts 第 831 行附近。该事件同样属于独立事件不依赖queryType/actionType区分子类型。四、审计事件的统一结构eventIdmeta所有目录审计事件共享同一套结构由 AuditorService.ts 定义eventIdkebab-case 命名的逻辑分组标识如entity-fetch、location-mutate。eventId中不应包含与插件相关的冗余前缀因为插件上下文已单独提供severityLevel可选取值low/medium/high/criticalrequest可选关联的 HTTP 请求对象用于提取 actor、请求元数据等上下文meta可选JSON 对象承载queryType、actionType、entityRef、uid、locationRef等补充信息。meta中常见的键值约定如下摘自 Auditor 服务文档键描述格式示例queryType获取数据时执行的查询类型kebab-case 字符串all、by-id、by-name、by-query、by-refs、ancestry、by-entityactionType修改数据时执行的动作类型kebab-case 字符串create、delete、refreshentityRef实体的完整引用含 kind、namespace、name[kind]:[namespace]/[name]component:default/my-component、group:my-org/team-alocationRef被操作位置的引用任意表示位置的字符串url:https://example.com/catalog-info.yaml、custom:default/my-locationuid被操作对象位置或实体的唯一标识合法 UID 字符串9a4e740b-e557-427f-b9f2-0d4f092b1c1e两个典型事件示例摘自 Auditor 服务文档读取操作——获取全部实体{ eventId: entity-fetch, meta: { queryType: all } ... }写入操作——删除实体{ eventId: entity-mutate, meta: { actionType: delete, uid: some-entity-uid, entityRef: component:default/petstore }, severityLevel: medium ... }五、严重度与日志级别映射让entity-fetch真正可见5.1 四个严重度级别及其默认映射Auditor 服务支持四个严重度级别默认映射到如下日志级别严重度含义默认日志级别low普通常规操作如数据读取debugmedium写端点访问等需一定关注的事件infohigh非 root 级权限变更等高影响事件infocriticalroot 级权限变更等需要立即关注的事件info由于medium、high、critical默认均映射到info而 Backstage 默认日志级别为info因此目录中的写操作entity-mutate、location-mutate默认即可被记录只有low级别的读取事件如entity-fetch默认落到了debug级别而被过滤。5.2 自定义映射配置在app-config.yaml的backend.auditor.severityLogLevelMappings下可以逐级别覆盖映射无需整体重写backend: auditor: severityLogLevelMappings: low: debug medium: info high: warn critical: error若想看到全部entity-fetch读取事件只需将low提升为infobackend: auditor: severityLogLevelMappings: low: info5.3 底层实现事件如何变成日志从源码看auditorServiceFactorypackages/backend-defaults/src/entrypoints/auditor/auditorServiceFactory.ts负责将审计事件落地为日志基于插件 logger 派生一个标记了isAuditEvent: true的审计 logger通过getSeverityLogLevelMappings(config)从配置读取映射表即上文的severityLogLevelMappings当事件被成功/失败上报时按severityLogLevelMappings[event.severityLevel]选择对应的日志方法debug/info/warn/error以插件ID.事件ID如catalog.entity-fetch作为日志消息输出失败事件还会携带error对象。这也是为什么修改severityLogLevelMappings能直接决定审计事件是否出现在日志中的根本原因——配置键与日志级别是一一对应的。六、总结如何利用目录审计事件需求做法追踪实体读取行为合规审计开启backend.auditor.severityLogLevelMappings.low: info观察entity-fetch事件并按queryType区分查询方式追踪实体/位置变更直接观察entity-mutateactionType: delete/refresh与location-mutateactionType: create/delete/update它们默认以 info 级别记录校验与统计关注独立的entity-validate、entity-facets、location-analyze事件区分操作语义读取类事件看meta.queryType写入类事件看meta.actionType配合entityRef/uid定位具体对象审计事件为软件目录的每一次读取与修改留下了结构化、可检索的安全足迹是目录合规审计、访问追踪与异常排查的基础设施。想深入了解 Auditor 服务的完整设计命名规范、meta 键值约定、服务接入示例可继续阅读 Auditor 服务核心文档其代码级集成示例正对应本仓库 catalog-backend 的 createRouter.ts 中的实际实现。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Backstage 软件目录审计事件（Audit Events）完全指南：事件类型、meta 结构与配置详解
Backstage 软件目录审计事件Audit Events完全指南事件类型、meta 结构与配置详解【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage导读本文围绕 Backstage 软件目录Software Catalog后端发出的**审计事件Audit Events**展开。审计事件是 Backstage 新后端系统中 Auditor 核心服务AuditorService的产物用于追踪对软件目录中实体Entity与位置Location的每一次访问与修改。读完本文你将掌握目录审计事件的分组方式eventIdsubEventId/meta、每个事件对应的 REST 端点与queryType/actionType过滤维度、如何通过backend.auditor.severityLogLevelMappings配置控制低严重度事件的日志输出以及 Auditor 服务在底层是如何把事件写入日志的。一、审计事件目录访问的安全足迹Backstage 的软件目录后端catalog-backend在各类操作发生时都会发出审计事件。这些事件按eventId进行逻辑分组组内再通过subEventId实际实现中以meta.queryType、meta.actionType等字段体现进一步区分具体操作。这一命名规范在 Auditor 服务的官方约定中得到了明确eventId表示一类相关操作的逻辑分组而meta中的queryType/actionType等字段则精确刻画组内的具体动作见 Auditor 服务文档。从源码层面看目录后端的所有审计事件都在路由器 plugins/catalog-backend/src/service/createRouter.ts 中创建典型模式如下以POST /refresh为例源码位置const auditorEvent await auditor.createEvent({ eventId: entity-mutate, severityLevel: medium, meta: { queryType: refresh, entityRef: restBody.entityRef, }, request: req, }); try { // ... 执行业务逻辑 await auditorEvent?.success(); res.status(200).end(); } catch (err) { await auditorEvent?.fail({ error: err }); throw err; }每个路由处理器都遵循先创建事件 → 业务成功后调用success()→ 异常时调用fail({ error })的三段式结构从而保证审计日志能如实反映请求的成败。二、实体事件Entity Events实体事件围绕目录实体的查询fetch、变更mutate、校验validate与 facets 统计展开。2.1entity-fetch实体检索entity-fetch覆盖所有读取实体的操作通过meta.queryType区分具体查询方式。需要特别注意的是默认情况下entity-fetch这类 low 严重度的审计事件不会被记录因为 low 严重度默认映射到 debug 日志级别而 Backstage 默认日志级别是 info。若想看到这些事件需在app-config.yaml中设置backend: auditor: severityLogLevelMappings: low: info各queryType对应的端点如下queryType含义对应端点all获取全部实体GET/entitiesby-id按 UID 获取单个实体GET/entities/by-uid/:uidby-name按 kind、namespace、name 获取单个实体GET/entities/by-name/:kind/:namespace/:nameby-query用过滤查询获取多个实体GET/POST/entities/by-queryby-refs按 entity refs 批量获取实体POST/entities/by-refsancestry获取实体的血统祖先链GET/entities/by-name/:kind/:namespace/:name/ancestry源码佐证createRouter.tsGET /entities处理器在创建事件时将queryType: all和原始req.query一并写入meta在流式返回实体后调用success()。GET /entities/by-uid/:uid源码则在meta中同时记录uid成功时还会把返回的实体以 entity ref 字符串列表形式写入success({ meta })。ancestry事件源码在成功回调中记录了rootEntityRef与完整的祖先链映射。实现细节提示在POST /entities/by-query的成功回调中代码特意注释Lets not log out the entities since this can make the log very big源码仅记录totalItems与分页游标。这说明审计日志设计上会刻意避免记录完整实体内容防止日志体量失控。2.2entity-mutate实体变更entity-mutate覆盖修改实体的操作通过meta.actionType区分动作类型actionType含义对应端点delete删除单个实体。注意这不是永久删除若父 location 仍存在于目录中实体将被恢复DELETE/entities/by-uid/:uidrefresh调度一次实体刷新POST/entities/refresh这两个写操作都带有severityLevel: medium见 refresh 源码 与 delete 源码符合 Auditor 服务对严重度级别的约定——medium表示访问写端点这类需要一定关注度的事件。2.3entity-validate实体校验entity-validate用于校验一个实体POST/entities/validate。该事件在 createRouter.ts 第 877 行附近 创建事件本身不携带queryType/actionType属于独立的校验操作事件。2.4entity-facets实体 facets 检索entity-facets覆盖实体 facets维度统计的获取同时支持 GET 与 POST 两种方式GET 源码、POST 源码GET/entity-facetsPOST/entity-facets三、位置事件Location Events位置Location代表实体清单如url:https://example.com/catalog-info.yaml其审计事件同样分为检索与变更两大类。3.1location-fetch位置检索queryType含义对应端点all获取全部位置GET/locationsby-id按 ID 获取单个位置GET/locations/:idby-entity获取与某 entity ref 关联的位置GET/locations/by-entity在 createRouter.ts 中GET /locations将queryType: all写入 metaGET /locations/:id记录queryType: by-id与id并在成功回调中输出完整位置对象。另外源码中还有一个POST /locations/by-query源码以queryType: by-query记录分页查询位置的操作该端点未出现在文档的表格中属于文档之外、源码可证的补充细节。3.2location-mutate位置变更actionType含义对应端点create创建新位置POST/locationsdelete删除位置及其关联实体DELETE/locations/:idPOST /locations的实现源码展示了更精细的严重度设计dry-run 模式下事件严重度为low真实创建时为medium并在meta中记录location与isDryRun标志。另外源码中还有一个actionType: update的变体PUT /locations/:id源码成功时在 meta 中输出更新后的 location 对象。3.3location-analyze位置分析location-analyze覆盖位置分析操作POST/locations/analyze事件创建于 createRouter.ts 第 831 行附近。该事件同样属于独立事件不依赖queryType/actionType区分子类型。四、审计事件的统一结构eventIdmeta所有目录审计事件共享同一套结构由 AuditorService.ts 定义eventIdkebab-case 命名的逻辑分组标识如entity-fetch、location-mutate。eventId中不应包含与插件相关的冗余前缀因为插件上下文已单独提供severityLevel可选取值low/medium/high/criticalrequest可选关联的 HTTP 请求对象用于提取 actor、请求元数据等上下文meta可选JSON 对象承载queryType、actionType、entityRef、uid、locationRef等补充信息。meta中常见的键值约定如下摘自 Auditor 服务文档键描述格式示例queryType获取数据时执行的查询类型kebab-case 字符串all、by-id、by-name、by-query、by-refs、ancestry、by-entityactionType修改数据时执行的动作类型kebab-case 字符串create、delete、refreshentityRef实体的完整引用含 kind、namespace、name[kind]:[namespace]/[name]component:default/my-component、group:my-org/team-alocationRef被操作位置的引用任意表示位置的字符串url:https://example.com/catalog-info.yaml、custom:default/my-locationuid被操作对象位置或实体的唯一标识合法 UID 字符串9a4e740b-e557-427f-b9f2-0d4f092b1c1e两个典型事件示例摘自 Auditor 服务文档读取操作——获取全部实体{ eventId: entity-fetch, meta: { queryType: all } ... }写入操作——删除实体{ eventId: entity-mutate, meta: { actionType: delete, uid: some-entity-uid, entityRef: component:default/petstore }, severityLevel: medium ... }五、严重度与日志级别映射让entity-fetch真正可见5.1 四个严重度级别及其默认映射Auditor 服务支持四个严重度级别默认映射到如下日志级别严重度含义默认日志级别low普通常规操作如数据读取debugmedium写端点访问等需一定关注的事件infohigh非 root 级权限变更等高影响事件infocriticalroot 级权限变更等需要立即关注的事件info由于medium、high、critical默认均映射到info而 Backstage 默认日志级别为info因此目录中的写操作entity-mutate、location-mutate默认即可被记录只有low级别的读取事件如entity-fetch默认落到了debug级别而被过滤。5.2 自定义映射配置在app-config.yaml的backend.auditor.severityLogLevelMappings下可以逐级别覆盖映射无需整体重写backend: auditor: severityLogLevelMappings: low: debug medium: info high: warn critical: error若想看到全部entity-fetch读取事件只需将low提升为infobackend: auditor: severityLogLevelMappings: low: info5.3 底层实现事件如何变成日志从源码看auditorServiceFactorypackages/backend-defaults/src/entrypoints/auditor/auditorServiceFactory.ts负责将审计事件落地为日志基于插件 logger 派生一个标记了isAuditEvent: true的审计 logger通过getSeverityLogLevelMappings(config)从配置读取映射表即上文的severityLogLevelMappings当事件被成功/失败上报时按severityLogLevelMappings[event.severityLevel]选择对应的日志方法debug/info/warn/error以插件ID.事件ID如catalog.entity-fetch作为日志消息输出失败事件还会携带error对象。这也是为什么修改severityLogLevelMappings能直接决定审计事件是否出现在日志中的根本原因——配置键与日志级别是一一对应的。六、总结如何利用目录审计事件需求做法追踪实体读取行为合规审计开启backend.auditor.severityLogLevelMappings.low: info观察entity-fetch事件并按queryType区分查询方式追踪实体/位置变更直接观察entity-mutateactionType: delete/refresh与location-mutateactionType: create/delete/update它们默认以 info 级别记录校验与统计关注独立的entity-validate、entity-facets、location-analyze事件区分操作语义读取类事件看meta.queryType写入类事件看meta.actionType配合entityRef/uid定位具体对象审计事件为软件目录的每一次读取与修改留下了结构化、可检索的安全足迹是目录合规审计、访问追踪与异常排查的基础设施。想深入了解 Auditor 服务的完整设计命名规范、meta 键值约定、服务接入示例可继续阅读 Auditor 服务核心文档其代码级集成示例正对应本仓库 catalog-backend 的 createRouter.ts 中的实际实现。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考