后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载本指南基于 bk-cmdb 官方 API 文档docs/apidoc/cc/zh_hans/get_biz_brief_cache_topo.md编写系统讲解「根据业务 ID 查询该业务全量简明拓扑树」这一缓存接口的请求方式、返回结构与底层实现原理。读完本文你将掌握该接口的参数规范、data.biz/data.idle/data.nds三段式返回结构的确切语义并理解 cacheservice 中 15 分钟全量刷新与事件驱动实时刷新两套缓存机制是如何协同保证数据时效的可直接用于业务拓扑展示、定时任务选域等高频查询场景的二次开发。接口概述与适用场景get_biz_brief_cache_topo是蓝鲸配置平台BlueKing CMDBbk-cmdbv3.9.14 起提供的一个缓存型拓扑查询接口。它根据bk_biz_id查询指定业务的全量简明拓扑树从业务biz这个根节点开始依次包含业务自定义层级实例当主线拓扑层级中配置了自定义层级时、集群set、模块module等中间所有层级的树形数据直至最底层的 module 节点。与常规的拓扑查询接口每次实时读库不同该接口的数据由cacheservice进程统一维护在 Redis 缓存中特别适合**高频、只关心拓扑结构基本信息对象类型、实例 ID、实例名称**的场景——例如文档同目录下 cacheservice 缓存模块说明 中提到的作业平台的定时任务job scheduled tasks场景。使用该接口前需注意两点关键特性默认全量缓存刷新时间为 15 分钟即每隔 15 分钟cacheservice 会遍历所有业务将其拓扑刷新一次到缓存中事件实时刷新如果某业务的拓扑信息发生变化如新增/删除自定义层级实例、集群、模块会通过 watch 事件机制实时刷新该业务在缓存中的拓扑数据无需等待下一个 15 分钟周期。请求参数说明接口的完整 HTTP 路径为POST /api/v3/find/topo/tree/brief/biz/{bk_biz_id}路由注册位于 src/scene_server/topo_server/service/service_initfunc.go对应的请求鉴权正则^/api/v3/find/topo/tree/brief/biz/[0-9]/?$定义在 src/ac/parser/topology.go。公共参数common_args接口与其他蓝鲸 API 一致请求中需携带公共参数bk_app_code、bk_app_secret并视接入方式携带bk_username/bk_token或bk_ticket用于身份认证。接口参数字段类型必选描述bk_biz_idint是要查询的业务拓扑所属的业务 ID作为 URL 路径参数传入请求参数示例{ bk_app_code: esb_test, bk_app_secret: xxx, bk_username: xxx, bk_token: xxx, bk_biz_id: 2 }返回结果示例{ result: true, code: 0, message: success, permission: null, request_id: e43da4ef221746868dc4c837d36f3807, data: { biz: { id: 3, nm: lee, dft: 0, bk_supplier_account: 0 }, idle: [ { obj: set, id: 3, nm: 空闲机池, dft: 1, nds: [ { obj: module, id: 7, nm: 空闲机, dft: 1, nds: null }, { obj: module, id: 8, nm: 故障机, dft: 2, nds: null }, { obj: module, id: 9, nm: 待回收, dft: 3, nds: null } ] } ], nds: [ { obj: province, id: 22, nm: 广东, nds: [ { obj: set, id: 16, nm: magic-set, dft: 0, nds: [ { obj: module, id: 48, nm: gameserver, dft: 0, nds: null }, { obj: module, id: 49, nm: mysql, dft: 0, nds: null } ] } ] } ] } }response 字段说明字段类型描述resultbool请求成功与否。true请求成功false请求失败codeint错误编码。0 表示 success0 表示失败错误messagestring请求失败返回的错误信息permissionobject权限信息request_idstring请求链 IDdataobject请求返回的数据data.biz 参数说明data.biz是该业务的根节点基本信息对应源码 src/source_controller/cacheservice/cache/topology/types.go 中的BizBase结构体字段类型描述idint业务 IDnmstring业务名dftint业务类型该值 0。0表示该业务为普通业务1表示该业务为资源池业务bk_supplier_accountstring开发商账号data.idle 对象参数说明data.idle数组表示该业务的空闲 set 数据。目前一个业务只有一个空闲 set即「空闲机池」但文档明确提示后续可能有多个 set请勿依赖此数量。空闲 set 下默认挂载空闲机dft1、故障机dft2、待回收dft3三个默认模块。字段类型描述objstring该资源的对象可以是业务自定义层级对应的对象 IDbk_obj_id字段值、set、module等idint该实例的 IDnmstring该实例的名称dftint该值 0只有 set 和 module 有该字段。0表示普通的集群或模块1表示为空闲机类的 set 或 modulendsobject该节点所属的子节点信息data.nds 对象参数说明data.nds数组描述该业务下除空闲 set 之外的其它拓扑节点数据。该数组若无其它节点则为空。每个节点按照拓扑层级将节点与其对应的子节点逐个嵌套。需要注意module的nds节点一定为空因为 module 是整个业务拓扑树中最底层的节点各节点的字段语义与data.idle中的节点一致obj/id/nm/dft/nds。返回结构与源码的映射关系上述返回结构并非临时拼装而是与 cacheservice 缓存模块中定义的数据结构一一对应见 src/source_controller/cacheservice/cache/topology/types.goBizBriefTopology结构体包含Biz对应data.biz、Idle对应data.idle、Nodes对应data.nds三个字段Node结构体即为树中的单个节点ObjectJSON 字段obj、IDid、Namenm、Defaultdft带omitempty仅 set、module 存在、SubNodesnds递归嵌套数据来源字段白名单定义在同文件业务取bk_biz_id、bk_biz_name、default、bk_supplier_accountset 取bk_biz_id、bk_parent_id、bk_set_id、bk_set_name、defaultmodule 取bk_biz_id、bk_set_id、bk_module_id、bk_module_name、default。也就是说该接口返回的是精简拓扑每个节点只包含对象类型、实例 ID、实例名称及 set/module 的默认类型标记不含自定义属性等详情字段——这正是它适合高频读取、性能敏感场景的原因。缓存写入与刷新的底层机制接口数据由cacheservice进程维护。缓存模块入口在 src/source_controller/cacheservice/cache/topology/topology.go 的NewTopology初始化时会依次启动对**自定义层级实例custom、集群set、模块module**三类对象的事件监听watch并后台启动一个全量刷新协程loopBizBriefCache。整体包含四条链路定时全量刷新兜底机制loopBizBriefCache协程每间隔briefTopologySyncIntervalMinutes分钟默认 15 分钟遍历所有业务并逐一刷新拓扑缓存确保即使事件丢失也能最终收敛到正确数据。刷新间隔的读取逻辑见 src/source_controller/cacheservice/cache/topology/logic.go从配置中心读取cacheService.briefTopologySyncIntervalMinutes读取失败或配置值小于 2 分钟时回退到默认值 15同时仅当当前进程为 master 实例时才执行刷新checkMaster.IsMaster()。事件驱动实时刷新通过 watch 机制监听bk_topo_set集合表、bk_topo_module模块表及自定义层级实例表的变更事件事件处理器将受影响业务加入刷新列表后调用refreshBatch批量刷新见 src/source_controller/cacheservice/cache/topology/watch.go。每个 watch 使用独立的 token 记录位点brief_topology_cache_watch_token异常时自动重置保证事件不丢失。TTL 自动清理缓存 key 的命名空间为bk:cmdb:v3:cache:topology:brief:{bizID}见 src/source_controller/cacheservice/cache/topology/key.goTTL 为 24 小时。当业务被删除或归档时缓存在 TTL 过期后自动清除无需人工干预。缓存缺失直读 DB 兜底在 src/source_controller/cacheservice/cache/topology/client.go 的GetBizTopology中若从 Redis 读取不到或读到的内容为空会直接从 MongoDB 重新构建该业务的拓扑genBusinessTopology写回缓存后再返回避免缓存失效时接口不可用。拓扑树的构建过程从源码看拓扑树的构建src/source_controller/cacheservice/cache/topology/logic.go遵循主线mainline层级顺序逐级拼装通过getMainlineReverseRank读取主线关联关系bk_topo_obj_asso表、关联类型mainline得到从 module 到 biz 的反向层级排序按层级顺序依次生成各层节点先通过genModulesNodes生成 module 节点并挂到所属 set 下再通过genSetNodes区分空闲 setdefault 0与普通 setdefault 0——前者进入idle分支后者进入普通分支对主线中的每一层自定义对象通过genCustomNodes将实例节点挂载到父节点下逐层向上直至业务根节点最终返回inner空闲拓扑与common普通拓扑两部分每层节点生成后还会按节点名称排序sortNodes保证同层节点的输出顺序稳定。该过程从 MongoDB从库SecondaryPreferredMode读取减轻主库压力。树构建完成后写入 Redis 的即为接口最终返回的 JSON。配置说明缓存刷新间隔可通过cacheservice配置文件中的cacheService段调整模板见 docs/support-file/config/templates/server#conf#common.yaml# cacheService相关配置 cacheService: # 业务简要拓扑缓存的定时刷新时间默认为15分钟最小为2分钟。每次会将所有的业务的拓扑刷新一次到缓存中。 briefTopologySyncIntervalMinutes: 15需要说明的是briefTopologySyncIntervalMinutes控制的是定时全量兜底刷新的周期拓扑发生变更时的事件实时刷新并不受此配置约束会在事件到达后立即生效。若配置值小于 2 分钟含非法值源码会回退到默认值 15 分钟。使用建议优先用缓存接口做高频展示如需频繁获取业务拓扑做列表渲染、树形展示或调度选域优先使用本缓存接口若需要完整的自定义属性或主机信息再改用实时拓扑查询接口。注意数据语义data.idle与data.nds是两棵独立的子树遍历时应分别处理module是叶子节点其nds恒为空dft字段仅 set、module 节点携带业务节点与自定义层级实例节点不含此字段。不要依赖空闲 set 的数量官方文档明确提示后续可能存在多个空闲 set前端/下游系统应遍历data.idle数组而非假定只有一个元素。了解最终一致性边界在极端情况下如事件丢失后尚未到达下一个刷新周期接口可能短暂返回旧拓扑对于对一致性要求极高的场景可结合事件机制或实时查询接口做二次确认。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸配置平台bk-cmdbget_biz_brief_cache_topo 接口详解查询业务简要拓扑树缓存蓝鲸配置平台bk cmdbget_biz_brief_cache_topo 接口详解查询业务简要拓扑树缓存 导读 本文围绕蓝鲸智云配置平台BlueKin后端企业应用运维蓝鲸 CMDBbk-cmdb查询业务拓扑树简要信息接口 find_biz_tree_brief_info 实战指南蓝鲸 CMDBbk cmdb查询业务拓扑树简要信息接口 find_biz_tree_brief_info 实战指南 本文深入讲解蓝鲸智云配置平台BlueK后端企业应用运维蓝鲸配置平台 bk-cmdb find_topo_node_paths 接口详解业务拓扑节点路径查询实战蓝鲸配置平台 bk cmdb find_topo_node_paths 接口详解业务拓扑节点路径查询实战 导读 本文围绕蓝鲸智云配置平台BlueKing C后端企业应用运维上一篇Egg.js 安全策略详解版本支持、漏洞披露流程与 Shell 命令注入防护实战下一篇Design-Patterns-In-Swift 速查手册Swift 5.0 下 25 种设计模式的分类导航与源码总览创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/14 3:14:46 · 阅读 1.2k 蓝鲸配置平台（bk-cmdb）get_biz_brief_cache_topo 接口深度解析：业务全量简明拓扑树缓存查询实战指南
后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载本指南基于 bk-cmdb 官方 API 文档docs/apidoc/cc/zh_hans/get_biz_brief_cache_topo.md编写系统讲解「根据业务 ID 查询该业务全量简明拓扑树」这一缓存接口的请求方式、返回结构与底层实现原理。读完本文你将掌握该接口的参数规范、data.biz/data.idle/data.nds三段式返回结构的确切语义并理解 cacheservice 中 15 分钟全量刷新与事件驱动实时刷新两套缓存机制是如何协同保证数据时效的可直接用于业务拓扑展示、定时任务选域等高频查询场景的二次开发。接口概述与适用场景get_biz_brief_cache_topo是蓝鲸配置平台BlueKing CMDBbk-cmdbv3.9.14 起提供的一个缓存型拓扑查询接口。它根据bk_biz_id查询指定业务的全量简明拓扑树从业务biz这个根节点开始依次包含业务自定义层级实例当主线拓扑层级中配置了自定义层级时、集群set、模块module等中间所有层级的树形数据直至最底层的 module 节点。与常规的拓扑查询接口每次实时读库不同该接口的数据由cacheservice进程统一维护在 Redis 缓存中特别适合**高频、只关心拓扑结构基本信息对象类型、实例 ID、实例名称**的场景——例如文档同目录下 cacheservice 缓存模块说明 中提到的作业平台的定时任务job scheduled tasks场景。使用该接口前需注意两点关键特性默认全量缓存刷新时间为 15 分钟即每隔 15 分钟cacheservice 会遍历所有业务将其拓扑刷新一次到缓存中事件实时刷新如果某业务的拓扑信息发生变化如新增/删除自定义层级实例、集群、模块会通过 watch 事件机制实时刷新该业务在缓存中的拓扑数据无需等待下一个 15 分钟周期。请求参数说明接口的完整 HTTP 路径为POST /api/v3/find/topo/tree/brief/biz/{bk_biz_id}路由注册位于 src/scene_server/topo_server/service/service_initfunc.go对应的请求鉴权正则^/api/v3/find/topo/tree/brief/biz/[0-9]/?$定义在 src/ac/parser/topology.go。公共参数common_args接口与其他蓝鲸 API 一致请求中需携带公共参数bk_app_code、bk_app_secret并视接入方式携带bk_username/bk_token或bk_ticket用于身份认证。接口参数字段类型必选描述bk_biz_idint是要查询的业务拓扑所属的业务 ID作为 URL 路径参数传入请求参数示例{ bk_app_code: esb_test, bk_app_secret: xxx, bk_username: xxx, bk_token: xxx, bk_biz_id: 2 }返回结果示例{ result: true, code: 0, message: success, permission: null, request_id: e43da4ef221746868dc4c837d36f3807, data: { biz: { id: 3, nm: lee, dft: 0, bk_supplier_account: 0 }, idle: [ { obj: set, id: 3, nm: 空闲机池, dft: 1, nds: [ { obj: module, id: 7, nm: 空闲机, dft: 1, nds: null }, { obj: module, id: 8, nm: 故障机, dft: 2, nds: null }, { obj: module, id: 9, nm: 待回收, dft: 3, nds: null } ] } ], nds: [ { obj: province, id: 22, nm: 广东, nds: [ { obj: set, id: 16, nm: magic-set, dft: 0, nds: [ { obj: module, id: 48, nm: gameserver, dft: 0, nds: null }, { obj: module, id: 49, nm: mysql, dft: 0, nds: null } ] } ] } ] } }response 字段说明字段类型描述resultbool请求成功与否。true请求成功false请求失败codeint错误编码。0 表示 success0 表示失败错误messagestring请求失败返回的错误信息permissionobject权限信息request_idstring请求链 IDdataobject请求返回的数据data.biz 参数说明data.biz是该业务的根节点基本信息对应源码 src/source_controller/cacheservice/cache/topology/types.go 中的BizBase结构体字段类型描述idint业务 IDnmstring业务名dftint业务类型该值 0。0表示该业务为普通业务1表示该业务为资源池业务bk_supplier_accountstring开发商账号data.idle 对象参数说明data.idle数组表示该业务的空闲 set 数据。目前一个业务只有一个空闲 set即「空闲机池」但文档明确提示后续可能有多个 set请勿依赖此数量。空闲 set 下默认挂载空闲机dft1、故障机dft2、待回收dft3三个默认模块。字段类型描述objstring该资源的对象可以是业务自定义层级对应的对象 IDbk_obj_id字段值、set、module等idint该实例的 IDnmstring该实例的名称dftint该值 0只有 set 和 module 有该字段。0表示普通的集群或模块1表示为空闲机类的 set 或 modulendsobject该节点所属的子节点信息data.nds 对象参数说明data.nds数组描述该业务下除空闲 set 之外的其它拓扑节点数据。该数组若无其它节点则为空。每个节点按照拓扑层级将节点与其对应的子节点逐个嵌套。需要注意module的nds节点一定为空因为 module 是整个业务拓扑树中最底层的节点各节点的字段语义与data.idle中的节点一致obj/id/nm/dft/nds。返回结构与源码的映射关系上述返回结构并非临时拼装而是与 cacheservice 缓存模块中定义的数据结构一一对应见 src/source_controller/cacheservice/cache/topology/types.goBizBriefTopology结构体包含Biz对应data.biz、Idle对应data.idle、Nodes对应data.nds三个字段Node结构体即为树中的单个节点ObjectJSON 字段obj、IDid、Namenm、Defaultdft带omitempty仅 set、module 存在、SubNodesnds递归嵌套数据来源字段白名单定义在同文件业务取bk_biz_id、bk_biz_name、default、bk_supplier_accountset 取bk_biz_id、bk_parent_id、bk_set_id、bk_set_name、defaultmodule 取bk_biz_id、bk_set_id、bk_module_id、bk_module_name、default。也就是说该接口返回的是精简拓扑每个节点只包含对象类型、实例 ID、实例名称及 set/module 的默认类型标记不含自定义属性等详情字段——这正是它适合高频读取、性能敏感场景的原因。缓存写入与刷新的底层机制接口数据由cacheservice进程维护。缓存模块入口在 src/source_controller/cacheservice/cache/topology/topology.go 的NewTopology初始化时会依次启动对**自定义层级实例custom、集群set、模块module**三类对象的事件监听watch并后台启动一个全量刷新协程loopBizBriefCache。整体包含四条链路定时全量刷新兜底机制loopBizBriefCache协程每间隔briefTopologySyncIntervalMinutes分钟默认 15 分钟遍历所有业务并逐一刷新拓扑缓存确保即使事件丢失也能最终收敛到正确数据。刷新间隔的读取逻辑见 src/source_controller/cacheservice/cache/topology/logic.go从配置中心读取cacheService.briefTopologySyncIntervalMinutes读取失败或配置值小于 2 分钟时回退到默认值 15同时仅当当前进程为 master 实例时才执行刷新checkMaster.IsMaster()。事件驱动实时刷新通过 watch 机制监听bk_topo_set集合表、bk_topo_module模块表及自定义层级实例表的变更事件事件处理器将受影响业务加入刷新列表后调用refreshBatch批量刷新见 src/source_controller/cacheservice/cache/topology/watch.go。每个 watch 使用独立的 token 记录位点brief_topology_cache_watch_token异常时自动重置保证事件不丢失。TTL 自动清理缓存 key 的命名空间为bk:cmdb:v3:cache:topology:brief:{bizID}见 src/source_controller/cacheservice/cache/topology/key.goTTL 为 24 小时。当业务被删除或归档时缓存在 TTL 过期后自动清除无需人工干预。缓存缺失直读 DB 兜底在 src/source_controller/cacheservice/cache/topology/client.go 的GetBizTopology中若从 Redis 读取不到或读到的内容为空会直接从 MongoDB 重新构建该业务的拓扑genBusinessTopology写回缓存后再返回避免缓存失效时接口不可用。拓扑树的构建过程从源码看拓扑树的构建src/source_controller/cacheservice/cache/topology/logic.go遵循主线mainline层级顺序逐级拼装通过getMainlineReverseRank读取主线关联关系bk_topo_obj_asso表、关联类型mainline得到从 module 到 biz 的反向层级排序按层级顺序依次生成各层节点先通过genModulesNodes生成 module 节点并挂到所属 set 下再通过genSetNodes区分空闲 setdefault 0与普通 setdefault 0——前者进入idle分支后者进入普通分支对主线中的每一层自定义对象通过genCustomNodes将实例节点挂载到父节点下逐层向上直至业务根节点最终返回inner空闲拓扑与common普通拓扑两部分每层节点生成后还会按节点名称排序sortNodes保证同层节点的输出顺序稳定。该过程从 MongoDB从库SecondaryPreferredMode读取减轻主库压力。树构建完成后写入 Redis 的即为接口最终返回的 JSON。配置说明缓存刷新间隔可通过cacheservice配置文件中的cacheService段调整模板见 docs/support-file/config/templates/server#conf#common.yaml# cacheService相关配置 cacheService: # 业务简要拓扑缓存的定时刷新时间默认为15分钟最小为2分钟。每次会将所有的业务的拓扑刷新一次到缓存中。 briefTopologySyncIntervalMinutes: 15需要说明的是briefTopologySyncIntervalMinutes控制的是定时全量兜底刷新的周期拓扑发生变更时的事件实时刷新并不受此配置约束会在事件到达后立即生效。若配置值小于 2 分钟含非法值源码会回退到默认值 15 分钟。使用建议优先用缓存接口做高频展示如需频繁获取业务拓扑做列表渲染、树形展示或调度选域优先使用本缓存接口若需要完整的自定义属性或主机信息再改用实时拓扑查询接口。注意数据语义data.idle与data.nds是两棵独立的子树遍历时应分别处理module是叶子节点其nds恒为空dft字段仅 set、module 节点携带业务节点与自定义层级实例节点不含此字段。不要依赖空闲 set 的数量官方文档明确提示后续可能存在多个空闲 set前端/下游系统应遍历data.idle数组而非假定只有一个元素。了解最终一致性边界在极端情况下如事件丢失后尚未到达下一个刷新周期接口可能短暂返回旧拓扑对于对一致性要求极高的场景可结合事件机制或实时查询接口做二次确认。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸配置平台bk-cmdbget_biz_brief_cache_topo 接口详解查询业务简要拓扑树缓存蓝鲸配置平台bk cmdbget_biz_brief_cache_topo 接口详解查询业务简要拓扑树缓存 导读 本文围绕蓝鲸智云配置平台BlueKin后端企业应用运维蓝鲸 CMDBbk-cmdb查询业务拓扑树简要信息接口 find_biz_tree_brief_info 实战指南蓝鲸 CMDBbk cmdb查询业务拓扑树简要信息接口 find_biz_tree_brief_info 实战指南 本文深入讲解蓝鲸智云配置平台BlueK后端企业应用运维蓝鲸配置平台 bk-cmdb find_topo_node_paths 接口详解业务拓扑节点路径查询实战蓝鲸配置平台 bk cmdb find_topo_node_paths 接口详解业务拓扑节点路径查询实战 导读 本文围绕蓝鲸智云配置平台BlueKing C后端企业应用运维上一篇Egg.js 安全策略详解版本支持、漏洞披露流程与 Shell 命令注入防护实战下一篇Design-Patterns-In-Swift 速查手册Swift 5.0 下 25 种设计模式的分类导航与源码总览创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考