企业官网建设流程全解析

• 后端
• 企业应用
• 运维

本篇技术指南聚焦蓝鲸智云配置平台（BlueKing CMDB）的开放接口find_host_biz_relations，讲解如何根据主机 ID 批量查询主机与业务、集群、模块之间的归属关系，覆盖请求参数约束、调用与响应示例、底层数据表与核心调用链，帮助开发者在二次开发、主机盘点与业务拓扑对账场景中准确使用该接口。

接口概述：从网关路径到内部实现

find_host_biz_relations是一个查询类（query）开放接口，语义为“根据主机 ID 查询业务相关信息”，即给定一台或多台主机的 ID，返回这些主机当前挂载在哪些业务、集群、模块之下。

在蓝鲸 API Gateway 中，该接口对外暴露的访问路径为POST /v2/cc/find_host_biz_relations/。接口映射关系定义在仓库的 docs/apidoc/cc/cc.yaml：

- path: /v2/cc/find_host_biz_relations/ name: find_host_biz_relations label: 查询主机业务关系信息 suggest_method: POST api_type: query dest_path: /api/v3/hosts/modules/read dest_http_method: POST

可以看到，网关层将请求转发到 CMDB 内部的POST /api/v3/hosts/modules/read。该内部路由在 hostserver 中注册，对应处理函数为GetHostModuleRelation（见 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})

此外，在 docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml 的 Swagger 资源定义中，该资源以operationId: find_host_biz_relations标识，网关默认不公开（isPublic: false），允许申请权限（allowApplyPermission: true），并配置了默认限流（每 1 秒 100 个 token），调用方需要先通过蓝鲸 API 网关申请该接口的访问权限。

请求参数详解

接口请求体为 JSON，参数说明如下（对应文档 docs/apidoc/apigw/open/zh/find_host_biz_relations.md）：

两个参数的核心约束与行为说明：

• bk_host_id（必选）：主机 ID 数组。服务端会对其长度做强校验，上限为BKMaxInstanceLimit = 500（定义于 src/common/definitions.go）。校验逻辑位于 src/common/metadata/hostserver.go：

  type HostModuleRelationParameter struct { AppID int64 `json:"bk_biz_id"` HostID []int64 `json:"bk_host_id"` } 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{} }

  即：bk_host_id为空数组、或个数超过 500 时，将直接返回错误码CCErrArrayLengthWrong（数值为 1199089，见 src/common/errInfo.go），提示数组长度非法。因此批量查询时需要自行分片，确保每次调用传入的主机 ID 不超过 500 个。

• bk_biz_id（可选）：业务 ID。传入时接口只返回该业务范围内主机与模块的挂载关系；不传或传 0 时，则不做业务维度过滤，返回这些主机在所有业务下的归属关系。这一点可以从 hostserver 的处理逻辑得到印证（见 src/scene_server/host_server/service/module.go）：

  cond := &metadata.HostModuleRelationRequest{ HostIDArr: data.HostID, Page: metadata.BasePage{ Limit: common.BKNoLimit, }, } if data.AppID != 0 { cond.ApplicationID = data.AppID }

  内部查询不分页（Limit设为BKNoLimit），即一次返回全部匹配关系；同时业务 ID 在逻辑层还会参与条件拼装（见下文调用链）。

调用示例

请求使用POST方法，Content-Type 为application/json，请求体示例（文档原始示例）：

{ "bk_biz_id": 1, "bk_host_id": [ 3, 4 ] }

该示例的含义是：在业务 1 的范围内，查询主机 3 和主机 4 挂载在哪些模块（进而归属哪些集群）之下。若省略bk_biz_id，则等价于查询主机 3、4 在全部业务中的归属关系。

响应示例与字段说明

响应示例

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

响应参数说明

其中permission为权限相关信息：当用户对目标业务/资源无权限时，该字段会携带申请权限所需的信息（有权限时为 null）。

data字段说明：

从响应示例可以观察到该接口的两个重要特征：

1. 一对多关系：一台主机可以同时挂载在多个模块下。示例中主机 3 返回了 3 条记录，分别属于模块 59/60/61（其中模块 59、60 在集群 11，模块 61 在集群 12），data数组按“主机 × 模块”维度逐条展开；
2. 业务隔离：返回的每条记录都携带bk_biz_id与bk_supplier_account，便于在多业务、多开发商账户并存的环境下区分归属。

源码级原理：接口背后的完整调用链

该接口的返回数据实际来自主机与模块的挂载关系表cc_ModuleHostConfig（表名常量定义于 src/common/tablenames.go）。完整调用链可归纳为：

API Gateway (/v2/cc/find_host_biz_relations/) → hostserver 内部路由 POST /api/v3/hosts/modules/read → Service.GetHostModuleRelation（[src/scene_server/host_server/service/module.go](https://link.gitcode.com/i/c26e23ff8e473d232def53d45b60439f)） → Logics.GetHostModuleRelation（[src/scene_server/host_server/logics/host.go](https://link.gitcode.com/i/72025229e924896e5db658f2ae25db13)） → coreservice 的 GetHostModuleRelation（经 [src/apimachinery/apiserver/api.go](https://link.gitcode.com/i/4b58f8fcc0c31241b3df3fc5f398561d) 的 REST 客户端调用） → 查询 cc_ModuleHostConfig 表（[src/source_controller/coreservice/core/host/transfer/manager.go](https://link.gitcode.com/i/7eb3ec9c564ec817154318cb796ce4dc)）

在逻辑层Logics.GetHostModuleRelation中（src/scene_server/host_server/logics/host.go），除了 hostserver 入口已做的bk_host_id校验外，还会对批量参数做额外限制：

if len(cond.SetIDArr) > 200 { return nil, kit.CCError.CCErrorf(common.CCErrCommXXExceedLimit, "bk_set_ids", 200) } if len(cond.ModuleIDArr) > 500 { return nil, kit.CCError.CCErrorf(common.CCErrCommXXExceedLimit, "bk_module_ids", 500) } if len(cond.HostIDArr) > 500 { return nil, kit.CCError.CCErrorf(common.CCErrCommXXExceedLimit, "bk_host_ids", 500) }

而 coreservice 最终落库查询时（src/source_controller/coreservice/core/host/transfer/manager.go），会按bk_biz_id、bk_host_id、bk_module_id、bk_set_id动态拼装 MongoDB 查询条件，并自动叠加开发商账户（SetQueryOwner）隔离：

moduleHostCond := condition.CreateCondition() if input.ApplicationID > 0 { moduleHostCond.Field(common.BKAppIDField).Eq(input.ApplicationID) } if len(input.HostIDArr) > 0 { moduleHostCond.Field(common.BKHostIDField).In(input.HostIDArr) } if len(input.ModuleIDArr) > 0 { moduleHostCond.Field(common.BKModuleIDField).In(input.ModuleIDArr) } if len(input.SetIDArr) > 0 { moduleHostCond.Field(common.BKSetIDField).In(input.SetIDArr) } ... cnt, err := mongodb.Client().Table(common.BKTableNameModuleHostConfig).Find(cond).Fields(input.Fields...).Count(kit.Ctx)

返回值中的每条记录对应结构体ModuleHost（src/common/metadata/hostcontroller.go），其 JSON 字段与上述data字段一一对应：

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

值得说明的是：bk_module_id与bk_set_id是冗余存储在关系表中的冗余快照字段，因此本接口无需二次 join 集群表即可直接返回集群 ID，读取效率高，适合批量盘点场景。

使用注意与限制

1. 单次查询主机数上限 500：超出后返回错误码1199089（数组长度非法）；业务侧应分片查询；
2. bk_biz_id可选但建议显式指定：不指定时返回主机在全部业务下的挂载关系，结果可能跨业务展开，数据量与权限范围都会扩大；指定后仅在该业务内检索；
3. 结果按“主机 × 模块”逐条展开：一台主机挂载 N 个模块即返回 N 条记录，统计“去重主机数”时需对bk_host_id去重；
4. 权限：作为网关资源该接口默认不公开（isPublic: false），调用方需在蓝鲸 API 网关中申请该资源的调用权限，无权限时响应中的permission字段会返回申请所需信息；
5. 开发商账户隔离：查询自动叠加当前账户的bk_supplier_account过滤条件，跨开发商账户的数据不会互相可见。

典型应用场景

• 主机批量归属盘点：给定一批主机 ID，快速还原每台主机挂载的业务、集群、模块，用于资源归属审计与报表；
• 业务拓扑对账：结合bk_biz_id限定范围后，比对实际挂载关系与预期拓扑（如集群模板、模块模板规划）是否一致；
• 变更前置检查：在主机转移（如transfer_host_module、transfer_host_across_biz）前，先查询当前归属，评估影响面；
• 数据联动：配合 find_host_topo_relation、find_host_relations_with_topo 等主机拓扑类接口，可分别获取“主机 × 模块关系”与“主机 × 主线拓扑实例关系”，按需选择更细粒度的拓扑信息。

结语

find_host_biz_relations是 CMDB 主机模块挂载关系的最直接查询入口：对外通过蓝鲸 API 网关以POST /v2/cc/find_host_biz_relations/暴露，对内落到cc_ModuleHostConfig关系表，一次即可拿到主机在业务、集群、模块三维度的完整归属。把握“每批不超过 500 个主机 ID”“按主机 × 模块逐条展开”“可选业务过滤”这三个要点，即可在二次开发中稳定、高效地使用该接口完成主机归属查询类需求。

• 后端
• 企业应用
• 运维