后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载本文围绕蓝鲸智云配置平台bk-cmdb开放接口find_host_biz_relations查询主机业务关系信息展开讲解如何通过主机 ID 批量查询主机所属的业务、集群set、模块module关系。读完本文你将掌握该接口的 ESB 网关路径与后端真实路由、请求/响应参数规范、500 条上限的校验机制以及从 host_server 到 coreservice 的完整调用链与数据库落点能够在蓝鲸 ESB 或代码中正确、高效地调用并解读该接口。一、接口概览与定位find_host_biz_relations是 bk-cmdb 对外开放的一组查询类api_type: query接口用于根据主机 ID 批量查询主机与业务之间的关系。它在蓝鲸 ESB企业服务总线中的访问路径为POST /v2/cc/find_host_biz_relations/根据 docs/apidoc/cc/cc.yaml 的接口注册定义该 ESB 路径只是一个代理入口实际请求会被转发到 bk-cmdb 内部的host_server服务配置项值path/v2/cc/find_host_biz_relations/suggest_methodPOSTapi_typequerycomp_codenamegeneric.v2.cc.cc_componentdest_path/api/v3/hosts/modules/readdest_http_methodPOST同时在蓝鲸 API 网关apigateway的资源定义 docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml 中后端资源POST /api/v3/hosts/modules/read的operationId同样为find_host_biz_relations并默认挂载了限流插件bk-rate-limit每 1 秒 100 个 token。与它功能相近但视角不同的接口是find_host_topo_relation获取主机与拓扑的关系其内部路由为POST /api/v3/host/topo/relation/read同样由 host_server 处理见 src/scene_server/host_server/service/service_initfunc.go 的GetAppHostTopoRelation两者的差别在于find_host_biz_relations直接返回主机与业务、集群、模块的平铺关系记录而拓扑关系接口还会带上拓扑实例的层级信息。本接口返回的每一条记录都代表了主机与一个模块的一条挂载关系一台主机可能出现在多个业务、多个集群、多个模块中因此返回data是一个数组。二、请求参数详解2.1 通用请求参数调用蓝鲸 ESB 接口时需要在请求体中携带身份认证与公共参数对应文档中的{{ common_args_desc }}字段类型必填说明bk_app_codestring是应用 ID如esb_testbk_app_secretstring是应用密钥bk_usernamestring是操作者用户名bk_tokenstring是登录态 Token2.2 接口参数字段类型必填说明bk_host_idarray是主机 ID 数组ID 数量不能超过 500bk_biz_idint否业务 ID指定后仅返回该业务下的主机关系2.3 请求参数示例{ bk_app_code: esb_test, bk_app_secret: xxx, bk_username: xxx, bk_token: xxx, bk_biz_id: 1, bk_host_id: [ 3, 4 ] }三、接口参数在源码中的校验逻辑find_host_biz_relations对应的后端处理器是 host_server 服务中的GetHostModuleRelation。首先在路由注册处/hosts/modules/read被绑定到该方法src/scene_server/host_server/service/service_initfunc.go// get host module relation in app utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: /hosts/modules/read, Handler: s.GetHostModuleRelation})处理器实现位于 src/scene_server/host_server/service/module.go先将请求体解码为HostModuleRelationParameter然后执行参数校验再封装成内部请求HostModuleRelationRequest交给逻辑层。请求体对应的参数结构体定义在 src/common/metadata/hostserver.go// HostModuleRelationParameter get host and module relation parameter type HostModuleRelationParameter struct { AppID int64 json:bk_biz_id HostID []int64 json:bk_host_id }其Validate()方法给出了文档所述“数量不能超过 500”的准确实现func (h *HostModuleRelationParameter) Validate() (rawError errors.RawErrorInfo) { if len(h.HostID) 0 || len(h.HostID) common.BKMaxInstanceLimit { return errors.RawErrorInfo{ ErrCode: common.CCErrArrayLengthWrong, Args: []interface{}{bk_host_id, common.BKMaxInstanceLimit}, } } return errors.RawErrorInfo{} }这里有两个关键点BKMaxInstanceLimit 500定义在 src/common/definitions.go是全局的单次批量上限常量。bk_host_id既不能为空数组也不能超过 500 个否则返回错误码CCErrArrayLengthWrong 1199089见 src/common/errInfo.go。参数校验发生在 host_server 入口层因此即使只查一台主机也必须以数组形式传入如bk_host_id: [3]这与其他许多单值字段的接口习惯不同。四、响应参数说明4.1 响应结构字段类型说明resultbool请求是否成功true 成功 / false 失败codeint返回码0 表示成功0 表示失败错误码messagestring失败时的错误信息permissionobject权限信息request_idstring请求链路 IDdataobject请求返回的数据4.2 data 字段说明字段类型说明bk_biz_idint业务 IDbk_host_idint主机 IDbk_module_idint模块 IDbk_set_idint集群 IDbk_supplier_accountstring开发商账号4.3 响应示例{ result:true, code:0, message:success, permission: null, request_id: e43da4ef221746868dc4c837d36f3807, data: [ { bk_biz_id: 3, bk_host_id: 3, bk_module_id: 59, bk_set_id: 11, bk_supplier_account: 0 }, { bk_biz_id: 3, bk_host_id: 3, bk_module_id: 60, bk_set_id: 11, bk_supplier_account: 0 }, { bk_biz_id: 3, bk_host_id: 3, bk_module_id: 61, bk_set_id: 12, bk_supplier_account: 0 }, { bk_biz_id: 3, bk_host_id: 4, bk_module_id: 60, bk_set_id: 11, bk_supplier_account: 0 } ] }从示例可以看出主机3同时挂载在模块59/60/61分属集群11/12主机4挂载在模块60集群11两者同属业务3。因此返回记录条数 各主机在各业务下挂载模块的总条数而不是主机个数。4.4 data 字段与源码数据结构的对应响应中的data数组对应源码中的ModuleHost结构体src/common/metadata/hostcontroller.go// ModuleHost TODO type ModuleHost struct { AppID int64 json:bk_biz_id,omitempty bson:bk_biz_id HostID int64 json:bk_host_id,omitempty bson:bk_host_id ModuleID int64 json:bk_module_id,omitempty bson:bk_module_id SetID int64 json:bk_set_id,omitempty bson:bk_set_id OwnerID string json:bk_supplier_account,omitempty bson:bk_supplier_account }注意omitempty标签的含义当某条记录的字段为空值时例如主机尚未归属任何模块对应的 JSON 字段可能被省略解析响应时需按“可能缺失”处理。从 host_server 返回给上层时实际包装的响应结构是HostModuleRespsrc/common/metadata/hostcontroller.goData类型为[]ModuleHost与文档中的data数组一一对应。五、底层实现从 host_server 到 coreservice 的完整调用链在GetHostModuleRelation处理器内部service 层将外部参数组装为内部请求结构HostModuleRelationRequestsrc/common/metadata/core_service.go// HostModuleRelationRequest gethost module relation request parameter type HostModuleRelationRequest struct { ApplicationID int64 json:bk_biz_id bson:bk_biz_id field:bk_biz_id mapstructure:bk_biz_id SetIDArr []int64 json:bk_set_ids bson:bk_set_ids field:bk_set_ids mapstructure:bk_set_ids HostIDArr []int64 json:bk_host_ids bson:bk_host_ids field:bk_host_ids mapstructure:bk_host_ids ModuleIDArr []int64 json:bk_module_ids bson:bk_module_ids field:bk_module_ids mapstructure:bk_module_ids Page BasePage json:page bson:page field:page mapstructure:page Fields []string json:field bson:field field:field mapstructure:field }该结构比外部参数更丰富支持按bk_biz_id、bk_set_ids、bk_host_ids、bk_module_ids组合过滤并带分页page与字段裁剪field。处理器只把外部传入的bk_host_id和可选的bk_biz_id填入其中并将分页 limit 设为common.BKNoLimit不限制一次性返回全部见 src/scene_server/host_server/service/module.go。接下来进入 host_server 逻辑层GetHostModuleRelationsrc/scene_server/host_server/logics/host.go这里还有一层兜底校验条件为空Empty()为 true时返回CCErrCommHTTPBodyEmpty 1199005分页非法时返回CCErrCommPageLimitIsExceeded 1199059bk_set_ids超过 200 返回CCErrCommXXExceedLimit 1199035bk_module_ids超过 500、bk_host_ids超过 500 同样返回CCErrCommXXExceedLimit。随后逻辑层通过CoreService().Host().GetHostModuleRelation将请求转发给 coreservice核心数据服务最终由 coreservice 的TransferManager执行真正的数据库查询src/source_controller/coreservice/core/host/transfer/manager.go。核心逻辑是把bk_biz_id / bk_host_ids / bk_module_ids / bk_set_ids分别拼装为等值Eq或In条件再查询cc_ModuleHostConfig表表名常量BKTableNameModuleHostConfig定义在 src/common/tablenames.go先Count出总条数再按分页取数并反序列化到[]metadata.ModuleHost最终返回HostConfigData{Count, Info, Page}结构cond util.SetQueryOwner(moduleHostCond.ToMapStr(), kit.SupplierAccount) cnt, err : mongodb.Client().Table(common.BKTableNameModuleHostConfig).Find(cond).Fields(input.Fields...).Count(kit.Ctx) ... db : mongodb.Client().Table(common.BKTableNameModuleHostConfig). Find(cond). Fields(input.Fields...). Start(uint64(input.Page.Start)). Sort(input.Page.Sort) ... err db.All(kit.Ctx, hostModuleArr)cc_ModuleHostConfig是主机与模块挂载关系的核心表一条记录代表“一台主机挂载在一个业务模块下”表内同时冗余存储了bk_biz_id / bk_set_id这正是该接口能一次性返回业务、集群、模块三层信息的存储基础。整体调用链可归纳为ESB /v2/cc/find_host_biz_relations/ └─► apiserver /api/v3/hosts/modules/read └─► host_server: GetHostModuleRelation (service/module.go) └─► host_server 逻辑层 (logics/host.go) └─► coreservice: TransferManager.GetHostModuleRelation └─► MongoDB 表 cc_ModuleHostConfig六、在代码与前端中的实际使用方式6.1 通过 apimachinery SDK 调用bk-cmdb 的 Go 客户端封装了该接口见 src/apimachinery/apiserver/api.go// GetHostModuleRelation TODO func (a *apiServer) GetHostModuleRelation(ctx context.Context, h http.Header, params mapstr.MapStr) (resp *metadata.HostModuleResp, err error) { resp new(metadata.HostModuleResp) subPath : /hosts/modules/read err a.client.Post(). WithContext(ctx). Body(params). SubResourcef(subPath). WithHeaders(h). Do(). IntoCmdbResp(resp) return }该函数声明在 src/apimachinery/apiserver/apiserver.go 的apiServer接口中返回类型就是上一节提到的*metadata.HostModuleResp。6.2 分批调用的工程实践Excel 导出场景由于单次bk_host_id最多 500 个仓库内 src/web_server/service/excel/core/topo_func.go 在导出拓扑主机数据时给出了标准的分批处理模式把一批主机 ID 按每 500 个切分逐批调用GetHostModuleRelation再把每条关系的HostID映射到AppID从而构造“主机 → 业务”的映射表hostBizMap : make(map[int64]int64) // the length of GetHostModuleRelations param bk_host_id cant bigger than 500 for idx : 0; idx hostLen; idx 500 { endIdx : idx 500 if endIdx hostLen { endIdx hostLen } ids : hostIDs[idx:endIdx] params : mapstr.MapStr{ common.BKHostIDField: ids, } resp, err : d.ApiClient.GetHostModuleRelation(kit.Ctx, kit.Header, params) ... for _, relation : range resp.Data { hostBizMap[relation.HostID] relation.AppID } }当主机数量较大时务必在业务代码中按 500 分批否则会触发入口参数校验错误同时建议对分批调用做错误与超时处理避免单批失败导致全量导出中断。6.3 前端调用前端 Vue 项目中主机与模块关系的相关请求统一封装在 src/ui/src/store/modules/api/host-relation.js 的hostRelationstore 中通过$http.post(hosts/..., params, config)与 web_server 交互如hosts/modules批量转移、hosts/modules/fault故障机模块等。find_host_biz_relations更常见的落地方式是后端服务或 ESB 脚本直接调用用于批量确定主机归属。七、常见错误与排查建议现象可能原因处理方式返回code: 1199089CCErrArrayLengthWrongbk_host_id为空数组或超过 500 个检查数组长度按 500 分批重试返回code: 1199035CCErrCommXXExceedLimit内部链路中bk_host_ids/bk_module_ids超限对应接口分别控制主机 ≤500、模块 ≤500、集群 ≤200返回code: 1199005CCErrCommHTTPBodyEmpty未传任何过滤条件如仅传空数组至少传入非空的bk_host_id返回的data比预期条数多一台主机挂载在多个模块/集群或跨多个业务结合bk_biz_id过滤或按bk_set_id/bk_module_id聚合去重解析data时某些字段缺失ModuleHost结构体带omitempty空值字段被省略按可选字段解析先确认bk_host_id存在再取其他字段八、总结find_host_biz_relations是 bk-cmdb 中“以主机为入口、向上追溯业务归属”的标准查询接口ESB 路径/v2/cc/find_host_biz_relations/经 apigateway 转发到POST /api/v3/hosts/modules/read由 host_server 的GetHostModuleRelation处理器完成参数校验bk_host_id1500 个再经 coreservice 查询cc_ModuleHostConfig表返回主机与业务/集群/模块的平铺挂载关系。开发者在集成时只需记住三点必须用 POST、主机 ID 必须走数组且每批不超过 500、返回的每条记录是一次模块挂载而非一台主机即可在 ESB 编排、Go 后端或前端数据链路中稳定复用这一能力。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸 CMDB 开放接口实战find_host_biz_relations 查询主机业务归属关系蓝鲸 CMDB 开放接口实战find_host_biz_relations 查询主机业务归属关系 本篇技术指南聚焦蓝鲸智云配置平台BlueKing CMDB后端企业应用运维蓝鲸 bk-cmdb 主机查询收藏Host FavoritesAPI 全解析从接口调用到底层实现蓝鲸 bk cmdb 主机查询收藏Host FavoritesAPI 全解析从接口调用到底层实现 本文以蓝鲸智云配置平台bk cmdb归档的 docs后端企业应用运维蓝鲸 CMDBbk-cmdb查询业务拓扑树简要信息接口 find_biz_tree_brief_info 实战指南蓝鲸 CMDBbk cmdb查询业务拓扑树简要信息接口 find_biz_tree_brief_info 实战指南 本文深入讲解蓝鲸智云配置平台BlueK后端企业应用运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考