蓝鲸配置平台 bk-cmdb 主机详情与拓扑查询接口 `list_host_detail_topology` 实战指南

原创2026-10-14 11:53:522,126 阅读
文章标签:后端企业应用微服务

蓝鲸配置平台 bk-cmdb 主机详情与拓扑查询接口 list_host_detail_topology 实战指南

导读

list_host_detail_topology 是蓝鲸配置平台(BlueKing CMDB,bk-cmdb)对外提供的主机详情 + 所属拓扑联合查询接口:它根据主机属性条件筛选出目标主机,返回每台主机的基础属性字段,并同时返回该主机在业务主线拓扑中所处的完整层级路径(如 国家 → 省份 → 集群 → 模块)。本指南以 docs/apidoc/cc/zh_hans/list_host_detail_topology.md 为主体,结合仓库源码中的参数校验、路由注册与拓扑组装实现,帮你一次性掌握该接口的请求参数结构、host_property_filter 组合过滤规则、分页字段、返回结构与权限要求,并能在实际业务中直接组装可运行的请求与解析响应。

一、接口概览:功能、路径与权限

该接口的功能描述为:根据主机条件信息查询主机详情及其所属的拓扑信息。它面向"主机池"场景(不限定具体业务),权限要求为主机池主机查看权限。

从网关配置文件 docs/apidoc/cc/cc.yaml 可以看到该接口在蓝鲸 API 网关上注册的信息:

项目 值
网关路径 POST /v2/cc/list_host_detail_topology/
内部目标路径 POST /api/v3/findmany/hosts/detail_topo
接口类型 query
调用组件 generic.v2.cc.cc_component

也就是说,外部调用方通过网关的 /v2/cc/list_host_detail_topology/ 发起请求后,网关将其转发到 bk-cmdb 的 hostserver(主机服务)内部路由 /findmany/hosts/detail_topo。该路由在 src/scene_server/host_server/service/service_initfunc.go 中注册,对应的处理器为 s.ListHostDetailAndTopology,其实现位于 src/scene_server/host_server/service/findhost.go。

在权限管控层面,src/ac/parser/host.go 将命中 /api/v3/findmany/hosts/detail_topo 的请求映射为 HostInstance 资源类型 + FindMany 动作,交由统一的鉴权框架校验"主机池主机查看"类权限。

二、请求参数详解

2.1 公共参数(common_args_desc)

所有蓝鲸配置平台 API 均需携带公共鉴权参数(即文档中的 {{ common_args_desc }} 占位符所描述的内容),包括:

字段 类型 描述
bk_app_code string 应用 ID,即蓝鲸智云 API 网关上的应用标识
bk_app_secret string 应用密钥,用于接口调用认证
bk_username string 用户名
bk_token string 登录态 token,与 bk_username 配合完成用户鉴权

这些公共参数的具体取值方式取决于你的网关接入形态(蓝鲸桌面登录态或 API 密钥方式),请按实际环境配置。

2.2 接口参数(Interface Parameters)

接口自身的业务参数共三个:

字段 类型 必选 描述
page dict 是 查询分页条件
host_property_filter object 否 主机属性组合查询条件,用于按属性过滤主机
fields array 是 主机属性字段列表,控制返回结果中 host 对象包含哪些字段,按需求填写

其中 fields 字段在服务端是必填校验项:从 src/common/metadata/hostserver.go 的 Validate() 实现可见,若 Fields 为空数组,接口会直接返回参数无效错误。同时服务端会在 fields 基础上自动追加 bk_host_id(见 ListHostDetailAndTopology 实现中的 Fields: append(options.Fields, common.BKHostIDField),src/scene_server/host_server/service/findhost.go),因为后续组装拓扑时需要以主机 ID 关联主机与模块关系。

2.3 host_property_filter:组合过滤规则

host_property_filter 是主机属性字段的过滤规则组合,用于按主机属性字段搜索主机。它支持 AND 与 OR 两种组合方式,且可以嵌套,最多嵌套 2 层。每条过滤规则本质是一个四元组:field(字段名)、operator(操作符)、value(操作数)。

过滤规则对象结构:

字段 类型 必选 描述
condition string 否 组合查询条件,取值为 AND 或 OR
rules array 否 规则列表,元素可以是原子规则或嵌套的组合规则

rules 中的原子规则:

字段 类型 必选 描述
field string 是 字段名,如 bk_host_innerip、bk_os_type、bk_cloud_id
operator string 是 操作符,可选值:equal、not_equal、in、not_in、less、less_or_equal、greater、greater_or_equal、between、not_between
value - 否 操作数,不同的 operator 对应不同的 value 格式

关于"最多嵌套 2 层"的说明,可以从源码中得到精确印证:在 src/common/querybuilder/types.go 中定义了 MaxDeep = 3,注释明确写着"嵌套层级的深度按树的高度计算,查询条件最大深度为 3 即最多嵌套 2 层"。同时 src/common/metadata/hostserver.go 在 host_property_filter 非空时会调用 QueryFilter.Validate()(要求数组元素类型一致)并校验 GetDeep() > querybuilder.MaxDeep,超出即返回参数错误。这套过滤规则底层由 src/common/querybuilder 模块实现,它将 JSON 形式的规则树解析并最终转换为 MongoDB 查询条件(Rule 接口的 ToMgo() 方法),支持 src/common/querybuilder/README.md 中列出的完整操作符族(除文档所列通用操作符外,还包括时间比较、字符串匹配、空值判断、字段存在判断等扩展操作符)。

2.4 page:分页参数

字段 类型 必选 描述
start int 是 记录开始位置(偏移量,从 0 开始)
limit int 是 每页限制条数,最大值为 500
sort string 否 排序字段,如 bk_host_id

limit 的最大值 500 在源码中有明确约束:常量 BKMaxInstanceLimit = 500 定义于 src/common/definitions.go,而 ListHostsDetailAndTopoOption.Validate() 中会检查 option.Page.Limit > common.BKMaxInstanceLimit 并返回参数错误(src/common/metadata/hostserver.go)。因此分页查询超过 500 条时需要按页码(如 start: 500、start: 1000)分多次拉取。

2.5 with_biz 扩展参数(源码补充)

从源码数据结构 src/common/metadata/hostserver.go 可以看出,该接口的请求选项 ListHostsDetailAndTopoOption 还支持一个 with_biz(bool)字段——当它为 true 时,返回的拓扑会包含业务(business)层节点信息,并且服务端在 ArrangeHostDetailAndTopology 返回业务 ID 列表后,会对这些业务做"查看业务"资源级别的二次鉴权(见 src/scene_server/host_server/service/findhost.go)。文档正文未展开该参数,但如果你需要拿到"业务 → 集群 → 模块"完整链路(而不仅是自定义层级模型到模块),可以显式携带 with_biz: true。

三、请求参数示例(可直接复用)

{
    "bk_app_code": "esb_test",
    "bk_app_secret": "xxx",
    "bk_username": "xxx",
    "bk_token": "xxx",
    "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
                    }
                ]
            }
        ]
    }
}

这个示例本身就是一个标准的两层嵌套过滤:最外层用 AND 组合两条规则——① 内网 IP 等于 192.168.1.1;② 一个 OR 组合,表示操作系统类型不在 ["3"] 中 或 管控区域等于 0。整体语义为:bk_host_innerip == "192.168.1.1" AND (bk_os_type NOT IN ["3"] OR bk_cloud_id == 0)。

注意组合规则与原子规则在结构上的差别:组合节点(带 condition + rules)不写 field/operator/value,而原子节点(带 field/operator/value)不写 condition/rules。这一点在 src/common/querybuilder/README.md 的 demo 中同样如此,组装时可以参照该 README 中的示例继续扩展。

四、返回结果示例

4.1 完整响应样例

{
    "result": true,
    "code": 0,
    "message": "success",
    "permission": null,
    "request_id": "e43da4ef221746868dc4c837d36f3807",
    "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
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

从返回样例可以读出三条重要信息:

  1. data.count 为命中总数,data.info 数组元素与查询结果一一对应;即便 info 为空,服务端也会返回 count: 0 与空数组(见 src/scene_server/host_server/service/findhost.go)。
  2. 每台主机的 topo 可能包含多条树路径——一台主机可以同时挂载在多个模块/集群下,每条路径都从最顶层的自定义层级模型(如 nation 国家)一路下钻到 set(集群)与 module(模块)。
  3. 位于主机池(资源池)中的主机(如示例中的 空闲机池 → 故障机),其 topo 从 set 开始,即资源池本身以集群/模块形态参与拓扑,且不包含自定义层级模型节点。

4.2 响应顶层字段说明(response)

字段 类型 描述
result bool 请求成功与否。true 表示请求成功,false 表示请求失败
code int 错误编码。0 表示 success,>0 表示失败错误
message string 请求失败时返回的错误信息
permission object 权限信息
request_id string 请求链 ID,用于链路追踪与问题排查
data object 请求返回的数据

4.3 data 与 data.info 结构

data:

字段 类型 描述
count int 记录条数
info array 主机数据和拓扑信息

data.info 数组中的每个元素:

字段 类型 描述
host dict 主机实际数据(字段由请求中的 fields 控制)
topo array 主机拓扑信息,即该主机所属的拓扑节点树

五、返回字段详解

5.1 data.info.host:主机属性字段

下表是系统内置主机属性字段的说明;除此之外,返回值还取决于你在平台上自定义的主机属性字段(模型中扩展的属性)。host 中实际出现的字段由请求参数 fields 决定,未在 fields 中声明的字段不会返回。

字段 类型 描述
bk_host_name string 主机名
bk_host_innerip string 内网 IP
bk_host_id int 主机 ID
bk_cloud_id int 管控区域
import_from string 主机导入来源,以 api 方式导入为 3
bk_asset_id string 固资编号
bk_cloud_inst_id string 云主机实例 ID
bk_cloud_vendor string 云厂商
bk_cloud_host_status string 云主机状态
bk_comment string 备注
bk_cpu int CPU 逻辑核心数
bk_cpu_architecture string CPU 架构
bk_cpu_module string CPU 型号
bk_disk int 磁盘容量(GB)
bk_host_outerip string 主机外网 IP
bk_host_innerip_v6 string 主机内网 IPv6
bk_host_outerip_v6 string 主机外网 IPv6
bk_isp_name string 所属运营商
bk_mac string 主机内网 MAC 地址
bk_mem int 主机内存容量(MB)
bk_os_bit string 操作系统位数
bk_os_name string 操作系统名称
bk_os_type string 操作系统类型
bk_os_version string 操作系统版本
bk_outer_mac string 主机外网 MAC 地址
bk_province_name string 所在省份
bk_service_term int 质保年限
bk_sla string SLA 级别
bk_sn string 设备 SN
bk_state string 当前状态
bk_state_name string 所在国家
operator string 主要维护人
bk_bak_operator string 备份维护人

注意:此处的返回值仅对系统内置的属性字段做了说明,其余返回值取决于用户自己定义的属性字段。

5.2 data.info.topo:拓扑树节点

topo 是一棵(或多棵)嵌套树,每个节点包含实例信息与子节点列表:

字段 类型 描述
inst object 该节点实例的详情信息
inst.obj string 该节点的模型类型,如 set/module 及自定义层级模型类型
inst.name string 该节点的实例名
inst.id int 该节点的实例 ID
children object array 当前实例节点的子节点详情信息,可能有多个
children.inst object 该子节点的实例详情信息
children.children string 该节点的子节点详情信息

这棵树的内部数据模型对应源码中的 HostDetailWithTopo / HostTopoNode / NodeInstance(src/common/metadata/hostserver.go):

type 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"`
}

children 为 null 表示该节点已经是树的叶子(如 module 层),一个节点下可以挂多个 children(如一个集群下挂多个模块)。

六、服务端实现链路:从请求到响应

理解接口的服务端处理流程,有助于排查返回结果与预期不符的问题。核心处理函数 ListHostDetailAndTopology(src/scene_server/host_server/service/findhost.go)的执行步骤如下:

  1. 参数解析与校验:将请求体解码为 ListHostsDetailAndTopoOption,调用 Validate() 校验 page、fields、host_property_filter(深度与规则合法性),校验失败即返回参数错误。
  2. 设置读偏好:ctx.SetReadPreference(common.SecondaryPreferredMode),即优先从 MongoDB 从节点读取,降低主库压力。
  3. 查询主机列表:构造 ListHosts(HostPropertyFilter + Fields(自动补 bk_host_id) + Page),调用 CoreAPI.CoreService().Host().ListHosts 查出分页后的主机集合;若结果为空,直接返回 count: 0 与空数组。
  4. 组装拓扑:调用 Logic.ArrangeHostDetailAndTopology(kit, withBiz, hosts.Info) 为每台主机拼装所属拓扑树。该函数(src/scene_server/host_server/logics/host.go)内部依次执行:
    • 读取主线拓扑层级顺序(getTopologyRank,决定返回树从哪层模型开始);
    • 按主机 ID 批量查询"主机-模块"关系(GetHostRelations),得到每台主机归属的模块列表;
    • 批量查询业务、集群、模块的详情(getInnerObjectDetails);
    • 逐层向上补齐自定义层级模型的实例信息(getCustomTopoInfo);
    • 最终按层级重新组织成 HostDetailWithTopo 树(rearrangeHostDetailAndTopo),并将 rank 反转为"顶层 → 底层"的展示顺序。
  5. 业务级二次鉴权(可选):若 with_biz 为 true 且启用了鉴权管理,会对涉及的业务实例执行"查看业务"授权校验。
  6. 返回结果:通过 RespEntityWithCount(count, topo) 输出 data.count 与 data.info。

值得一提的是,同一套拓扑组装逻辑也被主机搜索相关接口复用(如 src/scene_server/host_server/logics/host.go 处同样调用了 ArrangeHostDetailAndTopology),因此本接口返回的 topo 结构与平台其他"主机带拓扑"查询结果保持一致。

七、常见问题与注意事项

  • fields 不能为空:服务端将空 fields 视为参数错误(src/common/metadata/hostserver.go);即使你只想拿拓扑,也至少需要传入一个字段(如 bk_host_id)。
  • limit 上限 500:单页超过 500 条会被拒绝,需要配合 start 翻页(src/common/definitions.go)。
  • 过滤规则最多嵌套 2 层:querybuilder.MaxDeep = 3 按树高度计算即两层嵌套(src/common/querybuilder/types.go),超出会返回 host_property_filter exceeded max allowed deep 之类的参数错误。
  • value 类型需与字段匹配:host_property_filter 校验要求同一数组内的元素类型一致(NeedSameSliceElementType: true,见 src/common/metadata/hostserver.go);如 in/not_in 的数组内不能混用字符串与数字。
  • 一台主机可能返回多条 topo 路径:因为主机可同时归属多个集群/模块,解析响应时不要假设 topo 只有一条。
  • 资源池主机的拓扑从 set 开始:主机池中的主机(如"空闲机池/故障机")没有业务与自定义层级模型上下文,topo 路径较短。
  • host 返回字段由 fields 决定:未在 fields 中声明的内置属性不会返回;自定义属性同理,需显式声明。
  • 权限要求:调用方需具备主机池主机查看权限;携带 with_biz: true 时还会对返回涉及的业务做"查看业务"鉴权,调用前请确认账号权限充足。

结语

list_host_detail_topology 将"主机属性检索"与"拓扑归属查询"合并为一次调用,是 bk-cmdb 中构建"主机视角"资产视图的高频接口。结合本文的请求/返回结构说明与服务端实现链路,你可以准确构造过滤条件、控制返回字段与分页,并正确解析嵌套的拓扑树结果。如需进一步掌握过滤规则的完整操作符体系(时间比较、字符串匹配、空值判断等),可继续阅读仓库内的 src/common/querybuilder/README.md;本接口完整文档以 docs/apidoc/cc/zh_hans/list_host_detail_topology.md 为准。

登录后查看全文
bk-cmdb