bk-cmdb 主机与拓扑关系查询接口 find_host_topo_relation 调用指南

• 后端
• 企业应用
• 运维

本篇技术指南围绕蓝鲸智云配置平台（bk-cmdb，BlueKing CMDB）的 ESB 开放接口find_host_topo_relation展开，讲解如何一次性获取指定业务下「主机 ↔ 集群 ↔ 模块」之间的挂载关系，覆盖请求参数、分页约束、返回结构，并深入其内部调用链（hostserver → coreservice → MongoDB 模块主机关系表），帮助读者在资源梳理、拓扑对齐、批量校验等场景中正确使用该接口。

一、接口功能定位与权限说明

find_host_topo_relation的核心能力是获取主机与拓扑的关系，即在一个业务（bk_biz_id）范围内，查询主机（host）、集群（set）、模块（module）三者之间的归属挂载关系。调用该接口需要业务访问权限（Business access permission）。

该接口属于 ESB（企业服务总线）对外暴露的 API，在仓库的 ESB 接口定义文件 docs/apidoc/cc/cc.yaml 中有明确注册：

• 对外路径：/v2/cc/find_host_topo_relation/
• 请求方式：POST
• 接口类型：query（查询类）
• 映射的内部路径：/api/v3/host/topo/relation/read（同样为POST）

也就是说，ESB 网关收到请求后，会转发到 hostserver 的/host/topo/relation/read路由。该路由在 src/scene_server/host_server/service/service_initfunc.go 中注册，对应的处理函数是GetAppHostTopoRelation。

二、请求参数说明

2.1 通用参数

每次调用需携带 ESB 鉴权与用户标识参数（对应文档模板{{ common_args_desc }}）：

2.2 接口参数

四个筛选字段（bk_biz_id、bk_set_ids、bk_module_ids、bk_host_ids）可单独或组合使用。从源码角度看，该请求体在 src/common/metadata/core_service.go 中被建模为HostModuleRelationRequest结构体，其中还包含一个文档未展开的field字段（json:"field"），用于指定返回字段，属于进阶用法。

2.3 page 分页字段

分页结构体对应 src/common/metadata/page.go 中的BasePage，除start、limit外还支持可选的sort（排序字段）与enable_count（仅统计数量）参数。

三、请求参数示例

{ "bk_app_code": "esb_test", "bk_app_secret": "xxx", "bk_username": "xxx", "bk_token": "xxx", "page": { "start": 0, "limit": 10 }, "bk_biz_id": 2, "bk_set_ids": [1, 2], "bk_module_ids": [23, 24], "bk_host_ids": [25, 26] }

该示例同时指定了业务、集群、模块、主机四类筛选条件并开启分页，含义是：查询业务 2 下，位于集群 1/2、模块 23/24 中，且主机 ID 为 25/26 的主机拓扑关系，从偏移 0 开始取 10 条。

四、返回结果示例

{ "result": true, "code": 0, "data": { "count": 2, "data": [ { "bk_biz_id": 2, "bk_host_id": 2, "bk_module_id": 2, "bk_set_id": 2, "bk_supplier_account": "0" }, { "bk_biz_id": 1, "bk_host_id": 1, "bk_module_id": 1, "bk_set_id": 1, "bk_supplier_account": "0" } ], "page": { "limit": 10, "start": 0 } }, "message": "success", "permission": null, "request_id": "f5a6331d4bc2433587a63390c76ba7bf" }

返回结果采用蓝鲸标准响应封装，request_id为本次请求的请求链 ID，便于在日志中串联定位问题。

五、返回结果参数说明

5.1 response 顶层字段

5.2 data 字段说明

5.3 data.data 字段说明

其中每条记录对应一条主机与模块的挂载关系，bk_set_id、bk_module_id、bk_host_id共同定位该关系。该结构在源码中的建模为 src/common/metadata/hostcontroller.go 的ModuleHost结构体，字段 JSON 标签与上表完全一致，且主机、模块、业务字段在序列化时使用omitempty，即值为 0 的字段不会出现在输出中。

5.4 data.page 字段说明

六、内部调用链与源码级实现原理

理解接口背后的调用链，有助于解释参数约束与错误行为。整体链路如下：

ESB 网关 /v2/cc/find_host_topo_relation/ → hostserver /host/topo/relation/read (GetAppHostTopoRelation) → hostserver Logics.GetHostModuleRelation（参数校验） → coreservice Host().GetHostModuleRelation（组装查询条件） → MongoDB cc_ModuleHostConfig 表（模块主机关系表）

6.1 hostserver 层：路由注册与请求解码

路由注册位于 src/scene_server/host_server/service/service_initfunc.go：

utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: "/host/topo/relation/read", Handler: s.GetAppHostTopoRelation})

处理函数GetAppHostTopoRelation位于 src/scene_server/host_server/service/module.go：将请求体解码为metadata.HostModuleRelationRequest后，调用Logic.GetHostModuleRelation，最终以ctx.RespEntity(result)返回结果。

6.2 hostserver 层：参数校验规则

核心校验逻辑位于 src/scene_server/host_server/logics/host.go，按顺序执行四道检查：

1. 请求体非空校验：若bk_biz_id为 0 且bk_set_ids、bk_module_ids、bk_host_ids均为空（结构体的Empty()方法判定），直接返回错误码CCErrCommHTTPBodyEmpty（1199005，对应 src/common/errInfo.go），即"请求体未设置有效数据"。
2. 分页合法性校验：调用cond.Page.IsIllegal()，当start < 0、limit > 1000（全局单页上限BKMaxPageSize = 1000，定义于 src/common/definitions.go）或limit <= 0时返回CCErrCommPageLimitIsExceeded（1199059）。例外是limit取特殊值BKNoLimit（999999999，定义于同文件第 41 行）时不受上限约束。
3. 集群数量校验：bk_set_ids超过 200 条时返回CCErrCommXXExceedLimit（1199035），错误信息指明bk_set_ids超限。
4. 模块与主机数量校验：bk_module_ids或bk_host_ids超过 500 条时同样返回 1199035 错误。

这些校验与文档中"最多 200 条 / 最多 500 条"的约束一一对应，是调用侧最容易触发的错误来源。

6.3 coreservice 层：关系数据查询

校验通过后，hostserver 通过 CoreService API 调用 coreservice。真正落库查询在 src/source_controller/coreservice/core/host/transfer/manager.go 的GetHostModuleRelation中完成：

• 基于condition.CreateCondition()按需拼接查询条件：bk_biz_id等值、bk_host_id/bk_module_id/bk_set_id走In列表匹配；
• 通过util.SetQueryOwner注入当前调用者的bk_supplier_account（供应商账号），实现租户数据隔离；
• 查询目标是common.BKTableNameModuleHostConfig即模块主机关系表，先Count统计总数，再按start/sort/limit拉取当前页数据；
• 最终封装为HostConfigData{ Count, Info: []ModuleHost, Page }返回，与文档中的data{count, data[], page}结构一致。

值得注意的是：查询条件中若所有筛选字段均为空，coreservice 会直接返回空结果而不执行全表扫描，这也解释了为什么上层要求bk_biz_id必填——避免无界查询。

七、调用实战要点与注意事项

1. 分页建议：文档与源码均建议limit取 200。单次上限 1000 由系统常量BKMaxPageSize决定（src/common/definitions.go）；数据量大时应基于data.count循环翻页（start += limit），直到取满为止。
2. 筛选条件可组合：bk_set_ids、bk_module_ids、bk_host_ids为"且"关系，传入多个集群 ID 时返回的是这些集群下全部模块的主机关系；不传则查询业务下所有关系。如需精确到具体主机，建议同时传bk_host_ids以缩小结果集。
3. 业务权限前置：调用前需确认当前bk_username具备目标业务的访问权限，否则permission字段会携带缺失的权限信息且result为 false。
4. 响应字段省略：data.data中值为 0 的字段（如bk_set_id）在 JSON 输出中可能被省略（omitempty），解析响应时应按"字段可能缺失"处理，避免直接断言字段存在。
5. 错误码速查：1199005请求体为空；1199035列表参数超限（bk_set_ids>200 或bk_module_ids/bk_host_ids>500）；1199059分页参数非法。对应定义见 src/common/errInfo.go。

八、典型应用场景

• 主机资源梳理：批量导出某业务下所有主机所属的集群与模块，生成"业务-集群-模块-主机"四元组清单，用于资产盘点；
• 拓扑一致性校验：结合bk_host_ids精确核对指定主机当前挂载的模块是否与预期一致（如变更发布后校验）；
• 主机自动化编排：在主机转移、模块变更前，先查询关系快照，作为操作前数据对比与操作后复核的依据（源码中多处使用DistinctHostIDByTopoRelationRequest复用类似查询逻辑，如 src/scene_server/host_server/logics/hostsearch.go）。

该接口是 bk-cmdb 提供主机拓扑关系读取能力的标准入口，配合 ESB 鉴权参数即可在第三方系统（运维平台、作业平台等）中稳定复用。

• 后端
• 企业应用
• 运维