后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载本文基于蓝鲸智云配置平台BlueKing CMDB即 bk-cmdb的 OpenAPI 文档深入讲解POST /api/v3/findmany/hosts/detail_topo接口它允许调用方基于主机属性条件一次查询出主机详情与主机在业务拓扑树中的完整位置国家/省份/集群/模块等多层级节点。读完本文你将掌握该接口的请求参数结构、host_property_filter组合过滤规则的完整语法、分页控制方式、返回数据的拓扑树组装规则以及它在 host_server 服务中的底层实现原理。接口概述detail_topo即ListHostDetailAndTopology是 bk-cmdb 面向 API 网关APIGW开放的主机查询接口对应调用权限为主机池主机查看权限Host pool host view permission。它的核心能力是根据主机条件信息查询主机详情及其拓扑信息。从源码结构看该接口在 host_server 路由注册 中注册为utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: /findmany/hosts/detail_topo, Handler: s.ListHostDetailAndTopology})对应处理器实现在 findhost.go。在权限解析层面ac/parser/host.go 将其匹配为meta.HostInstance类型的FindMany动作即按主机实例的批量查看权限进行鉴权。该接口与按业务查询主机的list_hosts_topo/hosts/app/{bk_biz_id}/list_hosts_topo不同detail_topo不要求调用方在 URL 中携带业务 ID而是完全依靠主机属性过滤条件host_property_filter圈定主机范围并返回每台主机在拓扑中的多级父节点链路适合主机池资源池场景下的主机检索与定位。请求参数详解接口为POST请求体为 JSON。核心参数如下名称类型必填说明pagedict是分页查询条件host_property_filterobject否主机属性组合查询条件fieldsarray是需要返回的主机属性字段列表按需填写对应的请求体结构定义在 metadata/hostserver.go 中type ListHostsDetailAndTopoOption struct { WithBiz bool json:with_biz HostPropertyFilter *querybuilder.QueryFilter json:host_property_filter Fields []string json:fields Page BasePage json:page }其中with_biz是一个可选增强字段文档未列出但在源码中已支持置为true时返回的拓扑树会带上业务节点同时服务端会对涉及的业务做ViewBusinessResource级别的实例鉴权见 findhost.go。fields按需裁剪返回字段fields用于控制响应中主机属性部分返回哪些字段。服务端在实现中会把bk_host_id强制追加进查询字段见 findhost.go因为后续拓扑编排依赖主机 ID 关联主机与模块关系option : meta.ListHosts{ HostPropertyFilter: options.HostPropertyFilter, Fields: append(options.Fields, common.BKHostIDField), Page: options.Page, }若fields为空参数校验会直接返回参数错误见 metadata/hostserver.go因此fields是必填项。page分页控制名称类型必填说明startint是记录起始位置从 0 开始limitint是每页记录数最大值为 500sortstring否排序字段分页结构对应metadata.BasePagepage.go。在ListHostsDetailAndTopoOption.Validate()中limit上限被进一步约束为common.BKMaxInstanceLimit即 500start不允许为负数见 metadata/hostserver.go。建议显式指定sort例如bk_host_id保证多次分页取数时结果顺序稳定。host_property_filter主机属性组合过滤该参数用于基于主机属性字段搜索主机组合支持AND 与 OR最多可嵌套两层即查询条件最大深度为 3。过滤规则是field、operator、value四元组实际是 field/operator/value 三元组加组合节点。名称类型必填说明conditionstring否组合查询条件AND或ORrulesarray否过滤规则列表rules中的每条规则名称类型必填说明fieldstring是字段名称operatorstring是操作符可选值equal、not_equal、in、not_in、less、less_or_equal、greater、greater_or_equal、between、not_betweenvalue-否操作数不同操作符对应不同取值格式说明文档所列操作符与 querybuilder 模块当前实现存在差异——between/not_between目前不在 types.go 的SupportOperators集合中README也明确说明不支持between/not_between此类区间比较可基于greater_or_equal与less_or_equal组合实现。当前完整支持的操作符包括equal、not_equal、in、not_in、less、less_or_equal、greater、greater_or_equal以及时间比较类datetime_less、datetime_less_or_equal、datetime_greater、datetime_greater_or_equal、字符串类begins_with、not_begins_with、contains、not_contains、ends_with、not_ends_with、数组类is_empty、is_not_empty、空值类is_null、is_not_null、字段存在类exist、not_exist。各操作符的 value 格式要求详见 types.go 与 validate.go操作符类别操作符value 格式通用比较equal/not_equal基本类型数值、布尔、字符串集合比较in/not_in基本类型数组元素类型需一致NeedSameSliceElementType数值比较less/less_or_equal/greater/greater_or_equal数值时间比较datetime_*系列RFC3339 时间字符串或日期字符串字符串匹配begins_with/contains/ends_with及其not_变体非空字符串数组空值is_empty/is_not_empty不接受参数空值判断is_null/is_not_null不接受参数字段存在exist/not_exist不接受参数组合规则深度的限制querybuilder.MaxDeep 3types.go即最外层的 AND/OR 组合节点算第 1 层最多嵌套两层子组合最内层为原子规则。超出深度上限会在 Validate 中被拦截返回host_property_filter exceeded max allowed deep。过滤规则的底层转换host_property_filter在 metadata/hostserver.go 中被校验后会通过QueryFilter.ToMgo()转换为 MongoDB 查询条件见 types.go例如equal转为$eq、in转为$in、contains转为大小写不敏感的$regex等随后由 coreservice 的Host().ListHosts()在 MongoDB 中执行调用链见 findhost.go 与 apimachinery/coreservice/host/api.go。请求示例以下请求示例综合演示了page、fields与双层嵌套的host_property_filter原文档示例{ page: { start: 0, limit: 10, sort: bk_host_id }, fields: [ bk_host_id, bk_host_innerip ], host_property_filter: { condition: AND, rules: [ { field: bk_host_innerip, operator: equal, value: 192.168.1.1 }, { condition: OR, rules: [ { field: bk_os_type, operator: not_in, value: [ 3 ] }, { field: bk_cloud_id, operator: equal, value: 0 } ] } ] } }该请求的语义为查询内网 IP 为192.168.1.1并且操作系统类型不在[3]中或管控区域 ID 等于 0的主机每页取 10 条按bk_host_id升序返回字段仅含bk_host_id与bk_host_innerip。注意in/not_in的 value 必须是数组如上例[3]equal的 value 可直接为标量数组元素类型需一致且数组长度默认上限为 500DefaultMaxSliceElementsCount见 types.go。响应结构与返回参数通用响应封装名称类型说明resultbool请求是否成功true成功false失败codeint错误码0表示成功0表示失败messagestring失败时返回的错误信息permissionobject权限信息dataobject请求返回的数据data 结构名称类型说明countint记录总数infoarray主机数据与拓扑信息列表其中info数组的每个元素包含名称类型说明hostdict主机实际数据topoarray主机拓扑信息响应示例原文档完整示例{ result: true, code: 0, message: success, permission: null, data: { count: 2, info: [ { host: { bk_host_id: 2, bk_host_innerip: 192.168.1.1 }, topo: [ { inst: { obj: nation, name: 中国, id: 30 }, children: [ { inst: { obj: province, name: prov-xxx, id: 31 }, children: [ { inst: { obj: set, name: set-xxx, id: 20 }, children: [ { inst: { obj: module, name: mod-xxx, id: 52 }, children: null }, { inst: { obj: module, name: mod-yy, id: 53 }, children: null } ] } ] } ] }, { inst: { obj: nation, name: 国家, id: 29 }, children: [ { inst: { obj: province, name: prv1, id: 26 }, children: [ { inst: { obj: set, name: set11, id: 19 }, children: [ { inst: { obj: module, name: m22, id: 51 }, children: null } ] } ] } ] } ] }, { host: { bk_host_id: 4, bk_host_innerip: 192.168.1.2 }, topo: [ { inst: { obj: set, name: 空闲机池, id: 2 }, children: [ { inst: { obj: module, name: 故障机, id: 4 }, children: null } ] } ] } ] } }从示例可以看到拓扑树的两种形态业务自定义层级的主机返回从自定义模型如nation、province到set、module的多级父节点链位于空闲机池的主机则直接返回set空闲机池→module故障机/空闲机的两级结构。host 字段说明data.info.host中返回的字段由请求fields决定。以下为系统内置主机属性字段说明其余返回值取决于用户自定义属性字段字段类型说明bk_host_namestring主机名bk_host_inneripstring主机内网 IPbk_host_idint主机 IDbk_cloud_idint管控区域import_fromstring主机导入来源3表示 API 导入bk_asset_idstring固定资产编号bk_cloud_inst_idstring云主机实例 IDbk_cloud_vendorstring云厂商bk_cloud_host_statusstring云主机状态bk_commentstring备注bk_cpuintCPU 逻辑核数bk_cpu_architecturestringCPU 架构bk_cpu_modulestringCPU 型号bk_diskint磁盘容量GBbk_host_outeripstring主机外网 IPbk_host_innerip_v6string主机内网 IPv6bk_host_outerip_v6string主机外网 IPv6bk_isp_namestring运营商名称bk_macstring主机内网 MAC 地址bk_memint主机内存容量MBbk_os_bitstring操作系统位数bk_os_namestring操作系统名称bk_os_typestring操作系统类型bk_os_versionstring操作系统版本bk_outer_macstring主机外网 MAC 地址bk_province_namestring主机所在省份bk_service_termint保修年限bk_slastringSLA 级别bk_snstring设备序列号bk_statestring当前状态bk_state_namestring主机所在国家operatorstring主要维护人bk_bak_operatorstring备份维护人topo 节点结构data.info.topo是递归的树形结构节点定义如下名称类型说明instobject节点实例详情inst.objstring节点的模型类型如set、module及自定义层级模型类型inst.namestring节点实例名称inst.idint节点实例 IDchildrenobject array当前实例的子节点详情可能有多条children.instobject子节点的实例详情children.childrenstring当前实例的子节点详情递归结构该结构与源码中的HostDetailWithTopo/HostTopoNode/NodeInstance一一对应metadata/hostserver.gotype HostDetailWithTopo struct { Host map[string]interface{} json:host Topo []*HostTopoNode json:topo } type HostTopoNode struct { Instance *NodeInstance json:inst Children []*HostTopoNode json:children } type NodeInstance struct { Object string json:obj InstName interface{} json:name InstID interface{} json:id }底层实现原理拓扑树是如何组装出来的detail_topo的处理器实现位于 findhost.go其执行流程分为四步参数校验ListHostsDetailAndTopoOption.Validate()校验page、过滤规则深度与fields非空查询主机调用CoreService().Host().ListHosts()并把bk_host_id追加到fields后查询查询读取策略设置为SecondaryPreferredMode优先从 MongoDB 从节点读取降低主库压力编排拓扑调用Logic.ArrangeHostDetailAndTopology()组装每台主机的拓扑树可选鉴权与响应若with_biztrue且开启了权限中心AuthManager对涉及的业务执行ViewBusinessResource鉴权最终以count info形式返回。ArrangeHostDetailAndTopology的编排过程logics/host.go是理解返回结果的关键获取主模型链mainline排序通过getTopologyRank()读取模型关联中的主模型关联AssociationKindMainline构建从biz → ... → set → module的模型层级顺序logics/host.go读取主机-模块关系批量查询主机归属的bk_app_id、bk_set_id、bk_module_id建立host → module映射获取内置对象详情批量拉取涉及的业务、集群、模块的实例信息getInnerObjectDetails获取自定义模型实例基于主模型链自下而上地以集群的父实例 ID 逐层查出业务下自定义模型如nation、province的实例getCustomTopoInfo组装树按从顶层到module的层级逆序rank反转把每个节点的obj、name、id以及children递归拼装成树形结构rearrangeHostDetailAndTopo。这一设计与 CMDB 的“主线模型”mainline概念强相关业务下既存在set集群、module模块这类内置模型也允许用户自定义中间层级模型如国家、省份主机通过这些层级挂载到业务拓扑上。使用建议与注意事项过滤条件优先缩小范围host_property_filter支持两层嵌套建议把筛选性强的条件如bk_host_innerip放在最外层 AND 中缩小主机集后再用 OR 扩展条件减少全量扫描。分页取数要排序limit最大 500遍历大批量主机时应固定sort如bk_host_id避免翻页数据错乱或重复。返回字段按需裁剪fields只声明业务侧真正需要的字段如bk_host_id、bk_host_innerip、bk_host_name可显著降低响应体与网络开销服务端会自行追加bk_host_id用于拓扑关联无需调用方传入。拓扑树的业务范围接口不通过 URL 指定业务返回的topo是主机实际归属的拓扑链路同一主机可能出现多个顶层父节点如同时位于不同自定义层级下因此topo是数组而非单一节点。权限要求调用方需具备主机池主机查看权限若开启with_biz还会对涉及业务进行查看级实例鉴权未授权时会返回权限错误。操作符兼容性文档中列出的between/not_between在当前版本 querybuilder 中未实现请改用greater_or_equalless_or_equal组合表达区间条件in/not_in数组元素必须类型一致。参考资料关联 API 文档list_host_detail_topology.md接口实现findhost.go路由注册service_initfunc.go请求/响应结构定义metadata/hostserver.go、metadata/hostserver.go拓扑编排逻辑logics/host.go、logics/host.go组合过滤规则引擎querybuilder 说明文档、types.go、validate.go权限解析ac/parser/host.go主机列表查询封装apimachinery/coreservice/host/api.go赞分享后端企业应用运维【免费下载链接】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按审计 ID 查询操作审计详情接口实战指南蓝鲸配置平台bk cmdb按审计 ID 查询操作审计详情接口实战指南 导读 本文围绕蓝鲸智云配置平台bk cmdb开放 API 网关后端接口 find_后端企业应用运维上一篇en_PP-OCRv5_mobile_rec_safetensors核心技术解析轻量化MobileNet架构深度剖析 下一篇无需Steam也能玩转创意工坊5个跨平台解决方案实测创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考